[AEM Forms]{class="badge positive" title="AEM Formsに適用）。"}

コアコンポーネント Formsのビジュアルルールエディターへの外部APIの統合

アダプティブフォームのビジュアルルールエディターは、呼び出しサービス​機能をサポートしており、インスタンスに設定されたフォームデータモデル（FDM）を介して外部APIに接続できます。 フォームフィールドをサービスの入力パラメーターに直接マッピングし、イベントペイロードオプションを使用して出力パラメーターをマッピングできます。 ビジュアルルールエディターでは、サービスの応答に基づいて成功ハンドラーと失敗ハンドラーのルールを定義することもできます。成功ハンドラーは成功したAPI呼び出しを処理し、失敗ハンドラーはエラーを管理します。

これにより、フォームからAPI リクエストを簡単に送信し、API レスポンスを処理し、返されたデータをフォーム内で動的に表示または使用できます。 これにより、アダプティブフォームと外部システムやデータソースとのシームレスな統合が保証されます。

フォームのルールエディターで呼び出しサービスを使用する利点

Adobe フォームのルールエディターでサービス呼び出し操作を使用する利点を以下に示します。

成功および失敗応答のサービスハンドラーを呼び出す

視覚的なルールエディターを使用すると、出力の応答に基づいて​ Invoke Service ​操作の成功ハンドラーと失敗ハンドラーのルールを作成できます。 次の画像は、アダプティブフォームのビジュアルルールエディターの​ 呼び出しサービス ​を示しています。

成功ハンドラーと失敗ハンドラーの追加

成功ハンドラーまたは失敗ハンドラーを追加するには、それぞれ​ 成功ハンドラーを追加 ​または​ 失敗ハンドラーを追加 ​をクリックします。

「成功ハンドラーを追加」をクリックすると、サービス成功ハンドラー ルールエディターが表示され、操作が成功したときに​ サービスを呼び出し ​の出力応答を管理するためのルールまたはロジックを指定できます。 条件を定義しなくてもルールを指定できますが、条件を追加 オプションをクリックして、成功ハンドラーの条件を追加できます。

呼び出しサービス​操作に対する正常な応答を処理するために、複数のルールを追加できます。

{width="50%,"}

同様に、操作が成功しなかった場合に​ Invoke Service ​の出力応答を処理するルールを追加できます。 次の画像は、Invoke Service Failure Handler ルールエディターを示しています。

また、複数のルールを追加して、サービスの呼び出し​操作からの失敗した応答を処理することもできます。

サーバー​ でエラー検証を有効にする ​機能を使用すると、アダプティブフォームの設計中に作成者が追加した検証をサーバーでも実行できます。

ルールエディターで呼び出しサービスを使用するための前提条件

ルール エディターで​ 呼び出しサービス ​を使用する前に満たす必要がある前提条件は次のとおりです。

様々なユースケースを通じたInvoke Serviceの探索

ビジュアルルールエディターの​ 呼び出しサービス ​を使用すると、いくつかの便利な操作を実行できます。 ドロップダウンオプションの入力、繰り返し可能またはシンプルなパネルの設定、フォームフィールドの検証など、すべて​ 呼び出しサービス ​の出力応答に基づいて使用できます。 フォームの柔軟性とインタラクティブ性を向上させます。

次の表は、呼び出しサービス​を使用できるいくつかのシナリオを示しています。

Get Information テキストボックスに入力された入力に基づいて値を取得するPet ID フォームを作成します。 以下のスクリーンショットは、これらのユースケースで使用されるフォームを示しています。

フォームフィールド

フォームに次のフィールドを追加します。

NOTE

フォームフィールドの​プロパティ ダイアログの​バインド参照 フィールドで、 を選択し、フォームデータモデル（FDM）に追加したバイナリプロパティを移動して選択します。

パネルの設定

次の制約を使用して、パネルを繰り返しとして設定します。

