# 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.
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 Workatoiframe
. 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:
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.
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
ordefer
attributes as it must load before theiframe
.
# 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
'ssrc
attribute.
Reference the EmbeddingClient (opens new window) documentation for additional helper methods.
Last updated: 8/1/2023, 5:00:18 AM