Human Task Orchestration

Business processes often require human input. Orkes Conductor includes features to incorporate human interaction into workflows:

• A user form is a reusable JSON-based schema that defines the form fields and layout.
• Each Human task is linked to a user form, which can be assigned to a user or group.
• The user form can be displayed on your own UI using Orkes’ Human Tasks API.

A Human task can be used for activities that require manual input, such as an approval step in a workflow or a booking form in a reservation workflow. When a workflow reaches a Human task, a form is generated from the predefined user form and assigned to a user or group. Once the form is submitted, the task is marked Complete, and the workflow moves to the next step.

When creating a workflow, a Human task can be configured with:

• Assignment policy—Define who can fill out the form, how long the form is assigned to them, and what to do if the assignment times out.
• Trigger policy—Trigger a workflow to start if the human task state changes.

During development, you can test and execute Human tasks internally on Orkes Conductor before integrating it with your own UI.

Orchestrating human-involved tasks

To orchestrate human-involved tasks:

1. Create a user form schema for the Human task.
2. Define the Human task.
3. Configure the Human task in your workflow definition and set the assignment and trigger policy.
4. Display the user form on your own UI.

Step 1: Create a user form schema

To use a Human task in a workflow, you must first create a user form for it. The User Forms studio on Orkes Conductor allows you to compose user forms easily, using JSON code or the pre-built form components. Once created, these forms can be safely versioned as well.

tip

It is best practice to create forms using Orkes’ User Form studio, even if the form is displayed on your own UI. With the user form schema stored on Conductor, any changes can be instantly reflected on the frontend without any additional development effort.

To create a user form on Orkes Conductor:

1. Go to Definitions > User Forms from the left menu on your Conductor cluster.
2. Select + New form.
3. In Form details, provide a name for the form in Form name.
4. To build the form, drag and drop the pre-built items for Layout and Components and configure each component.
5. Preview your form at any time by selecting Preview on the top right.
6. Once the form is ready, select Save > Confirm on the top right.

Supported form layout and components

Horizontal and vertical layouts are supported for user forms.

Following are the pre-built form components available on Orkes Conductor:

• Boolean
• Multiple Choice
• Date
• Date + Time
• Description Text
• Image
• Number Field
• Text
• Time
• Video
• Radio

note

You can toggle to the Code tab to create custom components for your form. However, all inputs to the form will be part of the Conductor workflow and JSON response, so the input data size should be as small as possible. Refer to this package for more information on Orkes-supported components.

Configuring form components

To configure a component:

1. Select the Edit icon beside the component.
   A pop-up box appears.

   

2. Enter the Field Name, which serves as the input parameter name in the Human task configuration.
3. Enter the Label, which is the text that end-users see when filling out the form.
4. Configure the remaining settings:

Setting	Applicable to	Description
Required	All components except Description Text.	Sets whether the form component is mandatory.
Read-only	All components except Description Text.	Sets whether the form component can accept user input. If the component is read-only, the user cannot fill out the field and the value must be supplied from elsewhere, such as from the workflow parameters.
Boolean default value	Boolean.	Sets whether the default value is true or false.
Items split by commas	Multiple Choice and Radio.	Contains the list of selection items split by a comma.
Alignment	Description Text.	Sets the alignment of the description text. Supported values: Left Center Right Justify inherit
Allow-decimal	Number Field.	Sets whether to allow decimal values as input.
Multiline	Text.	Sets whether the text input box is multiline.
Height	Image and Video.	Sets the height of the image or video.
Width	Image and Video.	Sets the width of the image or video.
Default URL	Image and Video.	Sets the default image or video displayed on the form if it is not supplied from elsewhere.

Step 2: Define a Human task

To use a Human task with your own UI, you must first define the Human task in Definitions > Task.

To define a Human task:

1. Go to Definitions > Task from the left menu on your Conductor cluster.
2. Select + Define task.
3. In Name, enter a unique name for your Human task.
4. In Description, enter the task description.
5. Enter the task details, such as the rate limits, retry settings, timeout settings, and expected inputs and outputs.
6. Select Save > Confirm Save.

Once the task is defined, you can proceed to add it to a workflow definition.

Step 3: Configure the Human task

Add the Human task to your workflow and configure its assignment and trigger policies.

To add a Human task:

1. In your workflow, select the (+) icon and add a Human task.
2. In Task Definition, select the task definition created in Step 2.
3. Configure the human task with the following parameters:

