Webhook

Webhook は、データ接続の概念で、Salesforce、SAP、または設定されたHTTPサーバーなどの外部システムにリクエストを送信し、通常はその外部システムのデータを変更することができます。

Webhook を設定し、アクションでの使用に設定することにより、Foundry でエンドユーザーがアクションを適用すると、外部システムにデータを送信できます。これにより、Foundry のワークフローをソースシステムに直接接続し、そのシステムにデータと決定を書き戻すことができます。

このセクションでは、アクションで Webhook を設定するためのさまざまなオプションについて詳しく説明します。ステップバイステップのチュートリアルについては、アクションでの Webhook の追加方法のドキュメントを参照してください。

Webhook: 書き戻し vs. 副作用

アクションでの Webhook の使用には、書き戻しまたは副作用として設定する2つの方法があります。

以下に、書き戻しと副作用の Webhook の動作を比較する表を示します。

以下のセクションでは、書き戻しの Webhook と副作用の Webhook について詳しく説明します。

書き戻し Webhook

書き戻しとして設定されている場合、Webhook は他の Rules が評価される前に実行されます。Webhook の実行が失敗した場合、他の変更は行われません。Foundry での変更が外部システムの前に行われないようにするには、Webhook を書き戻しとして設定する必要があります。

この動作により、Foundry と外部システム間のある程度のトランザクション性が実現できます。書き戻し Webhook を使用することで、外部システムへのリクエストが失敗した場合、Foundry オントロジーには変更が適用されないことが保証されます。ただし、外部リクエストが成功しても、オントロジーの変更が失敗する可能性はあります。

書き戻し Webhook が失敗したときにアクションの適用が停止するため、書き戻しとして1つの Webhook のみを設定できます。この Webhook がアクションの適用時に失敗した場合、エンドユーザーに失敗に関するエラーが表示されます。

Webhook が書き戻しとして設定されている場合、その出力パラメーターは後続の Rules で使用できます。詳細については、以下の 出力パラメーター セクションを参照してください。

副作用 Webhook

副作用として設定されている場合、Webhook は他の Rules が評価された後に実行されます。これは、Foundry オブジェクトへの変更が副作用が適用される前に行われることを意味します。1つのアクションで複数の副作用 Webhook を設定し、特定の順序で実行することができます。副作用 Webhook があるアクションでは、エンドユーザーは Foundry オブジェクトが変更された後に成功メッセージを表示し、副作用の実行は成功メッセージが表示された後に行われる場合があります。

1つのアクションから Webhook を複数回呼び出す必要がある場合は、入力としてペイロードのリストを提供することで、副作用 Webhook でこれを実現できます。これにより、提供されたリスト内のペイロードの数だけ Webhook がトリガーされ、保証された順序で処理されます。これの例は、以下の 入力パラメーター セクションで見つけることができます。

最善の努力で通知を送信するか、複数の外部システムに書き戻す場合は、副作用 Webhook を使用してください。

入力パラメーター

アクションで Webhook を設定するには、必要な入力パラメーターすべてを設定する必要があります。Webhook 入力パラメーターに関する一般的な参考資料は、Data Connection ドキュメントで入手できます。

Webhook 入力パラメーターを設定する方法は2つあります。アクションパラメーターにマッピングするか、関数を使用するかです。

アクションパラメーターにマッピングする場合、各必要な Webhook 入力は、同じタイプのアクションパラメーター、静的な値、またはオブジェクトパラメーターのプロパティに設定する必要があります。

関数を使用する場合は、Webhook タイプと強く一致するすべての必要な Webhook 入力パラメーターを含むカスタムタイプを返す関数を選択する必要があります。それ以外の場合、OntologyMetadata:ActionWebhookInputsDoNotHaveExpectedType エラーが発生します。関数を使用して Webhook 入力パラメーターを設定することは、特にオントロジーオブジェクトに基づくロジックを使用して入力を設定したい場合に便利です。たとえば、関連するオブジェクトを取得し、それらのオブジェクトからプロパティ値を取得して Webhook 入力を事前に設定できます。

