Human

The Human task enables human interaction into the middle of a workflow. When a workflow reaches a Human task, a form is assigned to a user or group to be filled. The Human task waits for the interaction to complete and records the user input before proceeding with the next task. A Human task can be used for a variety of human-involved tasks, such as manual approval in an approval workflow or a user intake form in a hotel booking workflow.

To support human-involved tasks, the Human task can be used alongside the following Orkes features:

• User Forms—A form builder to create user forms hosted on your Conductor cluster.
• Human Tasks API—A suite of APIs that manage the lifecycle of Human tasks connected to Conductor workflows.

For a full guide on how to use human-involved tasks, refer to the Human Task Orchestration guide.

Task configuration

During workflow creation, the Human task can be configured for:

• 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.
  • If not configured, the Human task will not be limited to a certain group or user and anyone can complete the form.
  • Multiple assignment policies can be added to create a multi-level assignment chain. If the first group fails to pick the assignment within the specified timeframe, the task will be escalated to the next assigned group.
  • Additional assignment policies cannot be added if the preceding assignment policy has no specified expiry timeframe.
• Trigger policy—Trigger a workflow to start if the task state or details change.

Configure these parameters for the Human task.

Parameter	Description	Required/ Optional
displayName	The task display name, which will appear on the connected UI for the user. Use a unique human-friendly name (for example, “Loan Approval” or “Booking Form”).	Required.
userFormTemplate	The user form template associated to the Human task. This form will be assigned when the Human task is executed. Note: If you haven’t created the user form, go to Definitions > User Forms and set it up. Refer to the documentation for creating user forms.	Optional.
userFormTemplate. name	The name of the user form that will be assigned.	-
userFormTemplate. version	The version number of the user form that will be assigned.	-
assignments	The assignment policy for the Human task.	Optional.
assignments. userType	The type of user or group that will be assigned to the task. Supported values: External User—The assignee is a user residing outside the Conductor cluster in an external system. External Group—The assignee is a group residing outside the Conductor cluster in an external system. Conductor User—The assignee is a user in the Conductor cluster. Conductor Group—The assignee is a group in the Conductor cluster.	-
assignments. user	The user or group ID for the assignee. The value depends on the user type. External User—Provide the user's email that is managed and verified in an external system. External Group—Provide the name of the group that is managed and verified in an external system. Conductor User—Provide the user’s Conductor email. Conductor Group—Provide the Conductor group name.	-
assignments. slaMinutes	The duration in minutes for which the Human task will be assigned. Use 0 minutes for a non-expiring duration.	-
assignmentCompletion Strategy	The action that will occur if the assignment policy times out. Supported values: 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”.	Required.
taskTriggers	The trigger policy for the Human task.	Optional.
taskTriggers. triggerType	The condition that will trigger a specified workflow. Supported conditions are: Pending—A workflow will be triggered if the Human task enters the Pending state. Assigned—A workflow will be triggered once the Human task is assigned to a specific assignee. In Progress—A workflow will be triggered if the Human task enters the In Progress state. Completed—A workflow will be triggered if the Human task enters the Completed state. Timed Out—A workflow will be triggered if the Human task times out. Assignee Changed—A workflow will be triggered if the assignee changes due to the assignment policy or because the task has been left open and picked by anyone. Claimant Changed—A workflow will be triggered if the claimant changes.	-
taskTriggers. startWorkflowRequest	The details of the workflow to be triggered, including its name, version, input parameters, correlation ID, and task-to-domain mapping.	-

In addition, you should also configure Human task’s inputParameters, which contain the fields taken from its associated user form template. The configuration depends on the input source:

• If the field is to be filled up by the assignee, leave the parameter value empty.
• 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.

Task definition

This is the JSON schema for a Human task definition.

