Integrating a Third Party Tasklist

Using a 3rd party application that comes with a prebuilt tasklist and is compatible with Camunda may bring multiple benefits. For example, rollouts are seamless to end-users since any view changes will be unnoticed while tasks will pop up in their own tasklist anytime. Camunda provides all the necessary hooks to get the job done, but your third party tasklist needs to allow for programmatic control of the lifecycle of a task.
Integrating a Third Party Tasklist

Planning For Relevant Aspects

When integrating a third party tasklist, you must plan for the following aspects. You will need to take care of

  • creating tasks in the third party tasklist based on the user tasks created by Camunda

  • completing tasks in Camunda and move on process execution based on user action in the third party tasklist

  • cancelling tasks, triggered by Camunda or triggered by the user in the third party tasklist

  • transferring business data to be edited in the third party tasklist back and forth

Requirements For the Third Party Tasklist

Camunda provides all the necessary hooks to get the job done, but your third party tasklist application also needs to allow for some programmatic control of the lifecycle of its tasks. The third party application must have the ability

  1. To programmatically create a new task

  2. To hook in code which programmatically informs other systems that the user is about to change a task’s state

  3. To manage custom attributes connected to a task and programmatically access them

Additionally, it should have the ability

  1. To programmatically delete a task which was cancelled in Camunda

Without this last possibility such tasks remain in the users tasklist and would need to be removed manually. Depending on the way you integrate the task completion mechanism, when the user tries to complete such tasks, she would immediately see an error or the action would just not matter anymore and serve as a removal from the list.

Creating Tasks

When reaching a User Task in your BPMN process instance you have to create the task in the third party tasklist.

Implement a task listener, which executes custom code when Camunda creates a new user task:

class ThirdPartyTaskListener implements TaskListener {

    @Override
    void notify(DelegateTask task) {
       switch(task.eventName) {
           // ...
           case EVENTNAME_CREATE: create(task); break
           // ...
       }
    }

    private static void create (DelegateTask task) {
        // call third party tasklist API to synchronize a new Camunda task (1)
    }

    //...

}
1 The third party application must provide some mechanism which allows to programmatically create a new task.
When you want to have this TaskListener for every user task you can use a ParseListener which adds it everywhere, so you don’t have to adjust the BPMN model. See BPMN Parse Listener to see how this can be done, and how it is hooked into the process engine by a ProcessEnginePlugin.

You can leverage a synchronous mechanism, e.g. by executing synchronously implemented Web Service or REST Calls, or asynchronous mechanisms like e.g. putting a JMS message into a queue. You will always need to deliver the Camunda taskID to the third party tasklist as well as business data relevant for task completion.

If possible push just important references like e.g. customerIds, orderIds or maybe simply the taskId from Camunda to the third party tasklist and pull all other business data relevant for task completion via your third party application when the user starts to work on the task form. You can then also pull data via other interfaces and third party systems.

Updating Tasks

Since Camunda 7.12 update events are supported. When a task local variable or other attributes of the task are changed in the engine, the event listener can propagate the changes to the third party tasklist.

Completing Tasks

Based on user actions in the third party tasklist, you will need to inform Camunda about a task completion, so that it correctly moves on with process instance execution.

The third party application must therefore provide a mechanism to hook in some custom code which gets executed in case the user completes (or at least: edits) a task.

You can leverage a synchronous mechanism, e.g. by directly calling the Camunda REST API, or an asynchronous mechanism like e.g. putting a JMS message into a queue. Both approaches can be combined by calling your custom Web Service or REST service as a layer in between allowing for e.g. authorization, data validation and storage.

When deciding for synchronous/asynchronous mechanisms or a combination of both, consider which (e.g. data validation, user authorization) steps have to be executed so that you can make sure that the task can be completed in Camunda as long as it is technically available. From a user perspective synchronous feedback about permanent problems (e.g. authorization or data related) is often preferable, because asynchronous feedback would mean that you have to technically reopen a task which was already completed by the user of the third party tasklist application.

Cancelling Tasks

Your process definition can provide for situations which require the cancellation of a user task, e.g. because a final deadline for task completion was missed or because an external message provided the needed information to move on, etc. As was the case with new tasks you will want to synchronize the fact that a task was cancelled by the process engine to the third party tasklist by removing it there.