例として、ID が name、industry、および country の3つの入力パラメーターを持つ Webhook があるとします：

同じ構造のカスタムインターフェースを返す関数を作成できます:

Copied!
1
2
3
4
5
6
7
// 'MyWebhookInput'というインターフェースをエクスポートします。
// このインターフェースは、ウェブフック入力の形式を定義します。
export interface MyWebhookInput {
    name: string;  // 名前
    industry: string;  // 産業
    country: string;  // 国
}

次に、アクションでWebhookの入力を設定する際に、この関数を選択し、アクションのパラメーターを関数に必要なパラメーターにマッピングできます:

以下は、オントロジーのオブジェクトからデータをロードし、それを使用してWebhookの入力を設定する関数の完全なコード例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// "@foundry/functions-api"からFunctionとUserFacingErrorをインポートします
import { Function, UserFacingError } from "@foundry/functions-api";
// "@foundry/ontology-api"からCompanyをインポートします
import { Company } from "@foundry/ontology-api";

// MyWebhookInputインターフェースを定義します。name, industry, countryプロパティを持つオブジェクトを表します
export interface MyWebhookInput {
    name: string;
    industry: string;
    country: string;
}

// MyWebhookFunctionsクラスを定義します
export class MyWebhookFunctions {
    // Functionデコレーターを使用して、returnWebhookInputメソッドを公開関数としてマークします
    @Function()
    // この関数は、Companyオブジェクトを引数に取り、MyWebhookInputオブジェクトを返します
    public returnWebhookInput(company: Company): MyWebhookInput {
        // 会社の名前、業界、国が設定されていない場合は、エラーをスローします
        if (!company.name || !company.industry || !company.country) {
            throw new UserFacingError("Some required fields are not set.");
        }
        // 会社の名前、業界、国を持つオブジェクトを返します
        return {
            name: company.name,
            industry: company.industry,
            country: company.country,
        }
    }
}

副作用の Webhook は、Function からペイロードのリストを返すことで複数回呼び出すことが可能です。以下に、2つの企業を入力として受け取り、Webhook が期待する入力パラメーターに一致する2つのペイロードを含むリストを返す例の Function を示します。この Function を Actions から使って副作用の Webhook の入力を返すと、2回の別々の Webhook 実行を引き起こします。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// "@foundry/functions-api"から"Function"をインポートします。
import { Function } from "@foundry/functions-api";
// "@foundry/ontology-api"から"Company"をインポートします。
import { Company } from "@foundry/ontology-api";

// MyWebhookInputインターフェースをエクスポートします。これは二つの文字列型のプロパティを持ちます。
export interface MyWebhookInput {
    arg1: string;
    arg2: string;
}

// MyFunctionsクラスをエクスポートします。
export class MyFunctions {
    // "createWebhookRequest"という名前の関数を定義します。この関数は二つのCompany型の引数を取り、MyWebhookInput型の配列を返します。
    @Function()
    public createWebhookRequest(company1: Company, company2: Company): MyWebhookInput[] {
        return [
        {
           // company1のプロパティをarg1とarg2にセットします。
           arg1: company1.someProperty,
           arg2: company1.someOtherProperty,
        },
        {
           // company2のプロパティをarg1とarg2にセットします。
           arg1: company2.someProperty,
           arg2: company2.someOtherProperty,
        }
        ];
    }
}

出力パラメーター

Webhook が書き戻し Webhookとして設定されている場合、その出力パラメーターを後続の Rules で使用することができます。これは、外部システムがデータを返し、それをすぐに Foundry のオブジェクトに書き込む、または後続の通知や副作用 Webhookで使用したい場合に便利です。

Webhook の出力パラメーターに関する一般的な参考資料は、Data Connection 文書でご覧いただけます。

後続のロジックルールで出力パラメーターを使用するには、ロジックルールの値を入力する際に Writeback response を選択し、使用したい特定の出力を選択します：