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:

Parameter	Type	Description
_inputParams	JSON	Specifies 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    }  },  "_timeout": 60}

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.