User input
Overview#
The User Input task is a built-in task that pauses workflow execution until an external user provides the required input. Use a User Input task to interrupt automated steps for manual intervention.
Examples of manual interventions include:
- Approval before proceeding such as a manager or QA review
- Data entry, for example, the user must provide missing information
- Decision making, such as choosing between multiple workflow branches
Reacting to User Input tasks#
When the workflow reaches a User Input task, the following occurs:
- The workflow is paused and remains in a waiting state.
- A notification is sent via the Notification Service to a user or system to prompt input.
- Once the user provides the input (through the API), the task is marked as completed, and the workflow resumes. This makes the User Input task useful for human-in-the-loop workflows, where automation needs to stop until a person confirms, edits, or approves the next step.
Defining a User Input task#
JSON structure#
Refer to the sample JSON file below for specifying a User Input task.
{ "_name": "user_input_task", "_type": "USER_INPUT", "_sequenceno": 1, "_sendNotification": "yes", "_notificationId": "12345", "_userInputPermissions": [ { "_userType": "user", "_id": "944f8468-2641-4d71-b8ff-8d00062a46b5" } ], "_inputParams": { "_userInput": { "userChoice": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, } }}
Field descriptions#
| Parameter | Type | Required | Description |
|---|---|---|---|
_name | String | No | The unique name of the task. |
_type | String | Yes | The type of task. Here it is set as"USER_INPUT". |
_sequenceno | Number | No | The execution order of the task within the sequence of tasks. |
_sendNotification | String | Yes | A flag that indicates whether to send a notification or not when the task completes. Values are yes or no. |
_notificationId | String | Yes | A user-defined ID which must be configured in both the user input task and the notification trigger. |
User permissions#
The user permissions define which users can perform the input task.
| Field | Type | Required | Description |
|---|---|---|---|
_userType | String | Yes | Type of user allowed to interact. Enter "user" or "usergroup". |
_id | String | No | Unique user or group identifier. |
Input parameters#
The input parameters defines the user input fields.
| Field | Type | Required | Description |
|---|---|---|---|
_inputParams | Object | No | An object that describes the task's parameters |
_userInput | Object | No | An object that describes any number of user input fields. Each key under _userInput represents a field name, and the value defines its schema. |
userChoice | Object | No | An input parameter of type string with three options to choose from, "pending", "approved", or "rejected" |
User Input API#
To provide the user input, you can use the following API:
/workflowsvc/api/v1/workflows/:workflowid/userinput/:userinputid?nsfilter=:nsfilter
Note: For more information, see Workflow Service REST API.
Request body:
{ "_userInput": { //Input based on schema defined in the workflow definition }}Configuring a notification#
You can configure a notification within the Notification Service by using the following filter parameters:
- event:
com.invicara.model.event.UserInput - namespaces:
<namespace> - notificationId:
<notificationId>