Get started with human task orchestration

BeginnerTime estimate: 15 minutes

Camunda 8 allows you to orchestrate processes with human tasks of any complexity. Utilizing user tasks, you can create and assign tasks to users. Then, users can perform their work and enter the necessary data to drive the business process.

note

If you prefer a video-based learning experience or a more complex example, visit this Camunda Academy course.

This guide introduces you to the basics of human task orchestration. You will create a simple process to decide on dinner, and drive the process flow according to that decision. This process is entirely executable in the browser.

Self-Managed

Have you installed Camunda yet?

Prerequisites

Before getting started, ensure you:

• Can access your preferred code editor or IDE.
• Install Desktop Modeler.

Starting in 8.6.0-alpha2, you can install Camunda 8 Self-Managed as an integrated plain Java application.

For this installation, you must have:

• OpenJDK 21+ locally installed
• Camunda 8.6.0-alpha2 or later

Download and configure Elasticsearch

danger

Disabling Elasticsearch's security packages is for non-production only!

1. Download Elasticsearch 8.9.2 and follow the installation instructions.
2. Navigate to the directory where you installed Elasticsearch, and open /config/elasticsearch.yml. Add the line xpack.security.enabled: false to the bottom of the configuration to disable Elasticsearch's security packages.
3. Start Elasticsearch by running ELASTICSEARCH_HOME/bin/elasticsearch (or ELASTICSEARCH_HOME\bin\elasticsearch.bat on Windows).

Confirm Elasticsearch is running by visiting http://localhost:9200 in a browser. If the response doesn't include version information formatted as JSON, you will need to troubleshoot your installation.

Download and configure Camunda

1. Download and extract the latest camunda-zeebe- release artifact in the Assets section of the release page, starting with 8.6.0-alpha2.
2. Navigate to the directory where you installed Camunda, and open /config/application.yaml. Add the following Elasticsearch exporter as a child of the zeebe/broker configuration element:

zeebe:
  broker:
    ...
    exporters:
      elasticsearch:
        className: io.camunda.zeebe.exporter.ElasticsearchExporter
        args:
          url: http://localhost:9200
          index:
            prefix: zeebe-record

note

Spacing is important! Indent the exporters element four spaces to properly nest the configuration.

Still need help?

Here is the full application.yaml file:

zeebe:
  broker:
    gateway:
      # Enable the embedded gateway to start on broker startup.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_ENABLE.
      enable: true

      network:
        # Sets the port the embedded gateway binds to.
        # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_NETWORK_PORT.
        port: 26500

      security:
        # Enables TLS authentication between clients and the gateway
        # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_SECURITY_ENABLED.
        enabled: false
        authentication:
          # Controls which authentication mode is active, supported modes are 'none' and 'identity'.
          # If 'identity' is set, authentication will be done using camunda-identity, which needs to
          # be configured in the corresponding subsection. See also https://docs.camunda.io/docs/self-managed/identity/what-is-identity/ .
          # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_SECURITY_AUTHENTICATION_MODE.
          mode: none

    network:
      # Controls the default host the broker should bind to. Can be overwritten on a
      # per-binding basis for client, management and replication
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_NETWORK_HOST.
      host: 0.0.0.0

    data:
      # Specify a directory in which data is stored.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_DIRECTORY.
      directory: data
      # The size of data log segment files.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_LOGSEGMENTSIZE.
      logSegmentSize: 128MB
      # How often we take snapshots of streams (time unit)
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_SNAPSHOTPERIOD.
      snapshotPeriod: 15m

    cluster:
      # Specifies the Zeebe cluster size.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_CLUSTERSIZE.
      clusterSize: 1
      # Controls the replication factor, which defines the count of replicas per partition.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_REPLICATIONFACTOR.
      replicationFactor: 1
      # Controls the number of partitions, which should exist in the cluster.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_PARTITIONSCOUNT.
      partitionsCount: 1

    threads:
      # Controls the number of non-blocking CPU threads to be used.
      # WARNING: You should never specify a value that is larger than the number of physical cores
      # available. Good practice is to leave 1-2 cores for ioThreads and the operating
      # system (it has to run somewhere). For example, when running Zeebe on a machine
      # which has 4 cores, a good value would be 2.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_THREADS_CPUTHREADCOUNT
      cpuThreadCount: 2
      # Controls the number of io threads to be used.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_THREADS_IOTHREADCOUNT
      ioThreadCount: 2

    exporters:
      elasticsearch:
        className: io.camunda.zeebe.exporter.ElasticsearchExporter
        args:
          url: http://localhost:9200
          index:
            prefix: zeebe-record

