Workato埋め込み実装ガイド ​

Workatoの埋め込みオプションを使用すると、強力なツールをプラットフォームに統合できます。 これにより、連携の構築、管理、監視において、カスタマイズされたシームレスなユーザーエクスペリエンスを提供できます。

direct link URLを構築してiframe内に埋め込むことで、WorkatoをアプリケーションのUIに埋め込むことができます。 Workatoでは、この目的のために2種類のiframesを提供しています：

フルページiframe ​

フルページiframesでは、目的のページへの直接URLパスをiframe内で指定することで、任意のWorkatoページを埋め込むことができます。 この方法では、Workatoナビゲーションバーを表示せずにページのコンテンツを表示できます。

Acme ERP内のWorkatoプロジェクトページのフルページiframe

ウィジェットiframe ​

ウィジェットiframesでは、アプリケーションにシームレスに統合される、特定機能に特化したウィジェットを埋め込むことができます。 次のウィジェットタイプから選択できます：

コネクションウィジェット ​

コネクションウィジェットを使用すると、製品内で直接、任意のWorkato connector用の認証情報を顧客から安全に収集できます。 このウィジェットは、Managed Servicesの提供の一部として、またはプラットフォーム上のより大きな連携セットアップジャーニー内で使用します。

Acme ERP内のSalesforce connectorのコネクションウィジェット

コネクションウィジェットのエラー通知 ​

コネクションウィジェットでは、特定の問題が発生したときに次の通知が表示されます：

• コネクションの切断

• 変更された認証情報または権限不足によりコネクションが無効になった場合に表示されます。 必要な権限があることを確認し、コネクションの認証情報を検証してください。
  コネクションの切断

• 監査ログレプリケーションコネクション

• コネクションへの変更が監査ログデータのストリーミングに影響する可能性があることを示します。

• 外部シークレットマネージャー

• コネクションへの変更が、外部プロバイダーに保存されたシークレットの使用に影響する可能性があることを示します。

コネクションウィジェットのカスタマイズ ​

コネクションウィジェットをカスタマイズして、機密情報を保護し、事前設定済み設定への変更を防ぎ、フィールド値を事前入力できます。

これらのカスタマイズを適用するには、コネクションの作成またはコネクションの更新APIを呼び出す際に、input_schema_ui_extensionsオブジェクトを渡します。 このスキーマでは、ネストされたプロパティを含むフィールドをロックまたは非表示にできます。 ウィジェットはレンダリング時にこれらの設定を自動的に適用します。

次のリクエスト例は、カスタマイズされたコネクション設定を示しています：

curl -X POST https://www.workato.com/api/managed_users/:managed_user_id/connections \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "databricks",
    "name": "My databricks connection",
    "folder_id": 147,
    "input": {
      "url": "http://oem.databricks.com",
      "password": "Testpwd1234",
      "profile": "Test Profile"
    },
    "input_schema_ui_extensions": {
      "url": {
        "locked": true
      },
      "password": {
        "hidden": true
      },
      "poolingx": {
        "properties": {
          "minSize": {
            "locked": true
          }
        }
      }
    }
  }'

コネクションを作成した後、返されたコネクションidを使用してウィジェットを埋め込みます。 ウィジェットは、コネクションで定義されたカスタマイズ済みフィールド動作でレンダリングされます。

レシピウィジェット ​

レシピウィジェットを使用すると、個別のレシピページに特化した簡素なビューを埋め込むことができます。 このウィジェットは、上部ナビゲーションやサイドパネルなどの必須ではない要素を削除しながら、レシピ、ジョブ、バージョンのコアタブを保持し、アプリケーション内でシームレスな構築エクスペリエンスを提供します。

Acme ERP内の個別レシピのレシピウィジェット

dynamic field mappingウィジェット ​

dynamic field mapping機能を使用すると、コアレシピロジックを変更せずに、ソースシステムのフィールドをレシピ内の宛先ステップにマッピングできます。 このウィジェットは、埋め込み連携内のフィールド関係を管理するための構造化されたインターフェイスを提供します。