{
  "name": "human",
  "taskReferenceName": "human_ref",
  "inputParameters": {
    "__humanTaskDefinition": {
      "assignmentCompletionStrategy": "LEAVE_OPEN",
      "displayName": "Complete Your Booking",
      "userFormTemplate": {
        "name": "someFormName",
        "version": 1
      },
      "assignments": [
        {
          "assignee": {
            "userType": "EXTERNAL_GROUP"
            "user": "someId",
          },
          "slaMinutes": 0
        }
      ],
      "taskTriggers": [
        {
          "triggerType": "COMPLETED",
          "startWorkflowRequest": { //workflow name, version, parameters, and so on}
        }
      ]
    },
    "FormField": "", // corresponsing task input parameters, left empty for user input
    "anotherFormField": "someValue", // value should be passed if the form field is set as read-only
    "BooleanField": false
  },
  "type": "HUMAN"
}

Task output

The Human task will return a JSON object containing the form response.

Adding a Human task in UI

Before adding a Human task to a workflow, you should complete the following:

• Create a user form template in Orkes’ User Form studio.
• Define a Human task in Definitions > Tasks.

For a full guide on how to use human-involved tasks, refer to the Human Task Orchestration guide.

To add a Human task:

1. In your workflow, select the (+) icon and add a Human task.
2. In Task Definition, select a Human task definition.
3. Enter the Task display name, which will appear on the connected UI for the user. Use a unique human-friendly name, such as “Loan Approval” or “Booking Form”.
4. Select the UI template previously created in the User Form studio and its Version.
5. (Optional) Add an assignment policy to control who can fill out the form.
   1. In Assignment policy, select (+) 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 access an external UI to complete the task.
      • Conductor User or Group—Select this if the assignees are Conductor users, and access Orkes Platform 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. In After assignments, select the strategy for when the assignment times out.
   5. If needed, add another assignment to create a multi-level assignment chain.
6. (Optional) Add a trigger policy to start new workflows when the state of the Human task changes.
   1. In Trigger policy, select (+) New trigger.
   2. Select the Trigger event.
   3. Select the Workflow to start and its Version.
   4. (Optional) Select Additional inputs to configure the workflow’s input parameters, correlation ID, and task-to-domain mapping.
   5. If needed, add another trigger to start another workflow.
7. In 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.

Examples

Here are some examples for using the Human task.

Expense approval

In this example, an expense approval workflow contains two Human tasks, one for approval by the HR department and another for approval by the Finance department. Since the approval process is the same for both rounds, the same user form template can be re-used across both Human tasks.

The expense name and amount are passed into read-only form fields for the user to view and approve. If the expense has been approved by HR, it will proceed to the next stage of approval. Otherwise, the workflow will terminate. Once the expense has been approved by Finance, a notification workflow will be triggered.

// workflow definition

{
  "name": "expenseApprovals",
  "description": "Approve expenses",
  "version": 1,
  "tasks": [
    {
      "name": "human",
      "taskReferenceName": "human_ref",
      "inputParameters": {
        "__humanTaskDefinition": {
          "assignmentCompletionStrategy": "LEAVE_OPEN",
          "userFormTemplate": {
            "name": "ExpenseApproval",
            "version": 1
          },
          "assignments": [
            {
              "assignee": {
                "user": "HR",
                "userType": "EXTERNAL_GROUP"
              },
              "slaMinutes": 0
            }
          ],
          "taskTriggers": [
            {
              "triggerType": "",
              "startWorkflowRequest": {
                "name": "",
                "version": ""
              }
            }
          ],
          "displayName": "Approve Expenses - HR"
        },
        "expenseName": "${workflow.input.expense}",
        "expenseAmt": "${workflow.input.amount}",
        "approve": false,
        "approveReason": ""

      },
      "type": "HUMAN"
    },
    {
      "name": "HRApproved",
      "taskReferenceName": "switch_ref",
      "inputParameters": {
        "switchCaseValue": "${human_ref.output.approve}"
      },
      "type": "SWITCH",
      "decisionCases": {
        "true": [
          {
            "name": "human_1",
            "taskReferenceName": "human_1_ref",
            "inputParameters": {
              "__humanTaskDefinition": {
                "assignmentCompletionStrategy": "LEAVE_OPEN",
                "userFormTemplate": {
                  "name": "ExpenseApproval",
                  "version": 1
                },
                "displayName": "Approve Expense - Finance",
                "assignments": [
                  {
                    "assignee": {
                      "user": "Finance",
                      "userType": "EXTERNAL_USER"
                    }
                  }
                ],
                "taskTriggers": [
                  {
                    "triggerType": "COMPLETED",
                    "startWorkflowRequest": {
                      "name": "notif",
                      "version": ""
                    }
                  }
                ]
              },
              "expenseName": "${workflow.input.expense}",
              "expenseAmt": "${workflow.input.amount}",
              "approve": false,
              "approveReason": ""
            },
            "type": "HUMAN"
          }
        ]
      },
      "defaultCase": [
        {
          "name": "terminate",
          "taskReferenceName": "terminate_ref",
          "inputParameters": {
            "terminationStatus": "COMPLETED"
          },
          "type": "TERMINATE"
        }
      ],
      "evaluatorType": "value-param",
      "expression": "switchCaseValue"
    }
  ],
  "inputParameters": [
    "expense",
    "amount"
  ],
  "outputParameters": {},
  "failureWorkflow": "",
  "schemaVersion": 2
}