Embedded Connection Widget implementation guide

The Embedded Connection Widget is an embedded iframe within the partner UI. The embedded iframe contains a login window for customers to authenticate their connections in Workato without leaving the partner's application. To implement the Embedded Connection Widget, construct a direct link URL and embed it within the iframe of the partner UI.

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
• Construct a direct link URL
• Embed the URL in an iframe
• PostMessage API

Prerequisites

To construct a direct link URL, use the following 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 PostMessage 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 Admin console > Manage customers to 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. For each Workato connection you want your customers to authenticate with the Widget, you need the connection's connection ID. If you don’t know the connection ID, obtain it by calling our list connections API (opens new window).

OTHER USEFUL WORKATO EMBEDDED APIS

• Get customer account
• Create customer account

• Data Center

• (Required) The base of the direct link URL depends on the data center you use. You must construct a direct URL formatted for the data center you use to embed the Connection Widget into the partner UI.

  • 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/

  • AU Data Center:

  • https://app.au.workato.com/

Configure URL parameters

Construct a direct link URL using 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 using the following code:

<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. This method 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 object 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 workflows, 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 of supported PostMessages

<!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>