Parameter	Description	Required/Optional
Task display name	The display name for the human task that appears in the human task execution. Use a unique human-friendly name, such as “Loan Approval” or “Booking Form”. Note: Whenever a workflow containing a human task is executed, the execution status of the human task can be viewed under Executions > Human Tasks from the left menu on your Conductor cluster. The name specified under this field can be used to identify your human task execution from the list.	Required.
User form template	Select the User form template previously created in Step 1 and its Version.	Required.
Assignment policy	Add an assignment policy to control who can fill out the form. If not configured, the Human task will not be limited to a certain group or user; anyone can complete the form. To add an assignment policy: Select + New assignment. In Assign, select the User type for the assignee(s) and enter the corresponding user or group ID. External User or Group—Select this if the assignees are managed and verified in an external system, and will access your own UI to complete the task. Conductor User or Group—Select this if the assignees are Conductor users and will access Orkes Conductor to complete the task. Enter the SLA minutes to specify the assignment duration before it times out. Use 0 minutes to set a non-expiring assignment. Notes: Multiple assignment policies can be added to create a multi-level assignment chain. If the first user/group fails to pick the assignment within the specified timeframe, the task will be escalated to the subsequent assignment policy in the order added here. Additional assignment policies cannot be added if the preceding assignment policy has 0 SLA minutes.	Optional.
After assignments	Select the action to be carried out after the assignment policy is timed out. You can select one of the following actions: Leave open—The Human task execution remains open to be picked up by anyone. Terminate—The Human task execution is terminated and marked as deleted, and the workflow fails with the error “Task terminated as no more assignments pending and completion strategy is TERMINATE”.	Optional.
Trigger policy	Add a trigger policy to start new workflows when the state of the Human task changes. The trigger policy works based on the human task state in the Executions > Human Tasks list. To add a trigger policy: Select + New trigger. Select the Trigger event, the Workflow to start, and its Version. Pending—If the human task execution is in the pending state, the trigger workflow is executed. Assigned—Once the human task is assigned to a specific assignee, the trigger workflow is executed. In progress—Once the human task execution is in the progress state, the trigger workflow is executed. Completed—Once the human task execution is completed, the trigger workflow is executed. Timed out—Once the human task execution is timed out, the trigger workflow is executed. Assignee changed—Once the human task assignee changes (as per the assignment policy or if left open and picked by anyone), the trigger workflow is executed. Claimant changed—When the claimant of a human task changes (e.g., if the initially assigned user does not claim the task and it remains open, allowing another user to claim it), the trigger workflow is executed. (Optional) Select Additional inputs to configure the workflow’s input parameters, correlation ID, and task-to-domain mapping. If needed, add another trigger to start another workflow.	Optional.
Input parameters	Configure the form fields depending on the input source: If the field is to be filled up by the assignee, you can leave the parameter value empty or pass in a default value that can be modified before submission. If the field is read-only and will be passed from somewhere in the workflow, enter a parameter value. The value can be passed as a variable.	Optional.

Refer to the Human task reference for more information and examples on configuring the task.

4. Save the workflow.

tip

During development, you can set the assignment policy to Conductor User or Group first to test the form. Once the Human task is connected to your own UI, you can easily switch to External User or Group. Even after making the switch, the form can still be tested internally on Orkes Conductor using the Human Task Inbox.

Step 4: (Optional) Display the form on your own UI

If you are using a custom UI for a Human task, configure it to render the form.

When the Human task begins, the associated user form will be assigned to the user or group defined in the task. The user form can be displayed on your own UI so that assignees can claim and complete user forms without having to log into Orkes Conductor. These external assignees are referenced in the Human task configuration but managed and verified in an external system.

To display the form on your own UI:

1. Create the UI in your preferred language.

Create your own UI to display the user form as desired. Some common display options include an action inbox containing all pending approval items or a multi-page form, each corresponding to one Human task on the Conductor end.

2. Add the Human task to an application and grant permissions for execution.

To use a Human task with your own UI, you need to add the Human task to an application and grant Execute permission to the application.

To add the Human task to an application:

1. Go to Access Control > Applications from the left menu on your Conductor cluster.
2. Select an application that you will be adding your worker to. Otherwise, create an application.
3. In Application roles, enable the Worker role.
4. Select + Create access key.
5. Store the generated credentials safely.
6. In Permissions, select + Add permission.
7. Select the Task tab, search, and add your Human task created in Step 2.
8. Enable the Execute, Read, and Update toggles.
9. Select Add Permissions.

The application can now execute the Human task.

3. Configure the Human task for external form assignment.

If the assignment policy in the Human task is not yet configured, go to the Human task in your workflow definition and ensure that the User type for the assignee(s) is set as External User or Group.

4. Integrate the UI with Conductor.

Use the Human Tasks APIs to connect your external UI with the Conductor cluster. Integrate the UI using the access credentials generated for the application in the previous step.

1. Display all active Human task executions. Call GET human/tasks/search to list Human tasks with Assigned status and Assignee as External Group or External User.
2. Display the user form for each Human task execution. First, call GET human/template using the form name and version to get the user form schema. Then, inject the form inputs from the GET human/tasks/search call into the form schema so that the read-only fields are pre-filled.
3. Submit the form response. First, call POST human/tasks/{taskId}/externalUser/{userId} to claim the Human task. Then, call POST h​​uman/tasks/{taskId}/update to save or submit the form response.

