# Embedded Connection Widget implementation guide
Implementing the Embedded Connection Widget involves constructing a direct link URL and embedding it in an iframe
in the partner UI. The embedded iframe
houses a login window for customers to authenticate their connections in Workato without leaving the partner's application.
The Embedded Connection Widget functions well in use cases where the Embedded partner builds and maintains integrations on their customers' behalf.
Automation Institute
Our Automation Institute course (opens new window) provides detailed instructions on implementing one of the Embedded Connection Widget's most common use cases.
This guide consists of the following sections:
# Prerequisites
JSON Web Token (JWT)
(Required) JWTs authenticate users and provide verified access to applications and resources. Generate a JWT to facilitate secure access to connections in Workato.
Origin URL
The origin URL is the default domain where you embed the Connection Widget
iframe
. This enables the parent window to receive messages through PostMessages API (opens new window). Provide your Workato Success Representative with the origin URL.Multiple origins
If you are embedding the Connection Widget in multiple domains, include the unique origin in the payload of the JWT. Additionally, you must configure the origin URL in each customer account. Go to the Admin console > Manage customers, and access the relevant customer account. Click the settings menu and update the origin URL.
Connection ID
(Required) Each Workato connection has a corresponding connection ID. Provide the connection ID for Workato connections you want your customers to authenticate using the Widget. If you don’t know the connection ID, obtain it by calling our list connections API (opens new window).
Other useful Workato Embedded APIs
Data Center
(Required) The base of the URL depends on the data center you use. To embed the Connection Widget into the partner UI you must construct a direct link URL formatted for the data center you use
US Data Center:
https://www.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/
# Configure URL parameters
Construct a direct link URL with the following structure:
https://<data_center>/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>
# Embed URL in an iframe
Embed the direct link URL in an iframe
in your application.
<iframe src="https://www.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>"></iframe>
# PostMessage API
Workato uses the window.PostMessage() (opens new window) method to send messages from the Connection Widget to your application which renders different UI states for the Embedded Connection Widget window. Post messages follow this format:
{ type: string, payload: object }
Test the Widget
If you are testing the Embedded Connection Widget for the first time, provide your Workato Customer Success Representative with the origin URL
. This enables the window to receive the messages through the PostMessage API.
# Supported PostMessages
# heightChange
Changes the height of the content, enabling the iframe
to adjust its size to match the partner's UI.
Payload:
{
height: number
}
Sample post message:
{
"wk": true,
"type": "heightChange",
"payload": {
"height": 467
}
}
# connectionStatusChange
Reports a change in connection status. Use this event to handle different work flows, including starting a recipe, calling external APIs, or other instances where the connection status changes.
Payload:
{
id: number,
provider: string,
connected: boolean,
error: string
}
Sample post message:
{
"wk": true,
"type": "connectionStatusChange",
"payload": {
"id": 453799,
"provider": "google_drive",
"connected": false
}
}
# error
Reports an error message.
Payload:
{
message: string
}
Sample Post message:
{
"wk": true,
"type": "error",
"payload": {
"type": "FatalEmbeddingError",
"message": "Fatal embedding error: sub_missing",
"details": {
"reason": "sub_missing"
}
}
}
# Example
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<script>
window.addEventListener('message', receiveMessage);
function receiveMessage(event) {
var data = JSON.parse(event.data);
switch (data.type) {
case 'heightChange':
document.getElementById('workatoId').style.height = data.payload.height + 'px';
break;
case 'connectionStatusChange':
var message = data.error || (data.payload.connected ? 'Connected' : 'Disconnected');
document.getElementById('statusId').innerText = message;
break;
case 'error':
console.log(data.payload.message);
}
}
</script>
</head>
<body>
<h4>Status: <span id="statusId"></span></h4>
<iframe id="workatoId" src="https://www.workato.com/direct_link/embedded/connections/<connection_id>>?workato_dl_token=<token>" style="width: 500px; height: 150px; border: 0"></iframe>
</body>
</html>
Last updated: 8/1/2023, 5:00:18 AM