SDK での開発のベストプラクティス

ここにはカスタムコネクターの開発において構築、テスト、保守を容易にするベストプラクティスをまとめています。このベストプラクティスは、次のような分類となっています。

• 全般的なベストプラクティス
• ルートキーごとのベストプラクティス
• アクションのベストプラクティス
• トリガーのベストプラクティス
• 使いやすさとテストのベストプラクティス

---

全般

このベストプラクティスは、Workato SDK プラットフォーム上でカスタムコネクターを開発する際に直接役立つものです。

• コネクターはアプリケーションの名前をとって命名するとよいでしょう。そうすることで、自分自身や自分のワークスペースの共同作業者が、あなたの独自のカスタムコネクターを検索しやすくなります。

  • 標準/グローバルコネクターがすでに存在している場合、SDK には <app name> (Custom) という名前を付けるとよいでしょう。これにより、それがカスタム SDK コネクターであることが示されます。

• アクションを構築する際は、トリガーレベルやアクションレベルのヒントを提供しましょう。これにより、あなたのコネクターになじみのないユーザーでも、自分がどのアクションを選択すべきか理解できるようになります。

• 未使用の変数、メソッド、ピックリスト、object_definition (オブジェクト定義) をコネクターコード内に残さないようにしましょう。

• コードをクリーンで、読みやすく、分かりやすく、拡張可能な状態に保ちましょう。

  • Ruby の DRY 原則に従い、再利用可能なコードライブラリを目指してメソッドや object_definition を使用しましょう。

• 名前付きのオブジェクトやメソッドを宣言する際は、常に分かりやすい表現を選ぶように心がけましょう。

  • アクション、トリガー、ピックリスト、メソッド、変数を宣言する際は、命名規則としてスネークケースを採用してください。
  • 変数の宣言に、略語や特殊文字は使用しないでください。
  • コードの各ブロックが何を達成しようとしているのかを、ユーザーがその名前に基づいて理解できる必要があります。
  • アクションおよびトリガーの前には、その動作、特殊な指示、制限事項を伝えるコメントを記載しましょう。

• 各キー (メソッド、アクション、トリガー、ピックリストなど) 同士の間には、空行を挿入しましょう。そうすると、そのコードの改善に取り組む人にとって読みやすくなります。

• 複数の階層をたどってデータを参照したい場合は、dig メソッドを使用するとよいでしょう。詳細については、こちら (opens new window)を参照してください。

• 可能なときはいつでも、文字列連結 ("string" + "string") ではなく、#{} を使用しましょう。

  • #{} は、変数が宣言されていない場合でもエラーを発生させないため、よりディフェンシブです。

• 日付の項目と形式は慎重に使用し、必ずタイムゾーンに対応するようにしましょう。

• コード内で put を使用することは控えましょう。ただし、デバッガーコンソールの [Console] タブを使用してテストやデバッグを行う場合は、その限りではありません。

• HTTP レート制限のあるエンドポイントに対してトリガーやアクションを実装するのは避けましょう (トリガーについては特に厳格に)。

  • アクションが必要な場合は、コネクターコードではなくレシピ側でレート制限ロジックを扱ってください。

• それぞれのトリガーやアクションには、適切なアクションまたはトリガーの名前の付いた説明タグが必要です。

  • 標準的な規則: <action/trigger> <object> in <applicationName>
  • 例: Search invoices in Xero

---

ルートキーごと

• コネクション
• テスト
• オブジェクト定義

コネクション

• 機密データに対しては、control_type: password を使用してください。

• 認証 URL でスコープを要求できる OAuth 2.0接続の場合、コネクションの作成時にコネクターのユーザーが選択できる入力がこれに該当するはずです。

• サブドメインパラメータについてユーザー入力を要求する場合は、control_type: subdomain と URL を使用してください。

  • これにより、エンドユーザーにとって入力項目が使いやすくなり、ヒューマンエラーの可能性を最小限に抑えることができます。
  • 例:

    fields: lambda do |_connection, _config_fields|
      {
          name: 'sub_domain',
          control_type: 'subdomain',
          url: '.salesforce.com',
          optional: false,
          hint: 'Provide salesforce sub-domain for example, <code>test_instance</code>'
      }
    end
    

• コネクターの配布を考えている場合は、機密性の高い情報をコード内に含めないようにしましょう。

  • OAuth 2.0フローを通じて認証を行う際のクライアント ID やシークレットについては、これが特に重要となります。