camunda:
  # Operate configuration properties
  operate:
    # Set operate username and password.
    # If user with <username> does not exists it will be created.
    # Default: demo/demo
    #username:
    #password:
    # ELS instance to store Operate data
    elasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
    # Zeebe instance
    zeebe:
      # Gateway address
      gatewayAddress: localhost:26500
    # ELS instance to export Zeebe data to
    zeebeElasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
      # Index prefix, configured in Zeebe Elasticsearch exporter
      prefix: zeebe-record
  # Tasklist configuration properties
  tasklist:
    # Set Tasklist username and password.
    # If user with <username> does not exists it will be created.
    # Default: demo/demo
    #username:
    #password:
    # ELS instance to store Tasklist data
    elasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
    # Zeebe instance
    zeebe:
      # Gateway address
      gatewayAdress: localhost:26500
    # ELS instance to export Zeebe data to
    zeebeElasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # Url
      url: http://localhost:9200
      # Index prefix, configured in Zeebe Elasticsearch exporter
      prefix: zeebe-record

Save the file. Without performing this step, no data will be visible in Operate or Tasklist.

3. To start Camunda, run bin/camunda (or bin\camunda.bat on Windows).

It may take a few minutes for startup to complete. When the message Started StandaloneCamunda in ___ seconds is displayed, the application is ready to use.

tip

Operate can be found at http://localhost:8080/operate and Tasklist can be found at http://localhost:8080/tasklist. Both use a default username/password of demo/demo.

SaaS

Have you signed up for Camunda yet?

Sign Up

Visit signup.camunda.com/accounts to sign up.

Create an account

Fill out the form and click Create account.

When you fill out the form, you'll receive a confirmation email. Click on the link to verify your email address.

Log in to your Camunda 8 account

Log in with the email address and password you used in the previous form, or use the social login buttons. To access the login site directly, navigate to camunda.io.

After login, select the square-shaped Camunda components icon in the upper-left corner, and select Console to view the Console overview page. This is the central place to manage the clusters, diagrams, and forms you want to deploy to Camunda 8.

Take the following five steps to create and run your first process with a human in the loop:

Step 1: Create a new process

In this step, you will design a process that demonstrates how to route the process flow based on a user decision. In this example, you will create a process to decide what is for dinner.

Create a new file

1. Every file in Web Modeler requires a project. Within Modeler, click New project.
2. Name your project and select Create new > BPMN diagram.
3. Give your file a descriptive name. In this case, name it Decide for Dinner.
4. Make sure to name the process itself as well. Click the empty canvas, and specify the process name and technical ID in the properties panel. This specifies how the process will appear in other tools of Camunda 8.

Design the process

note

To run this guide, make sure to be in Implement mode to specify the technical details of the process.

1. A start event is automatically added to the canvas. Click it to display configuration and append options.

2. Click the rectangular Append Task icon to append a task.

3. Enter a descriptive name for the task, such as Decide what's for dinner.

4. Change the task type by clicking the wrench icon. Select User Task.

5. Select the user task and click on the diamond-shaped icon to append an exclusive gateway. The gateway allows to route the process flow differently, depending on conditions.

6. Select the gateway and append a task by clicking the task icon. Repeat it to create a second process flow. Name the tasks based on what the user decides to eat: in this case, we've named ours Prepare chicken and Prepare salad.

7. To route the user to the right task, add expressions to the sequence flows. Sequence flows are represented by arrows connecting the gateway to the tasks. To add an expression, click on a sequence flow to view the properties panel, and open the Condition section.

8. Verify the sequence flows have the following expressions: meal = "Salad" on one side, and meal = "Chicken" on the other. You will define the variable meal later when designing a form for the user task.

   

9. Connect the split process flows again. Append another exclusive gateway to one of the tasks. Select the other task and drag the arrow-shaped sequence flow tool to connect it to the gateway.

10. Select the gateway and add an end event to your process, denoted by the circle with the thick outline.

note

New to BPMN or want to learn more? Visit our BPMN cheat sheet for an overview of all BPMN symbols. Variables are part of a process instance and represent the data of the instance. To learn more about these values, variable scope, and input/output mappings, visit our documentation on variables.

Step 2: Design a form

You have now designed the process. To allow the user to make the decision, you will now design a form. Forms can be added to user tasks and start events to capture user input, and the user input can be used to route the process flow, to make calls to APIs, or to orchestrate your services.

1. Select the user task you created in Step 1.
2. Click the blue link icon in the lower right corner. A menu expands that allows you to create a new form.
3. Click Create new form. A form will be created and opened in the form editor. The form is automatically named.

note

Don't worry about saving your process diagram. Modeler automatically saves every change you make.

4. Click and drag the Text component to the empty form.

   

5. Open the General section in the properties panel and enter a text, such as What's for dinner?.

6. Click and drag the Radio component to the form to create a radio group. Give it a descriptive name within the properties panel.

7. Additionally, set a key which maps to a process variable. The value of the component will be stored in this variable, and it can be read by the process that uses this form. As already defined by the conditions in the process earlier, use the variable meal.

