AEM Adaptive Formsにカスタムエラーハンドラーを追加する

Adobeでは、最新の拡張可能なデータキャプチャを使用することをお勧めします コアコンポーネント 対象： 新しいアダプティブFormsの作成 または AEM SitesページへのアダプティブFormsの追加. これらのコンポーネントは、アダプティブフォームの作成における大幅な進歩を示すものであり、優れたユーザーエクスペリエンスを実現します。この記事では、基盤コンポーネントを使用してアダプティブフォームを作成するより従来的な方法について説明します。

AEM Forms には、すぐに使用できる、フォーム送信の成功ハンドラーと失敗ハンドラーが用意されています。また、エラーハンドラー関数をカスタマイズする機能もあります。例えば、特定のエラーコードに対してバックエンドでカスタムワークフローを呼び出したり、サービスが停止していることを顧客に通知したりできます。ハンドラーは、サーバー応答に基づいて実行されるクライアントサイド関数です。API を使用して外部サービスが呼び出されると、データが検証のためにサーバーに送信され、サーバーは送信の成功イベントまたはエラーイベントに関する情報と共に、応答をクライアントに返します。この情報は、関連するハンドラーにパラメーターとして渡され、関数が実行されます。エラーハンドラーは、発生したエラーや検証の問題を管理したり表示したりするのに役立ちます。

アダプティブフォームは、事前設定された検証条件に基づいて、フィールドに指定された入力を検証し、外部サービスを呼び出すように設定された REST エンドポイントから返される様々なエラーを確認します。アダプティブフォームで使用するデータソースに基づいて、検証条件を設定できます。例えば、RESTful web サービスをデータソースとして使用する場合、Swagger 定義ファイルで検証条件を定義できます。

入力値が検証条件を満たす場合、その値は他のデータソースに送信され、アダプティブフォームはエラーハンドラーを使用してエラーメッセージを表示します。 この方法と同様に、アダプティブフォームをカスタムエラーと統合して、データ検証を実行します。入力値が検証条件を満たさない場合、アダプティブフォームのフィールドレベルでエラーメッセージが表示されます。サーバーから返される検証エラーメッセージが、標準メッセージ形式の場合に発生します。

エラーハンドラーの使用

エラーハンドラーは、様々な目的で使用されます。エラーハンドラー関数の使用例の一部を以下に示します。

• 検証の実行：事前定義されたルールや条件に対してユーザー入力を検証することで、エラー処理を開始します。ユーザーがアダプティブフォームに入力すると、エラーハンドラーは入力を検証し、必要な形式、長さ、その他の制約が満たされていることを確認します。

• リアルタイムでのフィードバックの提供：エラーが検出されると、エラーハンドラーは、対応するフォームフィールドの下にフィードバック（インラインエラーメッセージなど）を、ユーザーに即時に表示します。このフィードバックは、ユーザーがフォームを送信して応答を待たなくても、エラーを特定して修正するのに役立ちます。

• エラーメッセージの表示：アダプティブフォームの送信で検証エラーが発生すると、エラーハンドラーは適切なエラーメッセージを表示します。 エラーメッセージは、明確かつ簡潔で、注意が必要な特定のフィールドをハイライト表示する必要があります。

• エラーのあるフィールドのハイライト表示：特定の誤ったフィールドにユーザーの注意を引くために、エラーハンドラーは対応するフィールドをハイライト表示するか、視覚的に区別します。この処理は、背景色の変更、アイコンや境界線の追加、またはユーザーがエラーを迅速に見つけて対処する上で役立つ、その他の視覚的なヒントを追加することによって実行されます。

失敗／エラー応答形式

サーバー検証エラーメッセージが次の標準形式の場合、アダプティブフォームはフィールドレベルでエラーを表示します。
次のコードは、既存の失敗応答構造を示しています。

   {
    errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
    errors : [
        {
             somExpression  : <somexpr>
             errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
        }
    ]
    originCode : <target error Code>
    originMessage : <unstructured error message returned by service>
    }

ここで、

• errorCausedBy は失敗の理由を説明します.
• errors は、検証条件に失敗したフィールドの SOM 式と検証エラーメッセージに言及します。
• originCode は AEM によって追加され、外部サービスから返された http ステータスコードが含まれます。
• originMessage フィールドは AEM によって追加され、外部サービスから返された生のエラーデータが含まれます。

