カスタム ワークフロー アクション
HubSpotのワークフローツールを使用してビジネスプロセスを自動化すれば、チームの効率向上を図ることができます。カスタム ワークフロー アクションを作成すると、貴社のサービスとHubSpotワークフローを連携させることができます。
カスタムアクションを設定すると、ユーザーがアプリケーションをインストールする際に、そのカスタムアクションをワークフローに追加できます。
このワークフローが実行されると、設定済みのURLにHTTPSリクエストが送信され、設定したペイロードが提供されます。カスタムアクションに対するリクエストには、「X-HubSpot-Signature」のv2バージョンが使用されます。HubSpotからのリクエストを検証する方法をご確認ください。
以下のセクションまでスキップすることもできます。
- 始める前に
- カスタムアクションの定義
- 関数
- 入力フィールド
- 外部データフィールドのフェッチ(取得)
- 出力フィールド
- ラベル
- 実行
- カスタムアクションの非同期実行
- 実行ルールによるカスタム実行メッセージの追加
- カスタムアクションのテストと公開
- HubSpotアプリで使用するHubSpot開発者アカウントが必要です。貴社のアプリのロゴがカスタムアクションのアイコンとして使用されます。
- カスタム ワークフロー アクションのエンドポイントにリクエストを送信する際は、リクエストURLにHubSpot開発者アカウントキー(英語)を含める必要があります。例:
https://api.hubspot.com/automation/v4/actions/{appId}?hapikey={API_key}
カスタム ワークフロー アクションを作成するには、以下のフィールドを使用してアクションを定義する必要があります。アクションの定義では、HubSpotから送信されるリクエストの形式と、サービスから返されるレスポンスの処理も指定します。
actionUrl
:アクションを実行する際のHTTPSリクエストの送信先URL。リクエスト本文には、どのユーザーに代わってアクションが実行されているか、入力フィールドにどのような値が入力されているかに関する情報が格納されます。objectTypes
:アクションで処理できるCRMオブジェクト。published
:既定では、カスタムアクションは未公開の状態で作成されます。未公開のアクションは、HubSpotアプリケーションに関連付けられている開発者ポータルにのみ表示されます。カスタムアクションをユーザーに対して表示するには、アクション定義のpublishedフラグを更新してtrueにします。inputFields
:アクションに渡す入力。これらのフィールドの値は、ユーザーによって入力されます。inputFieldDependencies
:他のフィールドが特定の条件を満たすまでフィールドがグレーアウトされるようにするためのルール。outputFields
:アクションによって出力する値。この値は、ワークフローの後続のアクションで使用できます。カスタムアクションの出力はゼロにすることも、1つまたは複数にすることもできます。objectRequestOptions
:actionUrlへのペイロードに含まれる、登録されたオブジェクトのプロパティー。labels
:アクションのフィールドが表す内容とそのアクションの動作をユーザーに説明するための記述。英語のラベルは必須ですが、次のどの対応言語のラベルも併せて指定できます:フランス語(fr
)、ドイツ語(de
)、日本語(ja
)、スペイン語(es
)、ブラジルポルトガル語(pt-br
)、オランダ語(nl
)。executionRules
:ワークフローを作成するユーザーに対し、貴社のサービスからのエラーを示すために指定できる定義のリスト。functions
:送信されるペイロードをURLに変換したり、URLから返されるレスポンスを変換したりするために実行するコードスニペット。
カスタムアクションの定義の例
上記の定義により、ワークフローツールでは、出力が次のように表示されます。
カスタム ワークフロー アクションで行われる呼び出しには、次の2種類があります。
- フィールド オプション フェッチ:ユーザーがフィールドを設定する際に有効なオプションのリストを取得します。フィールド オプション フェッチを使用して外部データフィールドをフェッチ(取得)する方法の詳細をご確認ください。
- アクション実行リクエスト:カスタムアクションを含むワークフローによってアクションが実行されると、このリクエストが送信されます。
関数は、APIへの送信前にペイロードを修正するために使用されるコードのスニペットです。また、APIから返された結果を解析するためにも関数を使用できます。HubSpotの関数には、AWS Lambdaが利用されています。以下のコードでは、次の要素が使われています。
event
は、関数に渡されるデータを格納します。exports.main
は、関数が実行されるときに呼び出されるメソッドです。callback
関数は、結果を返すために使用できます。
このコードは、次の形式になります。
関数を設定する際、functionSource
の形式は文字列になります。コード内の文字はエスケープされるようにしてください。
一般に、関数の定義は次の形式になります。
使用される関数:
想定される出力:
入力フィールドの定義は、以下の形式に従います。
name
:入力フィールドの内部名。フィールドのラベルとは異なります。UIに表示されるラベルは、カスタムアクション定義のlabelsセクション使用して定義する必要があります。type
:入力に必要な値の型。fieldType
:入力フィールドをUIでレンダリングする方法。入力フィールドは、CRMプロパティーと同様にレンダリングされます。有効なtype
とfieldType
の組み合わせについて詳細をご確認ください。supportedValueTypes
に有効な値は2つあります。OBJECT_PROPERTY
:ユーザーが登録されたオブジェクトからプロパティーを選択するか、フィールドの値として使用する、先行アクションによる出力を選択できます。STATIC_VALUE
:上記以外の場合は常にこの値を使用します。これは、ユーザー自身が値を入力する必要があることを意味します。
isRequired
:ユーザーが入力フィールドの値を入力することが必須かどうかを指定します。
入力フィールドの定義は、次の形式になります。
ユーザーに選択してもらうオプションをハードコードすることもできます。
optionsURL
に送信されるペイロードは、次の形式になります。
想定されるレスポンスは、次の形式になります。
上記のコードの例では、データのフェッチによって返されるオプションの数を制限するためにページネーションが設定されていることに留意してください。これにより、ワークフローに対してさらに多くのオプションの読み込みが可能であることを示すことができます。
また、searchable:true
を含めることで、オプションのリストを検索可能にすることができます。
外部データを管理するには、フィールド オプション フェッチのライフサイクルをカスタマイズするための2つのフックを組み込むことができます。
PRE_FETCH_OPTIONS
:HubSpotから送信されるペイロードを構成するための関数。POST_FETCH_OPTIONS
:貴社のサービスから返されるレスポンスを、HubSpotで理解できる形式に変換するための関数。
この関数を組み込むと、各入力フィールドに適用されます。関数の定義でその入力フィールドのid
を指定することで、特定の入力フィールドにこの関数を適用できます。
HubSpotから送信されるペイロードは、次の形式になります。
この場合、レスポンスは次の形式になります。
外部データフィールドに従って想定される形式にレスポンスを解析するには、POST_FETCH_OPTIONS
関数を使用します。POST_FETCH_OPTIONS
関数の定義は、PRE_FETCH_OPTIONS
関数と同じです。外部データのフェッチオプションが定義されている場合、アクションの入力オプションにドロップダウンメニューがレンダリングされます。
関数への入力は、次の形式になります。
関数からの出力は、次の形式になります。
カスタムアクションによって値を出力し、その値を他のアクションで使用するには、出力フィールドを使用します。出力フィールドの定義は、入力フィールドの定義と同様です。
- name:カスタムアクションの他の部分でこのフィールドを参照する方法。UIに表示されるラベルは、カスタムアクションの「labels」セクションを使用して定義する必要があります。
- type:入力に必要な値の型。
- fieldType:入力フィールドをUIでレンダリングする方法。入力フィールドは、CRMプロパティーと同様にレンダリングされます。有効な
type
とfieldType
の組み合わせについて詳細をご確認ください。
出力フィールドは、次の形式になります。
出力フィールドを使用する場合、その値はactionURL
から返されるレスポンスから解析されます。例えば、出力フィールドをHubSpotの既存のプロパティーにコピーできます。
ワークフローエディターで、ラベルを使用して出力や入力にテキストを追加できます。ラベルはHubSpotの言語サービスに読み込まれるため、表示されるまでに数分かかる場合があります。異なる地域や言語に設定されたポータルサイトでは、対応する言語のラベルがあれば、そのラベルが表示されます。
labels
:アクションのフィールドが表す内容とそのアクションの動作を説明する記述。英語のラベルは必須ですが、次のどの対応言語のラベルも併せて指定できます:フランス語(fr
)、ドイツ語(de
)、日本語(ja
)、スペイン語(es
)、ブラジルポルトガル語(pt-br
)、オランダ語(nl
))のラベルを指定することもできます。actionName
:ワークフローエディターの[アクションを選択]パネルに表示するアクションの名前。actionDescription
:ユーザーがカスタムアクションを設定する際に表示されるアクションの詳細な説明。actionCardContent
:アクションのカードに表示する説明の要約。appDisplayName
:アプリの全てのアクションが表示される、[アクションを選択]パネルのセクションの名前。複数のアクションでappDisplayNameが定義されている場合、最初に見つかった名前が使用されます。inputFieldLabels
:「inputFields」の定義を、該当する(ユーザーがアクションを設定する際に表示される)ラベルと結び付けるオブジェクト。outputFieldLabels
:「outputFields」の定義を該当する(ワークフローツールに表示される)ラベルと結び付けるオブジェクト。inputFieldDescriptions
:「inputFields」の定義を、該当するラベルの下に表示される説明と結び付けるオブジェクト。executionRules
:「executionRules」の定義を、ワークフロー履歴のアクション実行結果に表示されるメッセージと結び付けるオブジェクト。これらのドキュメントには、実行ルールに関する別個のセクションがあります。
ラベルの定義は、次の形式になります。
アクションが実行されると、actionUrl
にHTTPSリクエストが送信されます。
callbackId
:特定の実行に固有のID。カスタムアクションの実行がブロックされている場合は、このIDを使用します。object
:objectRequestOptions
で要求されているプロパティーの値。InputFields
:ユーザーが入力フィールドに入力した値。
実行ペイロードは、次の形式になります。
想定されるレスポンスは、次の形式になります。
実行レスポンスには、以下の要素があります。
outputFields
:前に定義した出力フィールドの値。これらの値は、以降のアクションで使用できます。hs_execution_state
:出力フィールドに任意で追加できる特殊な値。再試行を指定することができない場合、追加できるのは次の値に限られます。- SUCCESS
- FAIL_CONTINUE
- BLOCK
- ASYNC
SUCCESS
とFAIL_CONTINUE
は、アクションが完了し、ワークフローで次のアクションが実行されることを意味します。実行状態が指定されていない場合は、ステータスコードを基にアクションの結果が判断されます。
- 2xxステータスコード:アクションが正常に完了したことを意味します。
- 4xxステータスコード:アクションが失敗したことを意味します。例外的に429 Rate Limited(データレート制限)ステータスコードは再試行として再処理され、Retry-Afterヘッダーが考慮されます。
- 5xxステータスコード:サービスに一時的な問題があったことを意味します。この場合、アクションは後で再試行されます。再試行はエクスポネンシャルバックオフ方式で行われます。再試行を継続できるのは最大3日間で、その期限に達すると失敗します。
実行関数を使用して、actionURL
への送信前にデータを書式設定したり、actionURL
から返されたデータを解析したりできます。実行関数には次の2種類があります。
PRE_ACTION_EXECUTION
POST_ACTION_EXECUTION
PRE_ACTION_EXECUTION関数
actionURL
への送信前にデータを書式設定するには、PRE_ACTION_EXECUTION
関数を使用します。
関数の定義は、次の形式になります。
関数への入力は、次の形式になります。
関数からの出力は、次の形式になります。
POST_ACTION_EXECUTION関数
actionURL
からレスポンスを受け取った後、HubSpot用のデータに書式設定するには、POST_ACTION_EXECUTION
関数を使用します。
関数の定義は、次の形式になります。
関数への入力は、次の形式になります。
関数からの出力は、次の形式になります。
カスタム ワークフロー アクションを非同期で実行するには、アクションをいったんブロックし、後でそのアクションを完了します。
カスタムアクションを使用して、ワークフローの実行をブロックすることができます。貴社のサービスからのcompleted (2xx or 4xx status code)
のレスポンスを受信した後、ワークフロー内のカスタムアクションの次のアクションは実行されず、貴社から続行の指示があるまでの間、その登録の実行が停止(ブロック)されます。
ブロックするときに、hs_default_expiration
フィールドの値を指定することもできます。このフィールドに指定された時間が経過すると、カスタムアクションは有効期限切れと判断されます。その場合、アクションが完了していなくても、ワークフローの実行が再開され、カスタムアクションの後続のアクションが実行されます。
カスタムアクションをブロックするには、アクション実行レスポンスを次の形式にする必要があります。
ブロックされたカスタムアクションの実行を完了するには、エンドポイント「/callbacks/{appId}/{callbackId}/complete
」を使用します。
リクエスト本文は次の形式にしてください。
実際のメッセージは、カスタムアクションのlabelsセクションで指定することができます。
executionRules
は、指定されている順序で分析されます。複数のルールが一致する場合、最初に一致したルールのメッセージのみがユーザーに表示されます。
ルールの一致は、実行による出力がルールに含まれる特定の値と一致すると発生します。例えば、次のようなexecutionRules
の組み合わせが考えられます。
上記のルールでは、次のように一致します。
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}
:errorCode
がALREADY_EXISTS
と等しいため、最初のルールと一致します。この例では、widgetName
が出力されるとしても、ルール定義でその出力値は使用されていないため、どの値も許容されます。{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}
:TOO_SMALL
がsizeError
のうちの1つと一致し、errorCode
がWIDGET_SIZE
であるため、2番目のルールに一致します。{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}
:errorCode
はWIDGET_SIZE
ですが、sizeError
が2番目のルールで指定されている値(TOO_SMALL
またはTOO_BIG
)のいずれにも一致しないため、3番目のルールと一致します。
この一致の仕組みによってフォールバックエラー(エラー時の代替処理)を指定できます。重要なエラーの場合は特定のエラーメッセージを表示し、あまり発生しないエラーについては汎用的な代替エラーメッセージを表示できます。以下に、カスタムメッセージの表示例を示します。
新しいカスタムアクションを作成したら、テストして公開することができます。
公開前のカスタムアクションのテスト
カスタムアクションを公開する前に、URLをwebhook.site(英語)に指定して、アクションの実行とフェッチオプションをテストすることができます。これにより、ペイロードを検査して、特定のレスポンスを返すことができます。
開発者ポータルでアクションをテストすることもできます。それにはまず、ワークフローツールでワークフローを作成します。次に、新しいアクションを追加します。
カスタムアクションの公開
既定では、カスタムアクションは未公開の状態で作成されます。未公開のカスタムアクションは、対応するHubSpotアプリケーションに関連付けられている開発者ポータルにのみ表示されます。カスタムアクションをユーザーに対して表示するには、アクション定義のpublished
フラグを更新してtrue
にします。アクションが未公開の場合でも、そのアクションをすでにワークフローに追加しているポータルでは、追加済みのアクションを編集して実行できます。ただし、そのアクションを再度追加することはできません。
Example 1
A basic example with the following input fields, created for contact and deal workflows:
- a static input field
- a dropdown field with options
- a field whose value is a HubSpot owner
- a field whose value is pulled from a property (that the user creating the workflow selects) on the enrolled object.
例2
次のカスタムアクションでは、サーバーレス関数を使用して、構成済みの「actionUrl」に送信されるペイロードを変換しています。「objectTypes」が指定されていないため、このアクションは全てのワークフロータイプで使用できます。
例3
次のカスタムアクションには、フィールド依存関係と、APIから取得したオプションがあります。ウィジェットサイズはウィジェットの色に依存するため、ウィジェットの色が選択されるまで、ユーザーはウィジェットサイズの値を入力できません。
ウィジェットコストもウィジェットの色に依存しますが、ユーザーがウィジェットの色に選択する値に基づく条件が設定されています。ここでは、ウィジェットの色として「赤」が選択されない限り、ウィジェットコストの値を入力できません。
例4
次の例では、カスタムアクションをブロックしています。コールバックAPIはHubSpotに対し、アクションを完了して登録済みオブジェクトをワークフローの次のアクションに進ませるよう指示する際に使用します。
アクションの作成時にアクションのブロックを指定する必要はありません。貴社が設定したactionUrlからのレスポンスによって決まるからです。
貴重なご意見をありがとうございました。