x-ntx-dynamic-values

Use the x-ntx-dynamic-values Specification Extension to populate a drop-down field with a set of options from the API. The drop-down field data is retrieved in separate call to the API A programming interface that defines how software can be interacted with by other software. when the action A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. is being configured.

Looking for an example?

The following examples use x-ntx-dynamic-values:

• Create dynamic fields (x-ntx-dynamic-schema).
• Upload files by streaming.
• Upload files by URL.
• Download files by URL.
• Download base64 files.
• Upload base64 files.
• Add subscribers to Mailchimp.

The API must provide an endpoint The address of a specific resource provided by the third-party API. that returns the data in a valid JSON JavaScript Object Notation: a data format based on JavaScript that is commonly used for API request parameters and responses. format.

1. Create the 'helper' operation that retrieves the data.
2. Create the operation that uses the dynamic data.
3. Inside the dynamic parameter, add x-ntx-dynamic-values.
4. Inside the x-ntx-dynamic-values object, add:
   1. The operationId of the helper operation that retrieves the data.
   2. The value-path, with the property in the helper operation's response to the value you want to use for each option in the drop-down.
   3. The value-title, with the property in the helper operation's response to the label you want to display for each option in the drop-down.
      This field is optional. If you don't specify it, the value-oath value is displayed as the drop-down option.
   4. The value-collection, with the path in the helper operation's response to the value-title and value-path.
      This field is optional, and can be omitted if the value-path and value-title are in the root level of the response.

If the helper operation requires parameters:

1. For static parameters:

   1. Add a parameters object to the x-ntx-dynamic-values object.

   2. Inside the parameters object, add each parameter as a key-value pair.

2. For parameters supplied by the user when configuring the action:
   1. Add a parameters object to the x-ntx-dynamic-values object.
   2. Inside the parameters object, add each parameter required by the helper operation as an object with:
   3. The name of the parameter as the object key.
   4. A single property with the key of parameter and the name of the parameter as the value.

Note: The parameter names should match the parameters defined in the helper operation.

3. For parameters that depend on another dynamic-values operation, see Cascading dynamic values.

Where to use x-ntx-dynamic-values

Use x-ntx-dynamic-values inside parameters or other input properties you want to create a drop-down field for.

You can also use x-ntx-dynamic-values with references. See Streamline with references.

Sometimes one helper operation requires dynamic data from another helper operation. For example:

• A ticketing platform has several departments, and each department has several teams. Tickets belong to teams within the departments.
• A /getTickets operation retrieves all open tickets for a team. It needs a team ID as a parameter.
• The /getTickets uses x-ntx-dynamic-values with the /getTeams operation to retrieve a list of teams.
• The /getTeams operation needs a department ID as a parameter: it uses x-ntx-dynamic-values with the /getDepartments operation to retrieve a list of departments in the organization.

In the action configuration, the Get Open Tickets action will show the required parameters from /getDepartments and /getTeams.

Make sure you pass through any the parameters required by an operation further up the chain.

The operationId of the helper operation to retrieve the drop-down list options from.

"paths": {
  "/getCategories" : {
    "get" : {
      "summary" : "Get a list of categories",
      "operationId": "getCategories",
      "produces": [ "application/json" ],
      "parameters": [ ],
      "responses": {
        "200": {
          "description": "OK",
    	   "schema": {
            [...]
           }
         }
       }
     }
  }
}

The field from the helper operation's response to use as the option valuein the drop-down list.

[
    {
      "name": "Finance",
      "id": "10005"
    },
    {
      "name": "Research"
      "id": "20054"
    }
]

The field from the helper operation's response to display as the option in the drop-down list.

This field is optional.

[
    {
      "name": "Finance",
      "id": "10005"
    },
    {
      "name": "Research"
      "id": "20054"
    }
]

The path to the value-title and value-path in the helper operation's response.

This property is optional. Omit this property if the value-path and value-title properties are at the root level of the response payload.

{ 
  "categories": [
    {
      "name": "Finance",
      "id": "10005"
    },
    {
      "name": "Research"
      "id": "20054"
    }
  ]
}  

Any parameters that need to be passed to the helper operation. These can be static values or dynamic values defined when the action is configured.

Note: These parameters are defined in a parameters object, not an array.

Inside the parameters object, define each parameter you need to pass, using the name of the parameter as it is defined in the helper operation.

Example: The /getRecord operation has two parameters with the names category and status.

To pass a dynamic value to a parameter, define that parameter as an object with the property of parameter and the value of the parameter name.

To pass a static value in a parameter, define the parameter with the value you want to pass.