ハウツーガイド: Config fieldsの使用

入力フィールドや出力フィールドがユーザー入力に依存する場合があります。たとえば、アクションの入力フィールドが同じアクション内のユーザー入力に依存する場合です。ここでは、config_fieldsを紹介します。これは、アクションとトリガーの両方で使用できるオプションのキーです。これは、他の依存する入力フィールドや出力フィールドを生成するために使用できる特殊なタイプの入力フィールドです。

TIP

Config fieldsキーは、アクションとトリガーの両方で使用して、コネクターに動的な動作を導入できます。

サンプルコネクタ - Chargebee

ruby

{
  title: "Chargebee",

  # More connector code here

  actions: {
    create_object: {
      title: "Create object",
      subtitle: "Create object in Chargebee",

      description: lambda do |input, picklist_label|
        "Create <span class='provider'>#{picklist_label['object'] || 'object'}</span> in <span class='provider'>Chargebee</span>"
      end,

      config_fields: [
        {
          name: "object",
          label: "Object",
          control_type: 'select',
          pick_list: "objects",
          optional: false
        }
      ],

      input_fields: lambda do |object_definitions, connection, config_fields|
        object = config_fields['object']

        object_definitions[object]
      end,

      execute: lambda do |connection, input|
        object = input.delete('object')

        # Route to the appropriate endpoint based on selected object
        endpoint = case object
        when 'customer'
          '/api/v2/customers'
        when 'subscription'
          '/api/v2/subscriptions'
        when 'plan'
          '/api/v2/plans'
        else
          raise "Unsupported object type: #{object}"
        end

        post(endpoint, input).
          request_format_www_form_urlencoded
      end,

      output_fields: lambda do |object_definitions, connection, config_fields|
        object = config_fields['object']

        object_definitions[object]
      end
    }
  },

  object_definitions: {
    customer: {
      fields: lambda do |connection, config_fields, object_definitions|
        get("/api/v2/customers", limit: 1).
          dig('list',0,'customer').
          map do |key, value|
            if value.is_a?(Integer)
              type = 'integer'
              control_type = 'number'
            else
              type = 'string'
              control_type = 'text'
            end

            {
              name: key,
              label: key.labelize,
              type: type,
              control_type: control_type,
              sticky: true
            }
          end
      end
    },

    subscription: {
      fields: lambda do |connection, config_fields, object_definitions|
        get("/api/v2/subscriptions", limit: 1).
          dig('list',0,'subscription').
          map do |key, value|
            if value.is_a?(Integer)
              type = 'integer'
              control_type = 'number'
            else
              type = 'string'
              control_type = 'text'
            end

            {
              name: key,
              label: key.labelize,
              type: type,
              control_type: control_type,
              sticky: true
            }
          end
      end
    },

    plan: {
      fields: lambda do |connection, config_fields, object_definitions|
        get("/api/v2/plans", limit: 1).
          dig('list',0,'plan').
          map do |key, value|
            if value.is_a?(Integer)
              type = 'integer'
              control_type = 'number'
            else
              type = 'string'
              control_type = 'text'
            end

            {
              name: key,
              label: key.labelize,
              type: type,
              control_type: control_type,
              sticky: true
            }
          end
      end
    }
  },

  pick_lists: {
    objects: lambda do
      [
        ["Subscription", "subscription"],
        ["Customer", "customer"],
        ["Plans", "plan"]
      ]
    end,
  }
}

Chargebee API

ステップ1 - アクションのタイトル、サブタイトル、説明、ヘルプ

優れたアクションを作成するための最初のステップは、アクションが何を行い、どのように実行するかを適切に伝え、ユーザーに追加のヘルプを提供することです。そのため、Workatoではアクションのタイトルと説明を定義し、ヒントを提供できます。簡単に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を示します。アクションの説明には、そのアクションが何を実現するかについての仕様と説明、および接続先アプリケーションのコンテキストが含まれます。最後に、ヘルプセグメントでは、アクションを機能させるために必要な追加情報をユーザーに提供します。

このステップの詳細については、SDKリファレンスを参照してください

ステップ2: config_fieldsの定義

config_fieldsキーを使用すると、エンドユーザーからいくつかの入力を最初に収集し、さらに入力フィールドを生成できます。このアクションでは、作成するオブジェクトをユーザーに最初に選択してもらい、その入力を使用して、選択したばかりのオブジェクトに関連するフィールドを生成します。