• 時間経過で有効期限切れになる認証トークンに対しては refresh_token キーと detect_on キーを定義しましょう。初回の接続に成功しても、トークンの有効期限が切れると接続が切断される可能性があります。

• 正常な接続を確立するための資格情報を取得する方法について、ユーザーを支援する参照リンクを提供しましょう。

  • API キーやクライアント ID とシークレットを生成できる URL へのリンクを追加するといった簡単なことでも、カスタムコネクターのユーザーには大いに役立ちます。

• OAuth 2.0認証の認証 URL に必要なスコープが含まれていることを確認してください。

• type: "custom_auth" を使用する場合、acquire キーは detect_on または refresh_on がトリガーされた場合にのみ実行されます。acquire キーを使用してトークンをはじめとする資格情報を取得する場合は、適切なトークンが取得されないまま test キーが実行されたときに返されるエラーコードを用意してください。

• アプリが API の複数のバージョンを同時にサポートしている場合は、API のバージョンを記載してください。

• コネクションのハッシュに API URL を格納してください。

  • ベース URL が動的でテナント固有である場合は、acquire キーを使用して動的に base_url を取得しましょう。

• SDK がさまざまな環境をサポートする必要がある場合は、本番環境とサンドボックス環境から選択できるピックリストを使用しましょう。

• connection キー内の fields キーではピックリストを使用しましょう。接続の失敗につながる誤入力を防ぐことができます。

• (適用できる場合は) base_uri を使って API コールのベース URL を設定することで、トリガー、メソッド、およびピックリストで完全な URL を指定する必要性を回避できます。

  • 例:

  base_uri: lambda do |connection|
    if connection['custom_domain']
      "https://#{connection['custom_domain']}"
    else
      'https://go.trackvia.com'
    end
  end
  

• 静的な base_uri を使用するか、エンドポイントから base_url を取得しましょう (アカウント固有の base_url を返す API がある場合)。

テスト

• コネクションのテストには、特権とデータが最小限で済むエンドポイントを利用しましょう。

  • たとえば、「get(/profile/me)」のようなエンドポイントを利用した場合、これがメモリ内に保持するデータは最小限で済むでしょう。

• get メソッドを最小化し、テスト用のエンドポイント呼び出しで格納するデータを最小限に抑えましょう。

  • これにより、コネクションを正常に作成するのにかかる時間を短縮できます。
  • レシピを開始する前に、接続ステータスを検証しましょう。

オブジェクト定義

• 動的なオブジェクト定義は、静的なオブジェクト定義よりも推奨されます。

  • 動的なオブジェクト定義を採用すると、カスタムコネクターの保守作業を削減できます。接続先となるアプリケーションでユーザーがカスタム項目を作成できる場合は、特にこれが当てはまります。
  • 動的なオブジェクト定義は一般的に、接続先となるアプリのメタデータエンドポイントに HTTP リクエストを送信する方式を利用します。そのレスポンスを利用して、データを input_fields キーや output_fields キーで想定される形式に変換してください。

• オブジェクト項目の名前にはアンダースコア (_) 以外の特殊文字は使用できません。

• ラベルを使用すると、カスタムコネクターのエンドユーザーにとっての使いやすさが向上します。

  • たとえば、一部の API は、レスポンス内の項目に適切なラベルが付けられているメタデータエンドポイントを提供しています。たとえば、ターゲットアプリケーション内の項目に関するメタデータには、ID フィールドに加えて name フィールドが含まれている場合があります。この場合、Workato のオブジェクト定義内の name を ID に、Workato のオブジェクト定義内の label を name にマッピングすることで、エンドユーザーにとっての使いやすさを最大化できます。

• control_type を的確に使用して、ユーザーエラーを削減しましょう。

  • たとえば、日時の入力データを収集する場合、control_type として text ではなく date_time を使用しましょう。

• control_type が boolean、select、multi-select のときにはトグル項目を使用することが推奨されます。これを用いると、ユーザーがレシピの設計時に text 入力に切り替えてデータピルをマッピングできるようになります。

• トグルオプションを提供する場合は、許容されている値をトグルのヒントによって示すとよいでしょう。

  • 値の種類が少ない場合はそれをレシピの UI 上に一覧表示し、そうでない場合は適切なページにリンクを張って、トグル項目に使用できる値を示しましょう。

• 通貨の値に double や float が必要となる場合は、数値タイプを使用してください。

• 選択肢が性別、住所タイプ、通貨タイプのように静的である場合は、選択肢に静的な pick_list 値を使用してください。