Extend your task listener to also execute custom code when Camunda cancels an existing task:

class ThirdPartyTaskListener implements TaskListener {

    @Override
    void notify(DelegateTask task) {
       switch(task.eventName) {
           // ...
           case EVENTNAME_DELETE: delete(task); break
           // ...
       }
    }

    // ...

    private static void delete (DelegateTask task) {
        // call third party tasklist API to delete a canceled Camunda task (1)
    }

}
1 The third party application must provide some mechanism which allows to programmatically delete tasks.

Eventually it is also possible that the user cancels/deletes tasks in the third party tasklist which are actually part of a Camunda process instance execution. Camunda does have a possibility to correctly deal with such an action for standalone tasks, but not for user tasks belonging to a BPMN process instance. Make sure, that you either disallow such an action directly in your Third Party Tasklist or that you handle these cases properly, e.g.

  • A task, which is not removable in Camunda, re-emerges in your Third Party Tasklist (by re-opening the deleted task or creating a new task)

  • Model the deletion of the task explicitely in your BPMN process as Message Boundary Event.

Leveraging the Camunda FormKey

Typically, you will want to configure a form in your third party tasklist, but then you need to select the correct form based on the information attached to a task. To achieve this, you can leverage the Camunda form key, which is a String where you can add whatever data you like in order to identify your form. Learn more about the mechanism in our Best Practice about Building a Custom Tasklist/Application.

In principle you can also use the form key to embed complex (e.g. JSON) data strings. However, if you need more complex reference data than a string to select your third party tasklist form, you might want to leverage extension elements, in particular the freely usable camunda:properties element - which you even can maintain by means of custom Camunda Modeler Templates. This way you can make your custom camunda:properties editable in the properties pane of Camunda Modeler.

Transferring Business Data

Transfer just the minimal amount of business data in between Camunda and your third party tasklist application.

For creating tasks, transfer just the taskId and important business data references/ids to your domain objects. As much as possible should be retrieved later, and just when needed (e.g. when displaying task forms to the user) by requesting data from the process engine or by requesting data directly from other systems.

For completing tasks, transfer just the business data which originated from Camunda and was changed by the user. This means, in case you just maintain references, nothing needs to be transferred back. All other business data changed by the user should be directly transfered to the affected systems.

As a consequence, you may have to face that your loosely coupled architecture does not allow to commit all the necessary updates (business data updates and the task completion for Camunda) within one transactional operation. To deal with that, consider to call the task completion for Camunda as last step, to catch any exception arising in any of the called systems and to react to such an exception by re-establishing an open user task within the third party tasklist. The user can revisit that task later and deal with the presented business data situation.

Considering a Synchronization Troubles Detection

While your architecture should reach out to transactionally secure the correct synchronisation of Camunda tasks with the third party tasklist, chances are that there remains some room for seldom inconsistencies, especially when remote system calls are involved. Consciously judge your architecture with respect to the probability with which it remains possible that certain events are not synchronized in between Camunda and your third party tasklist application.

Is it possible that

  • A new task does not become visible in your third party tasklist?

  • A completed task is not completed in Camunda?

  • A cancelled task is not removed from your third party tasklist?

  • A task is correctly removed from your third party tasklist but not cancelled within Camunda?

If your architecture must accept such possibilities, consider to implement a fallback mechanism which polls the third party tasklist application status in acceptable intervals and ensures correct synchronization of detected mismatches.

Examples of 3rd party tasklists that customers use with Camunda

  • Siebel

  • Salesforce

  • Homegrown task lists implemented before the first Camunda project

No guarantee - The statements made in this publication are recommendations based on the practical experience of the authors. They are not part of Camunda’s official product documentation. Camunda cannot accept any responsibility for the accuracy or timeliness of the statements made. If examples of source code are shown, a total absence of errors in the provided source code cannot be guaranteed. Liability for any damage resulting from the application of the recommendations presented here, is excluded.

Copyright © Camunda Services GmbH - All rights reserved. The disclosure of the information presented here is only permitted with written consent of Camunda Services GmbH.