AEM Forms バージョンの機能の改善とその後の更新に伴い、既存の失敗応答構造は、既存の失敗応答構造と下位互換性のある RFC7807 に基づく新しい形式に変更されました。

    {
        "type": "SERVER_SIDE_VALIDATION/FORM_SUBMISSION/SERVICE_INVOCATION/FAILURE/VALIDATION_ERROR", (required)
        "title": "Server side validation failed/Third party service invocation failed", (optional)
        "detail": "", (optional)
        "instance": "", (optional)
        "validationErrors" : [ (required)
            {
                "fieldName":"<SOM expression of the field whose data sent is invalid>",
                "dataRef":<JSONPath (or XPath) of the data element which is invalid>
                "details": ["Error Message(s) for the field"] (required)

            }
        ],
        "originCode": <Origin http status code>, (optional - in case of SERVER_SIDE_VALIDATION)
        "originMessage" : "<unstructured error message returned by service>" (optional - in case of SERVER_SIDE_VALIDATION)
    }

ここで、

• type (required) は失敗のタイプを指定します。次のいずれかの値になります。

  • SERVER_SIDE_VALIDATION は、サーバーサイドの検証が原因でエラーが発生したことを示します。
  • FORM_SUBMISSION は、フォームの送信中にエラーが発生したことを示します
  • SERVICE_INVOCATION は、サードパーティのサービスの呼び出し中に失敗が発生したことを示します。
  • FAILURE は、一般的な失敗を示します。
  • VALIDATION_ERROR は、検証エラーが原因で失敗が発生したことを示します。

• title (optional) は、失敗のタイトルまたは簡単な説明を示します。

• detail (optional) は、必要に応じて、失敗に関する追加の詳細を示します。

• instance (optional) は、失敗に関連付けられたインスタンスまたは識別子を表し、特定の失敗の発生を追跡したり識別したりするのに役立ちます。

• validationErrors (required) には、検証エラーに関する情報が含まれています。次のフィールドが含まれています。

  • fieldname は、検証条件に失敗したフィールドの SOM 式に言及します。
  • dataRef は、検証に失敗したフィールドの JSON パスまたは XPath を表します。
  • details には、検証エラーメッセージとエラーのあるフィールドが含まれています。

• originCode (optional) は、AEMによって追加されたフィールドで、外部サービスから返された http ステータスコードが含まれています。

• originMessage (optional) は、AEMによって追加されたフィールドで、外部サービスから返された生のエラーデータが含まれています。

エラー応答形式のサンプル

エラー応答を表示するオプションの一部を次に示します。

ルールエディターを使用してエラーハンドラーを追加

ルールエディターのサービスの呼び出しアクションを使用して、アダプティブフォームで使用するデータソースに基づいて検証条件を定義します。RESTful web サービスをデータソースとして使用する場合、Swagger 定義ファイルで検証条件を定義できます。アダプティブフォームのエラーハンドラー関数とルールエディターを利用すると、エラー処理を効果的に管理およびカスタマイズできます。ルールエディターを使用して条件を定義し、ルールがトリガーされたときに実行するアクションを設定します。アダプティブフォームは、事前設定された検証条件に基づいて、フィールドに入力した内容を検証します。入力値が検証条件を満たさない場合、エラーメッセージはアダプティブフォームのフィールドレベルで表示されます。

ルールエディターを使用して、次の操作を実行できます。

• デフォルトのエラーハンドラー関数を追加
• カスタムエラーハンドラー関数を追加

デフォルトのエラーハンドラー関数を追加

デフォルトのエラーハンドラーは、エラー応答が標準スキーマの場合、またはサーバーサイドの検証エラーの場合に、フィールドにエラーメッセージを表示する機能をサポートしています。
ルールエディターのサービスの呼び出し action, take an example of a simple Adaptive Form with two fieldsアクションを使用してカスタムエラーハンドラーを作成および使用する方法を理解するために、「ペット ID」および「ペット名」という 2 つのフィールドを持つアダプティブフォームを例に、「ペット ID」でカスタムエラーハンドラーを使用して、200 - OK、404 - Not Found、400 - Bad Request などの外部サービスを呼び出すように設定された REST エンドポイントが返す様々なエラーをチェックしましょう。ルールエディターのサービスの呼び出しアクションを使用してデフォルトのエラーハンドラーを追加するには、次の手順を実行します。