8. Scroll down to the Static options section of the properties panel to add radio options. Since there are two options for the dinner, add an extra value by clicking on the plus sign. Enter the value Chicken with the same label as Chicken and enter the value Salad with the label as Salad in the other value.

Step 3: Link the form to your process

Once the form is designed, you must link it to your process.

1. Click on the project name in the navigation history in the top bar to navigate back, and open the process you created in Step 1.

   

2. Select the user task. Click the blue form link icon to open the form menu.

3. Select the form you just created, and click link to confirm.

   

4. You can check if you linked the right form by clicking the form linking icon again. A preview of the form will appear.

note

Forms linked in the user task are deployed together with the process. If you make changes to a form, you have to deploy the referencing process again to make the changes appear.

Step 4: Run your process

Your process is now ready to run. Given its human-centric nature, it is well suited to be run in Tasklist. In order to make it accessible from Tasklist, the process must be deployed first.

note

Human-centric processes involving user tasks seamlessly unfold within Tasklist, offering a cost-effective orchestration solution for human work with forms. However, the versatility of these processes extends beyond Tasklist, encompassing various alternative methods and applications. For instance, users can be redirected to external applications to fulfill tasks, bespoke task applications can be developed for any domain, or interactions with the physical world can be captured through event signals from sensors and IoT devices.

Deploy and test run

1. Click Deploy to deploy the process to your cluster.
   note

   If you have not yet created a cluster, clicking Deploy will take you to Console to create a cluster first. Continue with this guide after cluster creation.

2. After you deploy your process, it can be executed on the cluster. There are multiple ways to run a process. This time, click Run in Modeler for a test run.

tip

Other options to run a process are to start it via Tasklist, test it in the Play mode, or call it via the API or an inbound trigger. Read more about run options.

Check successful start in Operate

1. The process start will be confirmed via a notification message on the screen. Click the chevron icon next to Run to open more options. Click View process instances to see the running process in Operate.

   

2. In Operate, you will see a visualization of the running process instance. Notice that a green token is waiting at the user task. This means that a task is waiting to be worked on in Tasklist.

   

tip

In production, Operate is used to monitor both long-running and straight-through, high-throughput processes. In development environments, use Operate to confirm if the process flow works as expected. For faster in-place validation during development, use the Play mode.

Step 5: Complete a user task

When the process instance arrives at the user task, a new user task instance is created at Zeebe. The process instance stops at this point and waits until the user task is completed. Applications like Tasklist can be used by humans to complete these tasks. In this last step, you will open Tasklist to run the user task you created.

tip

While it may originally seem like the goal of automating a process is to remove humans entirely, efficiently allocating work through user tasks can be even more beneficial. Within this example, we've included a form to demonstrate the completion of a user task.

Using the Zeebe or Tasklist API, many other ways to complete a user task are possible, such as redirecting to another application to complete the task, or even listening to IoT devices to capture human interaction with the real world via job workers.

1. Click the navigation menu icon next to the Camunda logo in the top bar to open the global navigation.

2. Click Tasklist to open the Tasklist application.

   

3. On the left, you will notice a list of tasks. There should be one open task Decide what's for dinner. Click this task to open it in the detail view.

4. In the detail view, the form you created in Step 2 appears. It is read only since this task is currently unassigned. You have to claim the task to work on it. Next to Assignee, click Assign to me to claim the task.

5. Select one of the radio options.

6. Click Complete Task to submit the form.

7. To verify your task completion, you can filter by Completed tasks in the left task list panel.

You can now navigate back to Operate and notice the process instance has continued as the token has moved forward to the selected option.

The token moves through the exclusive gateway (also called the XOR gateway), and is used to model the decision in the process. When the execution arrives at this gateway, all outgoing sequence flows are evaluated in the order in which they have been defined. The sequence flow which condition evaluates to ‘true’ is selected for continuing the process.

In this case, the token will move through the gateway and (according to the conditional expressions we outlined earlier) to the selected dinner based on the Decide what's for dinner user task we completed. If we select Chicken, the token moves forward to Prepare chicken. If we select Salad, the token moves forward to Prepare salad.

Wrap up

At this point, you've successfully crafted a human-centered process that routes the process flow based on a decision made by a user.

A core value of Camunda 8 lies in the combination of automation and human interaction. Continue with the following resources to learn about intelligent task assignments, flexible forms to capture data and decisions, operational insights to refine task efficiency, and pathways to publish your processes to users via Tasklist or even publicly.

Don't want to build the process yourself? Click this button to create it from a template in Camunda 8 SaaS, or sign up first.

Open model in Camunda 8Sign up

Additional resources and next steps

• Watch the video-based Human Task Orchestration Course.
• Learn how to use BPMN user tasks to route tasks to the right users.
• Learn how to build more complex forms using the form editor.
• Learn how to write powerful expressions and utilize variables to route complex process flows.
• Get an introduction to Operate.
• Learn how to set up Tasklist for efficient task management.
• Explore start forms and attach the form directly to the start event.