Testing and completing Human tasks in Orkes Conductor

When defining your workflows with Human tasks, you can test and complete the task internally on Orkes Conductor without testing it from your own UI.

To test and complete Human tasks in Orkes Conductor:

1. Run the workflow.
2. Complete the Human task in Orkes Conductor.

Run the workflow

Run the workflow to trigger a Human task execution. The Human task will remain in progress until the human interaction with the user form is complete.

To run the workflow on Orkes Conductor:

1. From your workflow, go to the Run tab.
2. Enter any input parameters as needed.
3. Select Execute.

The workflow (execution) ID is generated. You can use it to view the execution progress and details.

Complete the Human task

As a Conductor user, you can also access all Human task executions on Orkes Conductor. The list of Human task executions can be found in the left navigation menu under Executions > Human Tasks, allowing you to claim and complete pending Human tasks and view past Human task executions.

Depending on your permission level, there are two tab views available on the page:

• Task inbox—As a regular non-admin user, you get the task Inbox view, which lists all the tasks assigned to you or your group or unassigned left open ones.
• Admin search—(applicable only to cluster admins or task creators—who created the workflow containing human tasks) Contains all Human tasks in the Conductor cluster.

To claim a task

To claim a task:

1. Go to Executions > Human Tasks > Task inbox.
2. In the filter box, select Available to view all unclaimed tasks.
3. Select a task.
4. Select Claim to claim a task. Alternatively, select the drop-down arrow > Override claim to claim a previously-claimed task.

Once claimed, you can Update or Complete the task. In addition, you can Release the task to remove your claim so that someone else can claim it.

To skip a task

To skip a task:

In your selected Human task, select Skip to bypass it. Alternatively, select the drop-down arrow > Skip with reason to include a reason for skipping the task.

To assign the task to a different user or group

To assign the task to a different user or group:

1. In your selected Human task, select Assign to a different subject > (+) New assignment.
2. In Assign, select the User type for the assignee(s) and enter the corresponding user or group ID.
   • External User or Group—Select this if the assignees are managed and verified in an external system, and will access your own UI to complete the task.
   • Conductor User or Group—Select this if the assignees are Conductor users and will access Orkes Conductor to complete the task.
3. Enter the SLA minutes to specify the assignment duration before it times out. Use 0 minutes to set a non-expiring assignment.
4. If needed, add another assignment to create a multi-level assignment chain.

Search Human task executions

You can search for Human task executions in Orkes Conductor. The search page provides two views based on your permissions:

• Task inbox – Lists tasks assigned to you, your group, or unassigned tasks available to claim.
• Admin search – Available to cluster admins and human task creators. Lists all Human tasks in the cluster.

Task inbox

The task inbox view is the non-admin regular user view that lists all the tasks assigned to you, your group, or left open.

Task inbox filters

Filter	Description
Task names	Filters based on the task display name specified in the Human task definition. Multiple entries can be selected.
Workflow IDs	Filters based on the workflow execution IDs.
Start time	Filters based on the task execution time.
Output data search	Filters based on the output data.
Input data search	Filters based on the input data.
Full-text search	Searches all data within the execution columns based on an “AND” and “OR” query. For example, “loan" OR "cc3d2dc-18d4-11ef-a811-8a584d19ffea". The search will return all results that contain either the text “loan” or the specific task ID “cc3d2dc-18d4-11ef-a811-8a584d19ffea”. To get results matching both criteria, use “AND” instead of “OR”.

You can also filter the executions by Available, Completed, or All.

Admin search

If you are a cluster admin or task admin (workflow creator for the Human task), you can use the Admin search tab in Executions > Human Tasks to filter and sort through all Human task executions for testing and debugging.

Admin search filters

Filter	Description
Task names	Filters based on the task display name specified in the workflow definition. Multiple entries can be selected.
State	Filters based on the Human task status. Supported values: IN_PROGRESS PENDING ASSIGNED COMPLETED TIMED_OUT DELETED
Definition names	Filters based on the task definition name. Multiple entries can be selected.
Output data search	Filters based on the output data.
Task reference name	Filters based on the task reference name. Multiple entries can be selected.
Start time	Filters based on the task's last updated time.
Input data search	Filters based on the input data.
Full-text search	Searches all data within the execution columns based on an “AND” and “OR” query. For example, “loan" OR "cc3d2dc-18d4-11ef-a811-8a584d19ffea". The search will return all results that contain either the text “loan” or the specific task ID “cc3d2dc-18d4-11ef-a811-8a584d19ffea”. To get results matching both criteria, use “AND” instead of “OR”.
Workflow IDs	Filters based on the workflow (execution) IDs.
Filter by actors	Filters based on Claimant or Assignee.
Actor type	Filters based on the actor type for the selected actor. Supported values: Conductor User Conductor Group External User External Group
User/Group ID	Filters based on a particular user or group ID.