---

アクション

• アクションには、明快な名前を付けましょう。

  • アクションの命名規則は次のとおりです。
    • Get - ID を通じて特定のレコードを1つだけ取得する
    • Search - 検索クエリーに基づいて0個、1個、またはそれより多くのレコードを返す
    • List - すべてのレコードをリスト出力する
    • Add - 新しいレコードを作成する
    • Create - 新しいレコードを作成する
    • Update - 既存のレコードを更新する
    • Upsert - 新しいレコードを作成するか、既存のレコードを更新する

• 必要なときは必ず input_fields の検証を行ってください。

  • 検証を実行して、エッジケースに対する保護措置を講じることは常に推奨されます。

• ユーザーへの特別な指示があれば、help タグを使用してそれを提供しましょう。

• execute ブロックでターゲットアプリケーションのエンドポイントを呼び出す際は、データを求めることのみを目的としてください。

  • メタデータの HTTP リクエストは、object_definitions 内で実行されているはずです。

• できる限りメソッドを利用して、冗長なコードを削減しましょう。

• after_response ブロックを使用して、cookie などのレスポンスヘッダー情報をキャプチャーしましょう。

• 任意のエンドポイントに使用できる CRUD 操作用のカスタムアクションをコネクターに用意することは良い慣行です。

• テーブル全体を削除したり、object_definitions に影響を与えたりするアクションは、Workato において推奨されません。

  • そうしたアクションは永続的な影響を及ぼし、データ損失につながる可能性があります。
  • このようなアクションについては慎重に検討してください。レシピを通して実行するのではなく、管理者がアプリケーション上で直接行うことをお勧めします。

---

トリガー

• 全般
• サンプル出力
• エラーハンドリング

全般

• トリガーの名前は、それが行う内容に応じた固有のものにしてください。

• たとえば、New employee in Replicon は、Replicon で新しい従業員が作成されたときに起動するトリガーです。

• トリガーの命名規則は次のとおりです。

  • New - オブジェクトの作成を検出するトリガー
  • New or updated - オブジェクトの作成または更新を検出するトリガー
  • Deleted - オブジェクトの削除を検出するトリガー

• 入力項目 Since は、ユーザーが過去のある時点からのデータを取得する際にしばしば役立ちます。

  • これは任意項目にすることができ、ユーザーはこれを利用して、最初にレシピを開始するときに過去からのレコードを取得できるようになります。
  • API は、set パラメータを用いて過去のある日付以降のレコードをクエリーできるようにすることで、これをサポートしていることが通例です。

• poll キーはトリガーの各ポーリングごとに少なくとも1回は実行されるため、このキー内での不要な API リクエストは避けてください。

• closure キーを使用して、クエリー項目、ページ番号、最後更新日時を格納しましょう (必要な場合のみ)。

  • クロージャでキャッシュされた情報は、ポーリング間隔を超えて保持されます。

• できる限りメソッドを利用して、冗長なコードを削減しましょう。

• Webhook URL をプログラム的にセットアップおよび破棄する機能を持つ API では、動的 Webhook を使用しましょう。

  • 代替手段としては静的 Webhook がありますが、そちらの場合は与えられた Workato の静的 URL を手動で登録する必要があります。

サンプル出力

• Workato レシピでは、どのアクションやトリガーにも、アプリデータセクション以下の出力データピルの隣にサンプル出力データを用意することが推奨されます。

  • そうすれば、ユーザーは下流のシステムで利用するデータについて理解できるようになり、使いやすさも向上します。

• 項目数の少ないオブジェクトでは、静的なサンプル出力データをお勧めします。

  • 動的なサンプル出力は、大量の項目があるオブジェクトで使用するとよいでしょう。
  • サンプルデータを表示するためのデータ変換や API コールが sample_output キー内で多くなりすぎないようにしましょう。
  • ファイルのダウンロードアクションでは、sample_output キー内で静的データを使用しましょう。

• それぞれのトリガーやアクション (出力) にサンプルデータが含まれていることを確認してください。

  • これは、各データピルの横に灰色のテキストで表示されます。
  • トリガーに1つも入力項目がない場合は、2番目のアクションが追加されるまでデータツリーは表示されません。

エラーハンドリング

• raise メソッドを利用して例外を通知しましょう。

• API がエラーを返すのを待つのではなく、早いうちに検証エラーを捕捉しましょう。

