ワークフロー拡張機能の紹介と概要。
actionUrl
:アクションを実行する際のHTTPSリクエストの送信先URL。リクエスト本文には、どのユーザーに代わってアクションが実行されているか、入力フィールドにどのような値が入力されているかに関する情報が格納されます。
objectTypes
:アクションで処理できるCRMオブジェクト。
published
:デフォルトでは、カスタムアクションは未公開の状態で作成されます。未公開のアクションは、HubSpotアプリケーションに関連付けられている開発者ポータルにのみ表示されます。カスタムアクションをユーザーに対して表示するには、アクション定義のpublishedフラグを更新してtrueにします。
inputFields
:アクションに渡す入力。これらのフィールドの値は、ユーザーによって入力されます。
inputFieldDependencies
:これらのルールは、後述の例のように、dependencyType
に基づいて2つ以上の入力間の関係を定義します。以下のdependencyType
オプションを使用できます。
SINGLE_FIELD
:他のフィールドが特定の条件を満たすまでフィールドをグレーアウトするためのルール。これを使用すると、フィールドへの入力が完了したことを確認してから、訪問者がフォームの残りの部分に続けて入力できるようにできます。制御(親)フィールドは、対応する依存(子)フィールドに値を提供します。CONDITIONAL_SINGLE_FIELD
:他のフィールドが特定の条件を満たすまでフィールドを非表示にするためのルール。これを使用すると、そこまでの選択に基づいて特定のフィールドを表示または非表示にできます。例えば、お菓子屋さんなら、訪問者にケーキが好きかを尋ねるチェックボックスを追加し、そのチェックボックスが選択されている場合にのみ、好きなケーキの種類を尋ねるフィールドを表示できます。outputFields
:アクションによって出力する値。この値は、ワークフローの後続アクションで使用できます。カスタムアクションの出力はゼロにすることも、1つまたは複数にすることもできます。
objectRequestOptions
:actionUrlへのペイロードに含まれる、登録されたオブジェクトのプロパティー。
labels
:アクションのフィールドが表す内容とそのアクションの動作をユーザーに説明するための記述。英語のラベルは必須ですが、次の対応言語のラベルも併せて指定できます。
fr
)de
)ja
)es
)pt-br
)nl
)pl
)sv
)it
)da_dk
)fi
)no
)zh-tw
)executionRules
:ワークフローを作成するユーザーに対し、貴社のサービスからのエラーを示すために指定できる定義のリスト。
functions
:送信されるペイロードをURLに変換したり、URLから返されるレスポンスを変換したりするために実行するコードスニペット。
event
は、関数に渡されるデータを格納します。exports.main
は、関数が実行されるときに呼び出されるメソッドです。callback
関数は、結果を返すために使用できます。functionSource
の形式は文字列になります。コード内の文字はエスケープされるようにしてください。
一般的に、関数の定義は次の形式になります。
name
:入力フィールドの内部名。フィールドのラベルとは異なります。UIに表示されるラベルは、カスタムアクション定義のlabelsセクションを使用して定義する必要があります。type
:入力に必要な値の型。fieldType
:入力をUIでレンダリングする方法。入力は、CRMプロパティーと同様にレンダリングされます。有効なtype
とfieldType
の組み合わせについて詳細をご確認ください。supportedValueTypes
に有効な値は2つあります。
OBJECT_PROPERTY
:ユーザーが登録されたオブジェクトからプロパティーを選択するか、フィールドの値として使用する、先行アクションによる出力を選択できます。STATIC_VALUE
:上記以外の場合は常にこの値を使用します。これは、ユーザー自身が値を入力する必要があることを意味します。isRequired
:ユーザーが入力フィールドの値を入力することが必須かどうかを指定します。inputFieldDependencies
を使用してそれらの関係を定義する必要があります。詳しくはカスタムアクションの定義についてご確認ください。optionsURL
に送信されるペイロードは、次の形式になります。
フィールド | 説明 |
---|---|
portalId | HubSpotアカウントのID。 |
actionDefinitionId | カスタムアクション定義のID。 |
actionDefinitionVersion | カスタムアクション定義のバージョン。 |
objectTypeId | アクションが使用されているワークフローのオブジェクトタイプ。 |
inputFieldName | オプションを取得する入力フィールド。 |
inputFields | ワークフローユーザーによってすでに入力されているフィールドの値。 |
q | ユーザーが指定した検索クエリー。返されるオプションを絞り込むために使用します。これが含まれるのは、前のオプションフェッチがsearchable: true を返し、ユーザーが検索クエリーを入力した場合のみです。 |
after | ページ分割カーソル。これは、前のオプションフェッチによって返されたのと同じページ分割カーソルになります。これは、どのオプションがすでに取得されているかを追跡するために使用できます。 |
フィールド | 説明 |
---|---|
q | ページ分割カーソル。これが指定されている場合、ユーザーがオプションを選択しているときにワークフローアプリによって、オプションリストの一番下に結果をさらに読み込むボタンが表示されます。また、次のページが読み込まれると、この値がfetchOptions.after の下のリクエストペイロードに含められます。このフィールドはオプションです。 |
after | デフォルト値はfalse です。true に設定されている場合、ワークフローアプリは検索フィールドを表示し、ユーザーが検索クエリーで利用可能なオプションを絞り込めるようにします。検索クエリーが入力されると、fetchOptions.q の下のリクエストペイロードに、その検索語でオプションが再取得されます。このフィールドはオプションです。 |
searchable:true
を含めてオプションのリストを検索可能にしています。PRE_FETCH_OPTIONS
: HubSpotから送信されるペイロードを構成するための関数。POST_FETCH_OPTIONS
: 貴社のサービスから返されるレスポンスを、HubSpotで理解できる形式に変換するための関数。id
を指定することで、特定の入力フィールドにこの関数を適用できます。
フィールド | 説明 |
---|---|
portalId | HubSpotアカウントのID。 |
actionDefinitionId | カスタムアクション定義のID。 |
actionDefinitionVersion | カスタムアクション定義のバージョン。 |
objectTypeId | アクションが使用されているワークフローのオブジェクトタイプ。 |
inputFieldName | オプションを取得する入力フィールド。 |
inputFields | ワークフローユーザーによってすでに入力されているフィールドの値。 |
q | ユーザーが指定した検索クエリー。返されるオプションを絞り込むために使用します。これが含まれるのは、前のオプションフェッチがsearchable: true を返し、ユーザーが検索クエリーを入力した場合のみです。 |
after | ページ分割カーソル。これは、前のオプションフェッチによって返されたのと同じページ分割カーソルになります。これは、どのオプションがすでに取得されているかを追跡するために使用できます。 |
フィールド | 説明 |
---|---|
webhookUrl | HubSpotが呼び出すWebhook URL。 |
body | リクエストの本文。これはオプションです。 |
httpHeaders | 追加するカスタムリクエストヘッダーのマップ。これはオプションです。 |
contentType | リクエストのContent-Type 。デフォルト値はapplication/json です。これはオプションです。 |
accept | リクエストのAccept タイプ。デフォルト値はapplication/json です。これはオプションです。 |
httpMethod | リクエストを送信するためのHTTPメソッド。デフォルト値はPOST ですが、その他にGET 、POST 、PUT 、PATCH 、DELETE も使用できます。これはオプションです。 |
POST_FETCH_OPTIONS
関数を使用します。POST_FETCH_OPTIONS
関数の定義は、PRE_FETCH_OPTIONS
関数と同じです。外部データのフェッチオプションが定義されている場合、アクションの入力オプションにドロップダウンメニューがレンダリングされます。
type
とfieldType
の組み合わせについて詳細をご確認ください。actionURL
から返されるレスポンスから解析されます。例えば、出力フィールドを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
: outputFieldsに任意で追加できる特殊な値。再試行を指定することができない場合、追加できるのは次の値に限られます。
SUCCESS
とFAIL_CONTINUE
は、アクションが完了し、ワークフローで次のアクションが実行されることを意味します。実行状態が指定されていない場合は、ステータスコードを基にアクションの結果が判断されます。
actionURL
への送信前にデータを書式設定したり、actionURL
から返されたデータを解析したりできます。実行関数には次の2種類があります。
PRE_ACTION_EXECUTION
POST_ACTION_EXECUTION
actionURL
への送信前にデータを書式設定するには、PRE_ACTION_EXECUTION
関数を使用します。
関数の定義は、次の形式になります。
actionURL
からレスポンスを受け取った後、HubSpot用のデータに書式設定するには、POST_ACTION_EXECUTION
関数を使用します。
関数の定義は、次の形式になります。
completed (2xx or 4xx status code)
のレスポンスを受信した後、ワークフロー内のカスタムアクションの次のアクションは実行されず、続行の指示があるまでの間、その登録の実行が停止(ブロック)されます。
ブロックするときに、hs_default_expiration
フィールドの値を指定することもできます。このフィールドに指定された時間が経過すると、カスタムアクションは有効期限切れと判断されます。その場合、アクションが完了していなくても、ワークフローの実行が再開され、カスタムアクションの後続のアクションが実行されます。
カスタムアクションをブロックするには、アクション実行レスポンスを次の形式にする必要があります。
フィールド | 説明 |
---|---|
hs_execution_state | ワークフロー実行をブロックするには、カスタムアクションにBLOCK を設定する必要があります。これは必須フィールドです。 |
hs_expiration_duration | 期間は、ISO 8601の継続時間形式で指定する必要があります。指定しない場合、デフォルトの有効期限である1週間が使用されます。これはオプションです。 |
/callbacks/{callbackId}/complete
エンドポイントを使用します。
リクエスト本文は次の形式にします。
フィールド | 説明 |
---|---|
hs_execution_state | 最終的な実行状態。これは必須フィールドです。このフィールドの有効な値は、カスタムアクションが正常に完了したことを示すSUCCESS と、カスタムアクションの実行に問題があることを示すFAIL_CONTINUE です。 |
actionURL
のレスポンス本文内に次の形式で指定します。
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番目のルールに一致します。published
フラグを更新してtrue
にします。アクションが未公開の場合でも、そのアクションを既にワークフローに追加しているポータルでは、追加済みのアクションを編集して実行できます。ただし、そのアクションを再度追加することはできません。
widgetName
:静的入力フィールドwidgetColor
:オプション付きのドロップダウンフィールドwidgetOwner
:HubSpotの所有者を表すフィールドwidgetQuantity
:登録されたオブジェクトのプロパティー(ワークフローを作成しているユーザーが選択したプロパティー)から派生したフィールドobjectTypes
フィールドが指定されていないため、このアクションは全てのワークフロータイプで使用できます。