必要に応じて、繰り返しパネルの値を調整できます。

データソース

この例では、Swagger Petstore APIを使用してデータソースを設定しています。 ​ フォームデータモデル ​は、getPetById サービス用に設定されており、入力されたIDに基づいてペットの詳細を取得します。

Swagger Petstore APIのaddPet サービスを使用して、次のJSONを投稿してみましょう。

{
        "id": 101,
        "category": {
            "id": 1,
            "name": "Labrador"
        },
        "name": "Lisa",
        "photoUrls": [
            "https://example.com/photos/lisa1.jpg",
            "https://example.com/photos/lisa2.jpg"
        ],
        "tags": [
            {
                "id": 1,
                "name": "vaccinated"
            },
            {
                "id": 2,
                "name": "friendly"
            },
            {
                "id": 3,
                "name": "house-trained"
            }
        ],
        "status": "available"
    }

ルールとロジックは、テキストボックスのルールエディターの サービスを呼び出すPet ID アクションを使用して実装され、前述のユースケースを示します。

それでは、各ユースケースの実装を詳しく見ていきましょう。

ユースケース 1：呼び出しサービスの出力を使用してドロップダウン値を入力する

この使用例では、Invoke Serviceの出力に基づいてドロップダウンオプションを動的に入力する方法を示します。

実装

これを実現するには、Pet ID テキストボックスにルールを作成して、getPetById サービスを呼び出します。 ルールで、enum成功ハンドラーを追加photo-urlのphotoUrls ドロップダウンの​ プロパティを ​に設定します。

出力

「101」テキストボックスに「Pet ID」と入力すると、入力した値に基づいてドロップダウンオプションが動的に入力されます。

ユースケース 2：呼び出しサービスの出力を使用した繰り返し可能なパネルの設定

この使用例では、呼び出しサービス​の出力に基づいて、繰り返し可能なパネルを動的に入力する方法を示します。

考慮事項

実装

Pet ID テキストボックスにルールを作成して、getPetById サービスを呼び出します。 成功ハンドラーを追加​で、別の成功ハンドラー応答を追加します。 ルールのtags パネルの値をtagsに設定します。

出力

「101」テキストボックスに「Pet ID」と入力すると、入力値に基づいて繰り返し可能なパネルが動的に入力されます。

ユースケース 3：呼び出しサービスの出力を使用したパネルの設定

この使用例では、呼び出しサービス​の出力に基づいて、パネルの値を動的に設定する方法を示します。

考慮事項

実装

Pet ID テキストボックスにルールを作成して、getPetById サービスを呼び出します。 成功ハンドラーを追加​で、別の成功ハンドラー応答を追加します。 ルールのcategoryname テキストボックスの値をcategory.nameに設定します。

出力

「101」テキストボックスに「Pet ID」と入力すると、入力値に基づいてパネルに動的に入力されます。

ユースケース 4：呼び出しサービスの出力パラメーターを使用して、他のフィールドを検証する

この使用例では、呼び出しサービス​の出力を使用して、他のフォームフィールドを動的に検証する方法を示します。

実装

Pet ID テキストボックスにルールを作成して、getPetById サービスを呼び出します。 失敗ハンドラーを追加​で、失敗ハンドラー応答を追加します。 誤った​ が入力された場合は、 ​送信Pet ID ボタンを非表示にします。

出力

102 テキストボックスにPet IDと入力すると、送信 ボタンは非表示になります。

ユースケース 5：呼び出しサービスのアクションに移動でのイベントペイロードの使用

この使用例では、呼び出しサービス​を呼び出す​送信 ボタンでルールを設定し、移動先 アクションを使用してユーザーを別のページにリダイレクトする方法を示します。

実装

送信 ボタンにルールを作成して、redirect-api API サービスを呼び出します。 このサービスは、ユーザーを​お問い合わせ フォームにリダイレクトする責任があります。

以下に示すJSON データを使用して、APIをredirect-api API サービスとしてルールエディターに直接統合できます。