• SDK で特定のエラーコードを処理し、独自のレスポンスを定義する必要がある場合は、エラーハンドリングを実装してください。

• 例外を抑制するのは避けましょう。API 情報は隠さずに明示した方がよいでしょう。

---

使いやすさとテスト

• 全般
• 使いやすさのルール

全般

• アクションおよびトリガーについて、レシピの UI を確認しましょう。

• アクション名、トリガー名、ラベル、ヘルプの指示の目的がエンドユーザーに明確に伝わるようにしてください。

• レシピを作成することで、カスタムコネクターのエンドツーエンドのテストをセットアップするようにしましょう。

  • これが特に有用となるのは、まず最初にサンドボックス環境を使って新しいバージョンのコネクターをレシピ内でテストし、それからコネクターを本番ワークスペースにプッシュする場合です。

使いやすさのルール

オブジェクトベースのアクションおよびトリガーの作成の背後にある概念については学んだので、今度はそれをデバッガーコンソール内だけでなく、レシピとして使用してテストしてみましょう。この段階まで来ると、コネクターの一部の要素が、期待していたほどには使いやすくないことに気付くかもしれません。優れたコネクターは、コードとして適切に構成されているだけではなく、レシピ作成エクスペリエンス全体の中でとりわけユーザーエクスペリエンスを重視しています。優れたコネクターとユーザーフレンドリでないコネクターを区別するルールを以下に挙げます。

1

説明となるヘルプテキスト

2

ユーザーフレンドリな入力項目

3

説明となるエラーメッセージ

説明となるヘルプテキスト

アクションのヘルプテキストは、あなたが構築したアクションについての知識が不足しているユーザーが、それを補うために重要です。以下に、アクションのヘルプテキストに含めるべき重要な事項を挙げます。

• サポートされている API バージョン
• オブジェクト固有のヘルプ
• ドキュメントへのリンク
• 項目レベルのヒント
• 項目レベルのヘルプ

サポートされている API バージョン

接続先アプリケーションの API バージョン。これはユーザーの期待を管理するのに役立ちます。これが提供されていると、ユーザーはコネクターの機能について何を期待できるかに関する理解を深めることができます。

オブジェクト固有のヘルプ

オブジェクトが異なれば、必要とされるアクションレベルのヘルプヒントも異なる可能性があります。ヘルプテキストは、ユーザーが選択したオブジェクトに基づいて簡単に変更できます。

help: lambda do |input, picklist_label|
  if input['object'] == 'invoice'
    {
      body: "Creates an invoice in XYZ. Invoices in XYZ accounting are essential " \
      "components of the platform. This action supports the creation of invoices " \
      "including custom fields",
      learn_more_url: "docs.xyz.com",
      learn_more_text: "Learn to setup this action"
    }
  else
    {
      body: "Creates an object in XYZ. First, select from a list of " \
      'objects that we currently support. After selecting your object,' \
      ' dynamic input fields specific to the object selected ' \
      'will be populated.'
    }
  end
end,

ドキュメントへのリンク

ユーザーがそのアクションの設定方法についてさらに情報を必要としている場合、ヘルプテキストには適切なドキュメントへのリンクを含めることもできます。

ドキュメントへのリンクは、狭いスペースにすべての情報を含めることができない場合にユーザーの役に立つ

項目レベルのヒント

ヒントは、特定の入力項目の使用方法をユーザーに示すための基本的な方法です。想定されている入力について、ユーザーに情報を提供してください。たとえば、タイムスタンプを特定の日付フォーマット (iso8601 や DD/MM/YYYY) にする必要があるかどうかなどです。

項目レベルのヘルプ

ユーザーが適切にアクションを設定する上で項目レベルのヘルプを読むことが重要となる場合は、それを使用することをお勧めします。これは慎重に使用する必要があります。

[
  {
    control_type: "text",
    label: "Txn date",
    type: "string",
    name: "TxnDate",
    optional: true,
    sticky: true,
    help: {
      title: "Extra info",
      text: "This field is super important"
    }
  }
]

項目レベルのヘルプを利用して特定の項目に注意を向ける

ユーザーフレンドリな入力項目

ここでは、コネクターを微調整して可能な限りユーザーフレンドリにするために役立つ簡単なルールを示します。これらのルールは、Workato が各コネクターに対して実施する UI/UX レビューでも重視される点なので、最終的に Workato のプラットフォーム上で世界中に公開することを目的としてコネクターを作成する場合には特に重要となります。