1. アダプティブフォームをオーサリングモードで開き、フォームコンポーネントを選択して、 ルールエディター をクリックして、ルールエディターを開きます。
2. 「作成」を選択します。
3. ルールの​条件​セクションで条件を作成します。例： 条件[ペット ID フィールドの名前] が変更されました。 「 」を 状態を選択 」ドロップダウンリストから選択できます。
4. 「Then」セクションの​アクションの選択​ドロップダウンリストで「サービスの呼び出し」を選択します。
5. 「入力」セクションから、Post サービス​とそれに対応するデータ連結を選択します。例えば、ペット ID を検証する場合は、Post サービス​を GET /pet/{petId} として選択し、「入力」セクションで「ペット ID」を選択します。
6. 「出力」セクションからデータ連結を選択します。例えば、「出力」セクションで「ペット名」を選択します。
7. 「エラーハンドラー」セクションから「カスタムエラーハンドラー」を選択します。
8. 「完了」をクリックします。

このルールの結果、REST エンドポイントによって呼び出された外部サービスを使用して、ペット ID に入力した値が​ペット名​の検証をチェックします。データソースに基づく検証条件が失敗した場合は、エラーメッセージがフィールドレベルで表示されます。

カスタムエラーハンドラー関数を追加

カスタムエラーハンドラー関数を追加して、次のようなアクションを実行できます。

• 非標準または標準のエラー応答を使用するエラー応答を処理します。これらの非標準のエラー応答は、エラー応答の標準スキーマに準拠していないことに注意する必要があります。
• 分析イベントを任意の分析プラットフォームに送信します。例：Adobe Analytics.
• エラーメッセージが表示されるモーダルダイアログを表示します。

上記のアクションに加えて、カスタムエラーハンドラーを使用すると、特定のユーザー要件を満たすカスタマイズされた関数を実行できます。

カスタムエラーハンドラーは、外部サービスから返されたエラーに応答し、カスタマイズされた応答をエンドユーザーに配信するように設計された関数（クライアントライブラリ）です。注釈 @errorHandler 付きのクライアントライブラリは、カスタムエラーハンドラー関数と見なされます。この注釈は、.js ファイルで指定されたエラーハンドラー関数を特定するのに役立ちます。
ルールエディターのサービスの呼び出しアクションを使用してカスタムエラーハンドラーを作成および使用する方法を理解するために、「ペット ID」および「ペット名」という 2 つのフィールドを持つアダプティブフォームを例に、「ペット ID」でカスタムエラーハンドラーを使用して、200 - OK、404 - Not Found、400 - Bad Request などの外部サービスを呼び出すように設定された REST エンドポイントが返す様々なエラーをチェックしましょう。

アダプティブフォームにカスタムエラーハンドラーを追加して使用するには、次の手順を実行します。

1. カスタムエラーハンドラーを作成
2. ルールエディターを使用してカスタムエラーハンドラーを設定

1. カスタムエラーハンドラーを作成

カスタムエラー関数を作成するには、次の手順を実行します。

1. AEM Forms as a Cloud Service リポジトリを複製.

2. の下にフォルダーを作成します。 [AEM Forms as a Cloud Service repository folder]/apps/ フォルダー。 例えば、という名前のフォルダーを作成します。 experience-league

3. に移動します。 [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/ をクリックし、 ClientLibraryFolder as clientlibs.

4. js という名前のフォルダーを作成します。

5. [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js フォルダーに移動します。

6. JavaScript ファイルを追加します。例： function.js. ファイルには、カスタムエラーハンドラーのコードが含まれています。
   次のコードを JavaScript ファイルに追加して、REST サービスエンドポイントから受け取った応答とヘッダーをブラウザーコンソールに表示します。

       /**
       * Custom Error handler
       * @name customErrorHandler Custom Error Handler Function
       * @errorHandler
       */
       function customErrorHandler(response, headers)
       {
           console.log("Custom Error Handler processing start...");
           console.log("response:"+JSON.stringify(response));
           console.log("headers:"+JSON.stringify(headers));
           guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers);
           console.log("Custom Error Handler processing end...");
       }
   

   カスタムエラーハンドラーからデフォルトのエラーハンドラーを呼び出すには、サンプルコードの次の行が使用されます。
   guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)

   メモ

   Adobe Analytics の .content.xml ファイルを開き、 allowProxy および categories プロパティ。

   • allowProxy = [Boolean]true
   • categories= customfunctionsdemo
     例えば、この場合、 [custom-errorhandler-name] は次のように指定されます。 customfunctionsdemo.