{
  "id": "1",
  "path": "/content/dam/formsanddocuments/contact-detail/jcr:content?wcmmode=disabled"
}

成功ハンドラーを追加​で、移動先 アクションを設定して、パラメーターを使用してユーザーを​お問い合わせEvent Payload ページにリダイレクトします。 ここで、ユーザーは連絡先の詳細を送信できます。

オプションで、サービスコールが失敗した場合にエラーメッセージを表示するようにエラーハンドラーを設定します。

出力

送信 ボタンをクリックすると、redirect-api API サービスが呼び出されます。 成功すると、ユーザーは​お問い合わせ ページにリダイレクトされます。

JSON配列からのプロパティ値の取得

これはアーリーアダプター機能です。 興味がある場合は、仕事用アドレスからmailto:aem-forms-ea@adobe.comにクイックメールを送信して、機能へのアクセスをリクエストしてください。

アダプティブ Formsでは、サービスの呼び出し、JSON応答の処理、フォームフィールドの動的な入力がサポートされています。 この節では、JSON配列からプロパティ値を抽出し、フォームフィールドにバインドする方法について説明します。

JSON応答のサンプル

次の例は、米国の販売地域と販売担当者のリストを表しています。

[
  {
    "region": "East",
    "salesPerson": "Emily Carter"
  },
  {
    "region": "South",
    "salesPerson": "Michael Brown"
  },
  {
    "region": "Midwest",
    "salesPerson": "Sophia Martinez"
  },
  {
    "region": "Southwest",
    "salesPerson": "David Johnson"
  },
  {
    "region": "West",
    "salesPerson": "Linda Walker"
  }
]

プロパティ値を抽出するカスタム関数

JSON配列からプロパティ値を抽出するには、次のカスタム関数を使用します。

/**
 * Returns an array of values for a specific property from an array of objects.
 *
 * @name getPropertyValues
 * @param {Object[]} jsonArray An array of objects
 * @param {string} propertyName The property whose values should be extracted
 * @returns {Array} An array containing the values of the specified property
 *
 */

function getPropertyValues(jsonArray, propertyName)
{
    return jsonArray.map((obj) => obj[propertyName]);

}

カスタム関数は次を受け入れます。

カスタム関数は、値の単純な配列を返します。

ルールエディターでの関数の使用

JSON配列から特定の値を取得するには：

event.payload.invokeServiceResponse.rawPayloadBody

次の例は、この応答を使用してSales Department フォームに入力する方法を示しています。

例えば、Sales DepartmentとSelect Regionのドロップダウンを含むSelect Sales Representative フォームを作成します。

手順1: フォームの初期化でサービスを呼び出す

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

手順2：地域ドロップダウンを設定

サービスコールにサクセスハンドラーを追加し、次のアクションを設定します。

Set enum → Region dropdown
getPropertyValues(
    event.payload.invokeServiceResponse.rawPayloadBody,
    "region"
)

このルールは、JSON配列を読み取り、region プロパティ値を抽出し、値をSelect Region ドロップダウンに割り当てます。

同様に、成功ハンドラーのSelect Sales Representative ドロップダウンのアクションを設定します。

フォームがJSON データを読み込むと、カスタム関数がプロパティ値を抽出し、ドロップダウンが自動的に入力されます。

よくある質問

Q: Invoke サービスを使用してルールを作成し、コアコンポーネントの最新バージョンにアップグレードするとどうなりますか？

A: コアコンポーネントの最新バージョンにアップグレードすると、呼び出しサービス ルールは、下位互換性があるため、最新のユーザーインターフェイスに自動的に更新されます。

Q: サービスの呼び出し操作の成功または失敗の応答を処理するために、複数のルールを追加できますか？

A:​はい、呼び出しサービス​操作の成功または失敗の応答を処理するために、複数のルールを追加できます。

関連記事

その他のリソース