ruby

  config_fields: [
    {
      name: "object",
      label: "Object",
      control_type: 'select',
      pick_list: "objects",
      optional: false
    }
  ],

ここでは、選択ドロップダウン入力フィールドを示すselect control_typeを使用しています。このドロップダウンの有効なオプションは、objects picklistのSubscription、Customer、Plansです。

config-select Config fieldsはユーザーには入力フィールドのように表示されます

ステップ3: input_fieldsの定義

config_fieldsを定義したので、input_fields lambda関数に渡されるconfig_fields引数を利用できるようになります。この引数からObject入力ドロップダウンに指定された入力を参照し、適切なobject_definitionにルーティングできます。

ruby

  input_fields: lambda do |object_definitions, connection, config_fields|
    object = config_fields['object']

    object_definitions[object]
  end,

たとえば、ユーザーがドロップダウンでCustomer入力を選択した場合、input_fieldsキーはobject_definition['customer']を呼び出します。

ruby

  object_definitions: {
    customer: {
      fields: lambda do |connection, config_fields, object_definitions|
        get("/api/v2/customers", limit: 1).
          dig('list',0,'customer').
          map do |key, value|
            if value.is_a?(Integer)
              type = 'integer'
              control_type = 'number'
            else
              type = 'string'
              control_type = 'text'
            end

            {
              name: key,
              label: key.labelize,
              type: type,
              control_type: control_type,
              sticky: true
            }
          end
      end
    }
  },

object_definition['customer']キーはChargebeeにセカンダリリクエストを送信し、レスポンスをWorkatoスキーマに変換します。

config-select 顧客を選択すると追加フィールドが作成されます

ステップ4: executeキーの定義

executeキーは、リクエストの送信先エンドポイントと使用するHTTPリクエストメソッドをWorkatoに指示します。通常、オブジェクトごとに異なるエンドポイントへのPOSTが必要です。 APIにリクエストを送信する前に、inputハッシュからconfig field値を抽出します。

ruby

  execute: lambda do |connection, input|
    object = input.delete('object')

    # Route to the appropriate endpoint based on selected object
    endpoint = case object
    when 'customer'
      '/api/v2/customers'
    when 'subscription'
      '/api/v2/subscriptions'
    when 'plan'
      '/api/v2/plans'
    else
      raise "Unsupported object type: #{object}"
    end

    post(endpoint, input).
      request_format_www_form_urlencoded
  end,

この例では、次のようになります。

input.delete('object')を使用して選択されたオブジェクトを抽出します。これにより、値が返され、入力ハッシュから削除されます
case文を使用して、各オブジェクトタイプを対応するAPIエンドポイントにマッピングします
選択されたオブジェクトのエンドポイントに対して適切なPOSTリクエストを作成します
Chargebeeでは入力をform urlencodedにする必要があるため、.request_format_www_form_urlencodedを使用します

文字列補間を使用してルーティングを簡素化する

APIエンドポイントが一貫したパターン（/api/v2/{object}sなど）に従っている場合は、文字列補間を使用してルーティングを簡素化できます。

ruby

execute: lambda do |connection, input|
  object = input.delete('object')

  post("/api/v2/#{object}s", input).
    request_format_www_form_urlencoded
end,

エンドポイントパスが異なる場合や追加のロジックが必要な場合は、前の例に示す明示的なcase文アプローチを使用します。

ステップ5: 出力フィールドの定義

出力フィールドについては、ステップ3と同じロジックを使用して出力フィールドを生成します。

ruby

  output_fields: lambda do |object_definitions, connection, config_fields|
    object = config_fields['object']

    object_definitions[object]
  end

config-select 顧客を選択すると追加フィールドが作成されます

オブジェクト定義

object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。

この詳細については、SDKリファレンスを参照してください

Last updated:

ハウツーガイド: Config fieldsの使用 ​

サンプルコネクタ - Chargebee ​

ステップ1 - アクションのタイトル、サブタイトル、説明、ヘルプ ​

ステップ2: config_fieldsの定義 ​

ステップ3: input_fieldsの定義 ​

ステップ4: executeキーの定義 ​

ステップ5: 出力フィールドの定義 ​

ハウツーガイド: Config fieldsの使用

サンプルコネクタ - Chargebee

ステップ1 - アクションのタイトル、サブタイトル、説明、ヘルプ

ステップ2: config_fieldsの定義

ステップ3: input_fieldsの定義

ステップ4: executeキーの定義

ステップ5: 出力フィールドの定義