AEM Adaptive Formsにカスタムエラーハンドラーを追加する error-handlers-in-adaptive-form

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

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

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

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

エラーハンドラーの使用 uses-of-error-handler

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

失敗／エラー応答形式 failure-response-format

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

   {
    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>
    }

ここで、

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)
    }

ここで、

エラー応答形式のサンプル sample-error-response-format

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

ルールエディターを使用してエラーハンドラーを追加 add-error-handler-using-rule-editor

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

ルールエディターを使用して、次のことができます。

デフォルトのエラーハンドラー関数を追加 add-default-errror-handler

デフォルトのエラーハンドラーは、エラー応答が標準スキーマの場合、またはサーバーサイドの検証エラーの場合に、フィールドにエラーメッセージを表示する機能をサポートしています。
ルールエディターのサービスの呼び出しアクションを使用してデフォルトのエラーハンドラーを使用する方法を理解するために、「ペット ID」と「ペット名」という 2 つのフィールドがある簡単なアダプティブフォームの例を見てみましょう。「ペット ID」フィールドでデフォルトのエラーハンドラーを使用して、外部サービス（200 - OK、404 - Not Found、400 - Bad Request など）を呼び出すように設定された REST エンドポイントが返す様々なエラーを確認します。ルールエディターのサービスの呼び出しアクションを使用してデフォルトのエラーハンドラーを追加するには、次の手順を実行します。

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

カスタムエラーハンドラー関数を追加 add-custom-errror-handler

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

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

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

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

1. カスタムエラーハンドラーを作成 create-custom-error-message

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

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

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

アダプティブフォームにカスタムエラーハンドラーを実装する前に、クライアントライブラリ名が クライアントライブラリカテゴリ ​のクライアントライブラリ名が、.content.xml ファイルのカテゴリオプションで指定された名前と一致していることを確認します。

この場合、クライアントライブラリ名は .content.xml ファイル内の customfunctionsdemo として指定されます。

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

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

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

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

関連トピック see-also