AppsStudioJSON formsDropdown element

Use the dynamic dropdown form element with adapters

JSON Forms in Itential Platform can integrate with APIs or adapters to fetch, manipulate, and display data. This guide covers how to configure adapter calls in JSON Forms.

The communication in this flow is between Itential Platform and the adapter — not a direct call to the external system. The HTTP method used depends on whether the call requires input: calls with no parameters use GET; calls that require parameters or data use POST, even if the adapter’s call to the external system is itself a GET.

Configure the adapter call within the form

1

Add a dropdown element to the canvas

Drag the Dropdown element onto the empty canvas.

Dragging the Dropdown element onto the form canvas
2

Open the Configure dialog

Hover over the three dots in the upper-right corner of the element, then click the gear icon to edit the dropdown. The Configure dialog appears.

Opening the dropdown Configure dialog
3

Select the Dynamic option

Select Dynamic to enable adapter-backed data fetching.

Selecting the Dynamic option in the Configure dialog
4

Configure the request

Complete the Make Request Configuration fields: Method, Base URL, API Route, and Request Body.

Make Request Configuration fields for the adapter call

Method — Select based on whether the adapter task requires input:

  • POST: Use when the adapter task requires input parameters.
  • GET: Use only when the adapter task accepts no input parameters. Confirm this in the adapter’s documentation.

Note that the JSON Form always sends a request to the adapter; the adapter itself may then call the external system using a different HTTP method (GET, PUT, etc.) as required.

Base URL — Select the adapter you need for the integration. The adapter must already be installed and online in your Itential Platform instance.

API Route — Select the route for the adapter task, which follows the structure /{adapter-task-name}. API routes for adapter calls are defined in the adapter’s pronghorn.json file.

Request Body — Define the payload for the adapter call. This payload must match the JSON input expected by the adapter task, not the external system. The adapter handles translating this into the format required by the external API.

Include all fields expected by the adapter task, even optional ones. Leave optional fields that are not needed empty. For example, if the adapter task expects three inputs — id, name, and body — where only id is required, the Request Body would look like:

1{
2  "id": "123",
3  "name": "",
4  "body": {}
5}
5

Make the API call and review the response

Click Make API Call. The output of the call appears in the Response Body.

For response filtering and other dropdown capabilities, see Use the form element dropdown.

Key considerations

AreaDetails
Base URLPoints to the adapter task endpoint within Itential Platform, not the external system. Example: /adapter-task
HTTP methodUse POST for tasks requiring input. Use GET only when the adapter task has no input requirements.
Request BodyMust match the format expected by the adapter task. The adapter translates the input into the appropriate format for the external API.
PermissionsUsers populating data into the form must have permission to execute the adapter call. This typically requires admin permissions on the adapter.