Acme ERP内のdynamic field mappingウィジェット

埋め込みガイドライン ​

フルページおよびウィジェットiframesの埋め込みは、同じ実装手順に従います。

Workatoのiframesを使用すると、顧客のワークスペースを製品のUIに埋め込むことができますが、管理者ワークスペースの埋め込みはサポートされていません。

埋め込みiframeに特定のユーザー権限を反映するには、JWTにカスタムロールを持つcustomer user IDを含めます。 これにより、iframeはユーザーに割り当てられたロールおよび権限に準拠します。 たとえば、ユーザーがレシピを編集できない状態で表示できるように設定できます。 このアプローチにより、ユーザーごとにカスタマイズされた、権限に応じたエクスペリエンスを提供できます。

この実装ガイドには、次のセクションが含まれています：

• 前提条件
• direct link URLの構築
• URLをiframeに埋め込む
• アプリ間の通信
  • コネクションウィジェットでサポートされるPostMessages
  • Workato Embedding Client

前提条件 ​

Workatoを埋め込む前に、次の前提条件を満たしていることを確認してください：

• JSON Web Token（JWT）

• 必須。 Workatoでコネクションへの安全なアクセスを容易にするには、JWTを生成します。 JWTはユーザーを認証し、アプリケーションとリソースへの検証済みアクセスを提供します。

• Origin

• 必須。 origin URL（<url_schema>://<url_host>）は、Workatoiframeを埋め込むデフォルトドメインです。 特定のケースでは、JWTペイロードにorigin URLを含める必要があります。 これにより、親ウィンドウはPostMessages APIを通じてメッセージを受信できます。 origin URLをWorkato Success Representativeに提供してください。 例：https://vendor.com。

• Embedding URL prefix

• フルページiframeに必須。 URLの埋め込みパスプレフィックスを<embedding_url_prefix>/<workato_url>形式で選択します。 たとえば、プレフィックスが/integrationでWorkato URLが/foo?a=1#hashの場合、vendor URLは/integration/foo?a=1#hashです。

• Workatoパス

• 必須。 プラットフォームに埋め込む予定のWorkatoリソースへのパスを定義します。

• データセンター

• 必須。 Workatoアカウントをホストしているデータセンターに基づいて、direct link URLを構築します。 詳細については、データセンターページを参照してください。

direct link URLの構築 ​

Workatoコンテンツを埋め込むには、まずdirect link URLを作成します。 URL形式は、WorkatoアカウントがホストされているData Centerと、埋め込むiframeのタイプによって異なります。 データセンターに適した正しいベースURLを使用してください。

データセンター別のベースURL ​

次のベースURLは、各Workato Data Centerに対応しています。 データセンターの場所に一致するベースURLを選択します：

• US Data CenterでホストされているWorkatoアカウント：https://app.workato.com
• EU Data CenterでホストされているWorkatoアカウント：https://app.eu.workato.com
• JP Data CenterでホストされているWorkatoアカウント：https://app.jp.workato.com
• SG Data CenterでホストされているWorkatoアカウント：https://app.sg.workato.com
• AU Data CenterでホストされているWorkatoアカウント：https://app.au.workato.com
• IL Data CenterでホストされているWorkatoアカウント：https://app.il.workato.com
• CN Data CenterでホストされているWorkatoアカウント：https://app.workatoapp.cn
• KR Data CenterでホストされているWorkatoアカウント：https://app.kr.workato.com

iframeタイプ別のURL構築 ​

正しいベースURLを特定したら、次の形式を使用して、特定のiframeタイプのURL構造を完成させます：

フルページiframe ​

フルページを埋め込むには、次のURL構造を使用します：

https://<base_url>/direct_link?workato_dl_path=<workato_path>&workato_dl_token=<jwt_token>

コネクションウィジェット ​

コネクションウィジェットを埋め込むには、次のURL構造を使用します：

https://<base_url>/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

レシピウィジェット ​

レシピウィジェットを埋め込むには、次のURL構造を使用します：

