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

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

  • Get customer account
  • Create customer account

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