7. function.js ファイルを保存します。

8. [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js フォルダーに移動します。

9. js.txt というテキストファイルを追加します。ファイルには次が含まれます。

       #base=js
       functions.js
   

10. js.txt ファイルを保存します。
    作成したフォルダー構造は次のようになります。

    

    メモ

    カスタム関数の作成方法について詳しくは、ルールエディターのカスタム関数を参照してください。

11. 次のコマンドを使用して、リポジトリに変更を追加、コミット、プッシュします。

        git add .
        git commit -a -m "Adding error handling files"
        git push
    

12. パイプラインを実行します。

パイプラインが正常に実行されると、カスタムエラーハンドラーがアダプティブフォームのルールエディターで使用できるようになります。次に、ルールエディターのサービスの呼び出しを AEM Forms で使用して、カスタムエラーハンドラーを設定して使用する方法を説明します。

2. ルールエディターを使用して、カスタムエラーハンドラーを設定

アダプティブフォームにカスタムエラーハンドラーを実装する前に、クライアントライブラリ名が クライアントライブラリカテゴリ は、 .content.xml ファイル。

この場合、クライアントライブラリ名は customfunctionsdemo （内） .content.xml ファイル。

ルールエディターのサービスの呼び出し​アクションを使用してカスタムエラーハンドラーを使用するには、次の手順を実行します。

1. アダプティブフォームをオーサリングモードで開き、フォームコンポーネントを選択して、 ルールエディター をクリックして、ルールエディターを開きます。
2. 「作成」を選択します。
3. ルールの​条件​セクションで条件を作成します。例えば、[ペット ID の名前フィールド]​が変更された場合は、「状態を選択 」ドロップダウンリストから「変更済み」を選択します。
4. 「Then」セクションの​アクションの選択​ドロップダウンリストで「サービスの呼び出し」を選択します。
5. 「入力」セクションから、Post サービス​とそれに対応するデータ連結を選択します。例えば、ペット ID を検証する場合は、Post サービス​を GET /pet/{petId} として選択し、「入力」セクションで「ペット ID」を選択します。
6. 「出力」セクションからデータ連結を選択します。例えば、「出力」セクションで「ペット名」を選択します。
7. 「エラーハンドラー」セクションから「カスタムエラーハンドラー」を選択します。
8. 「完了」をクリックします。

このルールの結果、REST エンドポイントによって呼び出された外部サービスを使用して、ペット ID に入力した値が​ペット名​の検証をチェックします。データソースに基づく検証条件が失敗した場合は、エラーメッセージがフィールドレベルで表示されます。

ブラウザーコンソールを開き、REST サービスエンドポイントから受け取った応答とヘッダーで、検証エラーメッセージを確認します。

カスタムエラーハンドラー関数は、エラー応答に基づいて、モーダルダイアログの表示や分析イベントの送信など、追加のアクションを実行します。カスタムエラーハンドラー関数を使用すると、特定のユーザー要件に合わせて柔軟にエラー処理をカスタマイズできます。

関連トピック

• AEM アダプティブフォームの作成
• AEM Sites ページへ AEM アダプティブフォームを追加
• AEM アダプティブフォームへテーマを適用
• AEM アダプティブフォームへコンポーネントを追加
• AEM アダプティブフォームでの Captcha の使用
• AEM アダプティブフォームの PDF バージョン（DoR）を生成
• AEM アダプティブフォームを翻訳
• フォームの使用状況を追跡するアダプティブフォームの Adobe Analytics を有効にする
• Microsoft SharePoint へアダプティブフォームを接続
• Microsoft Power Automate へアダプティブフォームを接続
• Microsoft OneDrive へアダプティブフォームを接続
• Microsoft Azure Blob Storage へアダプティブフォームを接続
• Salesforce へアダプティブフォームを接続
• AEM アダプティブフォームで Adobe Sign を使用
• アダプティブフォームの新しいロケールを追加
• データベースへアダプティブフォームデータを送信
• REST エンドポイントへアダプティブフォームデータを送信
• AEM ワークフローへアダプティブフォームデータを送信
• フォームポータルを使用して AEM web サイト上の AEM アダプティブフォームを一覧表示
• アダプティブForms（コアコンポーネント）でカスタムエラーハンドラーを作成して使用する