Embedding Workato pages implementation guide

Embed Workato into your UI by constructing a direct link URL and embedding it in an iframe in your application. The embedded iframe can host any Workato page, 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 includes the following sections:

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

CUSTOMIZATION

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 Embedded for you.

Prerequisites

The following values are required to complete the steps in this guide:

• 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 is /integration/foo?a=1#hash.

• Workato path

• Required. This is the path to the Workato resource you plan 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 (opens new window)you use.

Construct a direct link URL

Construct a direct link URL. The format of the direct link URL varies depending on your data center:

Workato accounts hosted in the US Data Center

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

Workato accounts hosted in the EU Data Center

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

Workato accounts hosted in the JP Data Center

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

Workato accounts hosted in the SG Data Center

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

Workato accounts hosted in the AU Data Center

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

• Workato path

• Set this parameter to the Workato resource you plan 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.

WORKATO EMBEDDING CLIENT SCRIPT REQUIRED BEFORE IFRAME

The Workato Embedding Client script must be injected before any Workato iframes are embedded. You must ensure that the Workato Embedding Client loads synchronously before the embedded iframe does. After the script loads, a global Workato object is created which you can configure and use to call the available helper methods.

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.

• Workato accounts hosted in the US Data Center: https://embedding.workato.com/r/embedding-client.js
• Workato accounts hosted in the EU Data Center: https://embedding.workato.com/r/embedding-client-eu.js
• Workato accounts hosted in the SG Data Center: https://embedding.workato.com/r/embedding-client-sg.js
• Workato accounts hosted in the JP Data Center: https://embedding.workato.com/r/embedding-client-jp.js
• Workato accounts hosted in the AU Data Center: https://embedding.workato.com/r/embedding-client-au.js

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

2

Insert this 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 cannot 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.

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