Embedding Workato pages implementation guide

Embedding Workato into the partner UI involves constructing a direct link URL and embedding it in an iframe in the partner's application. The embedded iframe can host any of Workato's pages, including the recipe builder.

Workato's tools, including the activity audit log, role-based access control, and the Workato admin dashboard, enable customers to build, test, and monitor their integrations from within the partner's platform.

This guide consists of the following sections.

• Prerequisites
• Construct a direct link URL
• Embed the URL in an iframe
• Communication between apps
  • Workato Embedding Client

Customization

• Workato Embedded supports customization, enabling you to change some of Workato’s style properties. These include brand color to match your own UI, font, and margins. Contact your Workato Success Representative to customize Workato Embedded for you.

Prerequisites

JSON Web Token (JWT)

Required. Generate a JWT to facilitate secure access to connections in Workato. JWTs authenticate users and provide verified access to applications and resources.

Origin

Required. The origin URL (<url_schema>://<url_host>) is the default domain where you embed the Workato iframe. In specific cases, you must include the origin URL in the payload of the JWT. This enables the parent window to receive messages through PostMessages API. Provide your Workato Success Representative with the origin URL. Example: https://vendor.com.

Embedding URL prefix

Required. Partners must choose an embedding path prefix for generating URLs. Embedding URL prefixes follow this pattern: <embedding_url_prefix>/<workato_url> For example if the prefix is /integration and the Workato URL is /foo?a=1#hash, then the corresponding vendor URL will be /integration/foo?a=1#hash.

Workato path

Required. This is the path to the Workato resource you wish to embed in your platform.

Data center

Required. To embed Workato into the partner UI you must construct a direct link URL. The base of the direct link URL depends on the data center you use.

Data center

This variable depends on the data center you use.

• US Data Center: https://app.workato.com/
• EU Data Center: https://app.eu.workato.com/
• JP Data Center: https://app.jp.workato.com/
• SG Data Center: https://app.sg.workato.com/

Construct a direct link URL

Construct a direct link URL with the following structure:

https://app.workato.com/direct_link?workato_dl_path=<workato_path>&workato_
dl_token=<jwt_token>

Data center

Configure this variable based on your data center. The examples in this guide are configured for the US data center. If you use a different data center, you must replace app.workato.com with the variable that matches your data center.

Workato path

Set this parameter to the Workato resource you want to embed.

JWT token

Set this parameter to the generated JWT.

Embed the URL in an iframe

Embed the direct link URL in an iframe in your application.

<iframe src="https://app.workato.com/direct_link?workato_dl_path=<workato_path>&workato_
dl_token=<jwt_token>"></iframe>

Communication between apps

The partner application and the iframe communicate through PostMessage API (opens new window).

See EmbeddingWorkatoMessage (opens new window) for the complete list of messages that Workato sends to the vendor's web app and EmbeddingVendorMessage (opens new window) for the list of messages that the vendor's web app can send to Workato.

The Workato Embedding Client simplifies communication between Workato and vendor's web apps.

Workato Embedding Client

The Workato Embedding Client is a script that simplifies communication between the vendor's web app and the embedded Workato platform. It also provides a few helper methods that aid in synchronizing Workato and embedding URLs.

Follow these steps to insert the Workato Embedding Client into your web app:

1

Inject this script on every embedding page:

<script src="https://embedding.workato.com/r/embedding-client.js">

Data center

For the Embedding Client Script the data center variable appears at the end of the URL before .js.

• US Data Center: https://embedding.workato.com/r/embedding-client.js
• EU Data Center: https://embedding.workato.com/r/embedding-client-eu.js
• SG Data Center: https://embedding.workato.com/r/embedding-client-sg.js
• JP Data Center: https://embedding.workato.com/r/embedding-client-jp.js

This script creates a global Workato object that is an instance of the [[EmbeddingClient]] class.

2

Insert the following configuration script immediately following the preceding script:

<script>
  Workato.configure({
    // Value of `Embedding URL prefix` parameter
    embeddingUrlPrefix: '/integration'
  });
</script>

Best practice

• Insert the script before the embedding iframe.
• The script shouldn't contain async or defer attributes as it must load before the iframe.

Available methods

This script enables you to use all properties and methods of the EmbeddingClient class, including:

handleNavigation

Use the handleNavigation method to synchronize the Workato URL in the embedded iframe with the partner's web app's current URL.

generateIframeURL

Use the generateIframeURL method to generate a value for the iframe's src attribute.

Reference the EmbeddingClient (opens new window) documentation for additional helper methods.