https://<base_url>/direct_link/embedded/recipes/<recipe_id>?workato_dl_token=<jwt_token>

dynamic field mappingウィジェット ​

dynamic field mappingウィジェットを埋め込むには、次のURL構造を使用します：

https://<base_url>/embedded/recipes/<recipe_id>/field_maps?workato_dl_token=<jwt_token>

URLをiframeに埋め込む ​

正しいdirect link URLを生成した後、次の形式を使用してアプリケーション内のiframeにURLを埋め込みます：

<iframe src="https://<base_url>/direct_link?workato_dl_path=<workato_path>&workato_dl_token=<jwt_token>"></iframe>

アプリ間の通信 ​

スムーズなやり取りを確保するには、iframeとパートナーアプリケーションが安全に通信する必要があります。 WorkatoはPostMessage APIを使用して、アプリと埋め込みiframe間のクロスオリジン通信を容易にします。

アプリケーションとiframe間の通信を実装またはトラブルシューティングするには、次のメッセージリストを参照してください：

• WorkatoがWebアプリに送信するメッセージの完全なリストについては、EmbeddingWorkatoMessageを参照してください。

• WebアプリがWorkatoに送信できるメッセージのリストについては、EmbeddingVendorMessageを参照してください。

アプリと埋め込みiframe間の通信を効率化するには、Workato Embedding Clientを使用します。 このクライアントは、メッセージを効率的に送受信するためのヘルパーメソッドを提供します。

コネクションウィジェットでサポートされるPostMessages ​

Workatoはコネクションウィジェット専用に次の2つのPostMessagesをサポートしており、動的な調整と通信を可能にします。

heightChange ​

heightChangeイベントはコンテンツの高さを調整し、iframeがUIに合わせてサイズ変更できるようにします。

• ペイロード：

  json

  {
     "height": number
  }

• サンプルPostMessage：

  json

  {
      "wk": true,
      "type": "heightChange",
      "payload": {
          "height": 467
      }
  }

connectionStatusChange ​

connectionStatusChangeイベントは、コネクションステータスの変更を報告します。 このイベントを使用して、コネクションステータスが更新されたときに、レシピの開始や外部APIの呼び出しなどのワークフローをトリガーできます。

• ペイロード：

  json

  {
    "id": number,
    "provider": string,
    "connected": boolean,
    "error": string
  }

• サンプルPostMessage：

  json

  {
      "wk": true,
      "type": "connectionStatusChange",
      "payload": {
          "id": 453799,
          "provider": "google_drive",
          "connected": false
      }
  }

error ​

errorイベントは、iframeからのエラーメッセージを報告します。

• ペイロード：

  json

  {
    "message": string
  }

• サンプルPostMessage：

  json

  {
    "wk": true,
    "type": "error",
    "payload": {
      "type": "FatalEmbeddingError",
      "message": "Fatal embedding error: sub_missing",
      "details": {
        "reason": "sub_missing"
      }
    }
  }

サポートされているPostMessagesの例 ​

次の例は、サポートされている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>

Workato Embedding Client ​

Workato Embedding Clientスクリプトにより、Webアプリと埋め込みWorkatoプラットフォーム間の通信を効率化できます。 埋め込みiframeとURLをシームレスに同期するためのヘルパーメソッドを提供します。

Workato Embedding ClientをWebアプリに挿入するには、次の手順を実行します：

<script src="https://embedding.workato.com/r/embedding-client.js">

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

利用可能なメソッド ​

Workato Embedding Clientスクリプトを使用すると、次の主要メソッドを含むEmbeddingClientクラスのすべてのプロパティとメソッドを使用できます：

• handleNavigation

• 埋め込みiframe内のWorkato URLをパートナーWebアプリの現在のURLと同期するには、handleNavigationメソッドを使用します。

• generateIframeURL

• iframeのsrc属性の値を生成するには、generateIframeURLメソッドを使用します。

追加のヘルパーメソッドについては、EmbeddingClientドキュメントを参照してください。