Workato embedded

Workato embedded allows all pages and elements on the Workato platform to be embedded within in an iframe built into the OEM partner’s platform UI. This allows for the most seamless end customer experience and brings the power of Workato's modern, low-code recipe building interface to your platform.

Alongside tools like the activity audit log, role-based access control, the Workato dashboard and more, your customers can build, test and monitor their integrations from within your platform.

Introduction

In this guide, we will show you how Workato embedded can be implemented within your platform.

A couple of key points to note:

  • The integration between Workato and the vendor is done via iframe - a native way to embed one webapp into another in a browser.

  • To better match vendor's page style and design, Workato provides a way to customize some of Workato's style properties like brand color, page margins etc.

  • We also provide the Workato Embedding Client script that is meant to simplify synchronization between Workato (embedded via iframe) and the vendor's webapp.

Configuration parameters

In order to provide seamless integration to the end-user, the OEM partner needs to provide Workato a few configuration parameters:

Parameter name Type Example value Description
Vendor origin Required https://vendor.com Origin (<url_schema>://<url_host>) of the vendor's webapp.
Embedding URL prefix Required /integration In order to provide the best user experience we need a way to synchronize Workato URL from the iframe with the URL of the vendor's webapp. To do so, vendor have to pick some embedding path prefix that will be used to generate vendor URLs from Workato URLs using this pattern: <embedding_url_prefix>/<workato_url>. For example if prefix is /integration and Workato URL is /foo?a=1#hash then corresponding vendor URL will be /integration/foo?a=1#hash.
Styling properties Optional See Styling documentation List of properties that customize Workato to better match vendor's design. See Styling documentation for more information.

Terms/Legend

We will introduce a few terms to make this guide clearer:

Links

  • Vendor: The OEM partner's web app is a vendor.
  • Vendor URL - all the URLs that belong to Vendor origin (https://vendor.com/*)
  • Embedding URL - all the vendor URLs that start with Embedding URL prefix (https://vendor.com/integration/*).
  • Embedding link - <a> element which points to an embedding URL.
  • Embedding iframe or just iframe - an <iframe> HTML element that contains embedded Workato webapp.
  • Embedding page - any page of the vendor's webapp which is located under embedding URL and contains an embedding iframe.

Vendor origin and Embedding URL prefix parameters are needed to convert all the links in the embedded Workato webapp into an embedding links.

For example, <a href="/foo?a=1#hash"> will become <a href="https://vendor.com/integration/foo?a=1#hash">.

This allows user to open proper embedding page when he wants to open a link in a new tab or in case of copying a link's URL.

Communication between apps

Communication between the iframe and the vendor webapp is done via browser's PostMessage API.

See EmbeddingWorkatoMessage for the complete list of messages that Workato sends to the vendor's webapp and EmbeddingVendorMessage for the list of messages that can be sent in the opposite direction.

In order to simplify communication between Workato and vendor's webapps we provide Workato Embedding Client. You can find more information about it below.

Workato Embedding Client

The Workato Embedding Client is a tiny script that simplifies communication between vendor's webapp and the embedded Workato platform.

It also provides a few helper methods that help with synchronization of Workato and embedding URLs.

In order to inject it into vendor's webapp you can follow these installation steps:

  1. Inject this script on every embedding page: <script src="https://embedding.workato.com/r/embedding-client.js">.

    There are a few important things to note:

    • It should be injected before the embedding iframe.
    • It shouldn't contain neither async nor defer attributes as it must be loaded synchronously before the iframe does.

    It creates a global Workato object that is an instance of the EmbeddingClient class.

  2. Insert the following configuration script right below the first one:

    <script>
      Workato.configure({
        // Value of `Embedding URL prefix` parameter
        embeddingUrlPrefix: '/integration'
      });
    </script>

That's it! Now you can use any property or method of the EmbeddingClient class.

For example you can use handleNavigation method to synchronize current Workato URL in the embedded iframe with current URL of the vendor's webapp or generateIFrameUrl method to generate a value for iframe's src attribute.

Check EmbeddingClient documentation for more information about available helper methods.

On This Page