1. 入力項目のラベルは十分分かりやすいものになっていますか。入力項目にラベルを定義する際は、エンドユーザーがあなたと同じ認識を持てるよう、できるだけ明確なものにしてください。 項目の name は id でも構いませんが、ラベルは Invoice ID に変更しておくと、エンドユーザーはその役割を速やかに理解できるようになります。

2. 入力項目の type と control_type は正確ですか。type と control_type は、ユーザーが自分の扱っている値の種類を把握するのに役立ちます。Workato では、何も定義されていない場合、type と control_type はデフォルトでそれぞれ文字列とテキストになります。

3. ラベルを変更してもまだ曖昧な入力項目に対して、ヒントを宣言しましたか。ヒントの使用は、ユーザーにさらなるガイドを提供する優れた方法です。HTML 形式のリンクも使用できます。

4. この入力項目は、定義された値の集合のみを受け入れますか。選択ドロップダウンを用いると、ユーザーは回答を手動で入力しなくても済むようになり、正しい入力を指定しやすくなります。これにより、ユーザーが直面するエラーの数も削減されます。

5. この入力項目は ID 値を受け入れますか。たとえば、XYZ 会計の create invoice アクションは、関連するカスタマーの ID を受け入れる入力項目を要求するとしましょう。そしてユーザーには手元にカスタマー ID がなく、代わりにカスタマーの名前があるとしましょう。そのような場合は、入力項目をピックリストにすることを検討してください。そのリストにラベルとしてカスタマー名を表示し、カスタマー ID は値として提供するようにするとよいでしょう。

6. ドロップダウンを使用する場合は toggle_field オプションも必ず含めるようにしてください。そうすることで、ユーザーは必要に応じてデータピルをマッピングできるようになります。ドロップダウンは優れていますが、ユーザーはデータピルをマッピングしなければならない場合もあります。また、toggle_hints を適切な形に変更することも忘れないでください。

7. このドロップダウンはコンフィギュレーション項目ですか。そうであれば、補助的なトグル項目で control_type を plain-text に設定し、データピルがマッピングされないようにしてください。コンフィギュレーション項目はデータピルを受け入れることができません。これは、アクション内の他の入力項目がコンフィギュレーション項目の情報に依存しているためです。

8. アクションまたはトリガー内の必須フィールドすべてに、必要に応じてラベルが付けられていますか。ユーザーは、このアクションを有効にするために入力する必要のあるフィールドがどれであるかを速やかに理解できる必要があります。

9. よく使用される任意項目はありますか。そのような項目は固定表示にすると、エンドユーザーは注意を引きつけられ、それを探す必要がなくなります。

10. コネクターのエンドユーザーのために、カスタム項目の可能性のある項目を動的に取得していますか。それぞれのカスタム項目で custom パラメータを使用し、どの項目が標準でどの項目がカスタムであるかについてユーザーにフィードバックを提供してください。

入力項目のそれぞれについて、以上の質問を簡単に確認しておくことをお勧めします。一度慣れれば、スキーマ定義に戻って変更を加える前に、このプロセスを通して調整が必要な入力項目を見つけ出せるようになります。

分かりやすいエラーメッセージ

分かりやすいエラーメッセージは、エンドユーザーにとって、レシピ作成エクスペリエンスの重要な一部となります。適切なエラーメッセージがないと、ユーザーはレシピが失敗する原因が分かるまで苦労することになります。Workato でエラーを表示させる方法について確認していない場合は、エラーハンドリングガイドをチェックしてください。

コネクターに適切なエラーハンドリングを導入するための一般的なルールを以下に示します。

1. コネクターでピックリストまたは何らかの種類の動的スキーマを使用していますか。after_error_response 関数をチェーンさせることにより、ユーザーは何が問題だったのかについて正確な情報を受け取れるようになります。例はこちらを参照してください。

2. あなたのコネクターには開始日と終了日など、同時に要求される特定の項目がありますか。そのような項目が求められないこともありますが、一部の項目はしばしば同時に要求されます。そのような場合は検証を行うことで、そのエラーを表面化させることができます。また、これは不要な API コールを削減するのにも役立ちます。例はこちらを参照してください。

3. 接続先の API は、適切な HTTP ステータスコードで応答していますか。一部のケースでは、実際にはエラーであるのに HTTP ステータスが 200 となっているレスポンスが API によって返される場合があります。そのような場合は after_error_response 関数を使用することで、ユーザーに問題を明らかにすることができます。例はこちらを参照してください。