Skip to main content
Version: v5.1

How to use dynamic inputs in Workflows

Overview​

This page describes how you can use parameters in Workflows to accept user input at runtime.

Dynamic parameters in a Workflow are achieved using one key property in the Workflow definition, namely:

ParameterTypeDescription
_inputParamsJSONSpecifies each input parameter required by the workflow. Contains one or more properties (name of the input parameter) and type (required), value (optional), encrypt (optional)

Tasks within the Workflow can reference this parameter using the ${workflow.input.PARAM_NAME} syntax.

Steps for setting up dynamic user inputs in Workflows​

To set up dynamic user inputs, do the following:

  1. Define Workflow inputs
  2. Reference Workflow inputs in tasks
  3. Run a Workflow with custom parameters
  4. Understand how it works
  5. Follow best practices

Step 1: Define Workflow inputs​

Create the workflow definition by specifying the input parameters using _inputParams.

Refer to the sample code below.

{
  "_name": "rest_connector_workflow",
  "_description": "REST Connector Workflow",
  "_userType": "iaq_realtime_setup",
  "_namespaces": [
    "{{nsfilter}}"
  ],
  "_taskDefs": [
    {
      "_name": "REST_CONNECTOR",
      "_type": "REST_CONNECTOR",
      "_sequenceno": 1,
      "_inputParams": {
        "_url": "${workflow.input._url}",
        "_auth": {
          "_type": "OAuth2ClientCreds",
          "_params": {
            "_tokenUrl": "https://accounts.spotify.com/api/token",
            "_clientId": "xxxxxxx",
            "_clientSecret": "xxxxxxxxxxx",
            "_scope": "user-top-read"
          }
        },
        "_to": "json"
      }
    }
  ],
  "_inputParams": {
    "_url": {
      type: "string", //could support enum in the future
      value: "",
      encrypt: "false" //optional, true or false
    }
  },
}

Note: _inputParams declares the _url value which can be a parameter specified when running the Workflow. This value stores the default URL, if it is specified.

Step 2: Reference Workflow inputs in tasks​

Reference Workflow-level input parameters within each task's _inputparams by using the ${workflow.input.PARAM_NAME} syntax.

Refer to the sample code below.

"_inputParams": {
  "_url": "${workflow.input._url}",
  ...
}

Note: At runtime, ${workflow.input._url} will be replaced with the value provided when the workflow is started.

Step 3: Run a Workflow with custom parameters​

To run a Workflow with custom parameters, POST to the /workflows endpoint with the Workflow definition ID and a map of input parameters.

Refer to the sample request below.

{
  "_workflowDefId": "xxxxxxxxxx",
  "_inputParams": {
    "_url": "https://api.spotify.com/v1/artists/0TnOYISbd1XYRBk9myaseg"
  }
}

Note: The value for _url here will be injected into the Workflow and available to all tasks referencing ${workflow.input._url}.

Step 4: Understand how it works​

Dynamic parameter input in Workflows operates as follows:

  1. Define the required input parameters in _inputParams and optionally provide the default values in the “value” property.
  2. Reference these parameters in your task definitions using ${workflow.input.PARAM_NAME}.
  3. Run the Workflow, supplying values for the parameters in the _inputParams object of your run request.
  4. The Workflow service will substitute the provided values (or defaults) into the tasks at runtime.

Step 5: Follow best practices​

It is best practice to follow these guidelines:

  • Always define all possible runtime parameters in _inputParams.
  • Reference workflow inputs in tasks using the ${workflow.input.PARAM_NAME} syntax for clarity and maintainability.