[AEM Forms]{class="badge positive" title="Applies to AEM Forms)."}

Integrating External APIs with Visual Rule Editor in Core Component Forms

The Visual Rule Editor in an Adaptive Form supports the Invoke Service feature, enabling you to connect to external APIs through Form Data Models (FDM) configured for your instance. You can map form fields directly to the service’s input parameters and use the event payload option to map the output parameters. The Visual Rule Editor also lets you define rules for success and failure handlers based on the service’s response: success handlers handle successful API calls, while failure handlers manage errors.

This allows you to easily send API requests from your form, process the API responses, and display or use the returned data dynamically within the form. It ensures a seamless integration between your Adaptive Form and external systems or data sources.

Advantages of using the Invoke Service in the form’s rule editor

Here are few advantages of using Invoke Service operation in the rule editor of an Adaotive Form:

Invoke Service handlers for success and failure responses

Visual rule editor allows you to create rules for success and failure handlers for Invoke Service operations based on its output responses. Below image depicts the Invoke Service in Visual rule editor for an Adaptive Form:

Adding Success Handler and Failure Handler

To add success or failure handler, click Add Success Handler or Add Failure Handler, respectively.

When you click Add Success Handler, the Invoke Service Success Handler rule editor appears, allowing you to specify rules or logic to manage the Invoke Service output response when the operation is successful. You can specify rules even without defining conditions; however, you can add conditions for the success handler by clicking the Add Condition option.

You can add multiple rules to handle successful responses for the Invoke Service operation:

{width="50%,"}

Similarly, you can add rules to handle the Invoke Service output response when the operation is not successful. The image below displays the Invoke Service Failure Handler rule editor:

You can also add multiple rules to handle unsuccessful responses from the Invoke Service operation.

The Enable Error Validation on Server feature allows validations added by the author while designing an Adaptive Form to run on the server also.

Prerequisites for using the Invoke Service in the rule editor

Below are the prerequisites you must satisfy before using Invoke Service in the rule editor:

Exploring Invoke Service through different use cases

The Visual rule editor’s Invoke Service allows you to perform several useful operations. You can use it to populate dropdown options, set repeatable or simple panels, and validate form fields, all based on the output response of the Invoke Service. Thus, enhancing the flexibility and interactivity of your forms.

The table below describes a few scenarios in which the Invoke Service can be used:

Create a Get Information form that retrieves values based on the input entered in the Pet ID text box. The screenshot below shows the form used in these use cases:

Form Fields

Add the following fields to the form:

NOTE

In the Bind Reference field in the Properties dialog of the form fields, select and navigate to select the binary property you added in the Form Data Model (FDM).

Configuring panels

Set the panels as repetitive with the following constraints:

You can adjust the values of the repetitive panels to suit your requirements.

Data source

In this example, the Swagger Petstore API is used to configure a data source. The Form Data Model is configured for the getPetById service, which retrieves pet details based on the entered ID.

Let’s post the following JSON using the addPet service in the Swagger Petstore API:

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

Rules and logic are implemented using the Invoke Service action in the rule editor on the Pet ID textbox to demonstrate the mentioned use cases.

Let’s now explore the implementation of each use case in detail.

Use Case 1: Populate dropdown values using the output of Invoke Service

This use case demonstrates how to populate dropdown options dynamically based on the output of an Invoke Service.

Implementation

To achieve this, create a rule on the Pet ID text box to invoke the getPetById service. In the rule, set the enum property of the photo-url dropdown to photoUrls in Add Success Handler.

Output

Enter 101 in the Pet ID text box to dynamically populate the dropdown options based on the entered value.

![NOTE]

Dropdown options can also be populated dynamically by invoking a service, parsing the JSON response, and applying custom functions. For more details, see this section.

Use Case 2: Set repeatable panel using output of Invoke Service

This use case demonstrates how to populate repeatable panels dynamically based on the output of an Invoke Service.

Considerations

Implementation

Create a rule on the Pet ID text box to invoke the getPetById service. In Add Success Handler, add another success handler response. Set the value of the tags panel to tags in the rule.

Output

Enter 101 in the Pet ID text box to populate the repeatable panel dynamically based on the input value.

Use Case 3: Set panel using output of Invoke Service

This use case demonstrates how to dynamically set the value of a panel based on the output of an Invoke Service.

Considerations

Implementation

Create a rule on the Pet ID text box to invoke the getPetById service. In Add Success Handler, add another success handler response. Set the value of the categoryname text box to category.name in the rule.

Output

Enter 101 in the Pet ID text box to populate the panel dynamically based on the input value.

Use Case 4: Use output parameter of Invoke Service to validate other fields

This use case demonstrates how to use the output of an Invoke Service to dynamically validate other form fields.

Implementation

Create a rule on the Pet ID text box to invoke the getPetById service. In Add Failure Handler, add a failure handler response. Hide the Submit button if an incorrect Pet ID is entered.

Output

Enter 102 in the Pet ID text box, and the Submit button is hidden.

Use Case 5: Use Event Payload in Navigate To Action in Invoke Service

This use case demonstrates how to configure a rule on the Submit button that calls an Invoke Service and then redirects the user to another page using the Navigate To action.

Implementation

Create a rule on the Submit button to invoke the redirect-api API service. This service is responsible for redirecting the user to the Contact Us form.

You can directly integrate an API as the redirect-api API service into your Rule Editor using the JSON data provided below:

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

In Add Success Handler, configure the Navigate To action to redirect the user to the Contact Us page using the Event Payload parameter. Here, the user can submit their contact details.

Optionally, configure a failure handler to display an error message if the service call fails.

Output

When the Submit button is clicked, the redirect-api API service is invoked. Upon success, the user is redirected to the Contact Us page.

Retrieve Property Values from a JSON array

This is a early-adopter feature. If you are interested, send a quick email from your work address to mailto:aem-forms-ea@adobe.com to request access to the feature.

Adaptive Forms supports invoking a service, processing JSON responses, and populating form fields dynamically. This section describes how to extract property values from a JSON array and bind them to form fields.

Sample JSON Response

The following example represents US sales regions and list of sales representatives:

[
  {
    "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"
  }
]

Custom Function to Extract Property Values

Use the following custom function to extract property values from the JSON array.

/**
 * 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]);

}

The custom function accepts:

The custom function returns a simple array of values.

Use the function in Rule Editor

To retriveve the specific value from the JSON array:

event.payload.invokeServiceResponse.rawPayloadBody

The following example demonstrates how to populate a Sales Department form using this response.

For example, let’s create a Sales Department form which include the Select Region and Select Sales Representative dropdowns.

Step 1: Invoke the service on form initialization

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

Step 2: Populate the Region dropdown

Add a Success Handler for the service call and configure the following action:

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

This rule reads the JSON array, extracts the region property values and assigns the values to the Select Region dropdown.

Similarly, configure the action for the Select Sales Representative dropdown in the Success Handler.

When the form loads the JSON data is returned and the custom function extracts property values and the dropdown is populated automatically:

Frequently asked questions

Q: What happens if I have created a rule using the Invoke Service and then upgrade to the latest version of the core components?

A: When you upgrade to the latest version of the core components, the Invoke Service rule automatically updates to the latest user interface, as it is backward compatible.

Q: Can I add multiple rules to handle successful or failure responses for the Invoke Service operation?

A: Yes, you can add multiple rules to handle successful or failure responses for the Invoke Service operation.

Related articles

Additional resources