Building a Custom Tasklist/Application

A tasklist developed by yourself can be adapted to your needs without compromise. You have freedom of choice among any development framework of any programming language. Tasks are inside your custom application, following your styleguide and usability concept. However, you will probably face a high development effort.
Building a Custom Tasklist/Application

Deciding Which API To Use

Camunda currently offers two APIs to interact with the process engine: the Java API and the REST API. Depending on the UI framework of choice one of the two is normally more natural:

  • Java server side framework (e.g. JSF, Vaadin, …​): Use Java API

  • All other frameworks (HTML5, PHP, …​): Use REST API

See  Drafting A BPM Architecture: API Technology and Deciding About Your Stack: UI Technology Choices for more information.

Planning For Relevant Aspects

When building a custom tasklist/application, you must plan for the following aspects. You will need to

  • query for user tasks and generate lists of those tasks

  • filter the list along specific attributes like e.g. current assignee, candidate groups, etc.

  • select and display the right forms for starting processes and completing tasks

  • use custom/business value data in order to filter with those values and display them correlated with the task list and within forms

  • authorize users to access those lists, filters and forms

Use the documentation of the Process Engine API and especially its TaskService and AuthorizationService as entry points to get started and learn more.

Using the Camunda Form Key Attribute

When a user wants to work on a task, your application needs to present a form. Avoid hard coding dependencies like "show form X for user task Y" to de-couple UI from process changes (as much as possible).

There are exceptions to this rule, for example if you build highly customized user interfaces you might have hard coded dependencies and do not use the form key at all, see the example in Satisfying Special Requirements.

Therefore, leverage the Camunda form key attribute to select the correct form. You can place any custom string into the attribute of the BPMN XML file:

<userTask id="someTask" camunda:formKey="someForm.html">
  ...
</userTask>
...
<startEvent id="startEvent"
  camunda:formKey="{'vaadinConroller': 'com.camunda...StartOrderProcess'}">
  ...
</startEvent>

The attribute is available for BPMN user tasks, in order to show a suitable form for task completion, as well as for start events, in order to show suitable forms to start process instances.

When using the attribute, make sure to define what you want to have in this attribute. It needs to allows you to select and configure the correct form at your application’s runtime. At runtime, you can retrieve the form key via an API call:

String formKey = formService.getTaskFormData(taskId).getFormKey();
// or if you have the Task at hand:
String formKey = task.getFormKey();

It is also contained in the Task properties via the REST API. In this example you see the encoding used for the Camunda Tasklist:

GET http://localhost:8080/engine-rest/engine/default/task/...
{..., "formKey":"embedded:app:forms/assign-approver.html"}

Learn more about User Task Forms in the BPMN implementation reference.

Satisfying Special Requirements

Building a custom tasklist/application allows you to satisfy very special requirements. Just to give an example and stimulate your imagination: you could e.g. face a situation in which

  1. you have several user tasks which are heavily interdependent from a business point of view and

  2. should therefore be completed in one step by the same coworker

The following example shows such a situation in the document input management process of a company: we decided to manage each "document" with a separate process instance, but to present the "mailings" - which consist of several such documents - as "bundled tasks" to the people in charge of quality assuring the scanning process and distributing the parts of that mailing to the responsible departments.

tasklist mockup
1 The custom tasklist shows the mailings as distribution tasks, even though they consist of several "technical tasks", because for each document in the mailing a process instance (and hence a separate distribution task) was created.
2 The custom "task" form allows to work on four technical tasks all at once. By dragging and dropping a document within the tree, the user can choose to which department the document is delivered.
3 In case the user detects a scanning problem, s/he can request a new scan of the mailing. But as soon as all documents are quality assured, the button "Distribute Mailing" gets enabled. By clicking on it, the system completes four technical tasks - one for each document - which moves forward the four process instances associated with the documents.

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.