A very common requirement that I saw in all my projects over the last years, is the update of business data related to a process instance.

Example: A process for handling offer requests of customers. A DB-table for related business data holds information of the current 'state' that should be updated after an offer is sent to a customer by a sales representative.

How to solve with Camunda Platform 7 embedded

In this simple process the state change is modeled as a none intermediate throw event. The Element has a execution listener attached to it. The listener is defined with an expression, that calls a method of a StateService bean from the context and passes a reference and the target state. The reference is the primary key of the business entity that was set as a process-variable upon instance start.

When running Camunda 7 as an embedded engine we have access to the classpath of the embedding application. Implementing the application with spring boot even allows calls to the bean context from within expressions defined in the BPMN model. The expression from this example

${stateService.changeState(execution.getVariable('reference'), 'OFFERED')}

calls the method 'changeState' of a bean named stateService. The value of the instance-variable 'reference' is used as the first method argument, the value 'OFFERED' as the second.

But execution listeners are no more with Camunda Platform 8!
Due to the new architecture of Camunda Platform 8, the engine (Zebee) is decoupled from the business code. Business-logic has to be implemented via JobWorkers that get their work from the engine via gRPC-API and report back on success (or failure).
You might already know that pattern as "External task pattern" that was already support by Camunda 7.

How to solve with Camunda Platform 8

The process looks almost similar. Instead of none intermediate throw event, a service task is used. So that a job worker can pick up the job, the jobType has to be defined - in this case the type is defined as changeState. The target state is provided via a custom header.

In this example the worker is implemented as part of a spring boot application using spring-boot-starter-camunda. The worker is defined with help of the @JobWorker annotation, that links the implementation to the jobType specified in the BPMN model. By using the @JobWorker annotation, the communication to Zeebe for retrieving and completing the job is taken care of for us. Using the annotation the job will be auto-completed after the execution the method. Instance variables and job headers can be accessed via the ActivatedJob wrapper object.

An alternative to model the state change as a service task, we could also use an message intermediate throw event. By using the same jobType as in the first model variant, we can use the exact same worker implementation to do the work.

Of course we are not bound to the use of Java. Due to the architecture of Camunda Platform 8, the worker can be implemented in any desired language. In addition to the official Zeebe clients, the Camunda community already came up with a whole bunch of useful client implementations for different languages and frameworks.

The Camunda Modeler mostly does a good job when it comes to modeling processes intuitively. Starting from an Eclipse based solution to the latest stand-alone version, the experience of quickly designing a business process improved a lot.

For all of us who need some extra customization, for example to accelerate input of values in reoccurring tasks, there is a simple way to create and integrate element-templates.

In a recent project we had a process that was called multiple times from call activities, always with different sets of variable values. I call this flavoring. The example in the following process illustrates what I mean.

We used to flavor the sub process using variables defined in the In Mapping, like in the picture:

I must say this is not the strongest feature of the modeler in terms of usability.

Luckily, it offers the possibility of templating it for these purposes. I added the following json to path/of/modeler/resources/element-templates:

{ 
   "name":"Congrats CallActivity",
   "id":"de.frena.callactivity",
   "appliesTo":[ 
      "bpmn:CallActivity"
   ],
   "properties":[ 
      { 
         "label":"channel",
         "type":"Dropdown",
         "binding":{ 
            "type":"camunda:in",
            "target":"channel",
            "expression":true
         },
         "constraints":{ 
            "notEmpty":true
         },
         "choices":[ 
            { 
               "name":"",
               "value":""
            },
            { 
               "name":"whatsapp",
               "value":"whatsapp"
            },
            { 
               "name":"email",
               "value":"email"
            }
         ]
      },
      { 
         "label":"person to congrat",
         "type":"String",
         "binding":{ 
            "type":"camunda:in",
            "target":"person",
            "expression":true
         },
         "constraints":{ 
            "notEmpty":true
         }
      },
      { 
         "label":"Called Process",
         "description":"the Process Id of the sub process to call",
         "type":"String",
         "value":"Subprocess_ID",
         "editable":false,
         "binding":{ 
            "type":"property",
            "name":"calledElement"
         },
         "constraints":{ 
            "notEmpty":true
         }
      },
      { 
         "label":"business key",
         "editable":false,
         "type":"String",
         "value":"${execution.processBusinessKey}",
         "binding":{ 
            "type":"camunda:in:businessKey"
         }
      },
      {
        "label": "Asynchronous Before",
		"editable":false,
        "type": "Boolean",
        "value": true,
        "binding": {
          "type": "property",
          "name": "camunda:asyncBefore"
        }
      },
      {
        "label": "Asynchronous After",
		"editable":false,
        "type": "Boolean",
        "value": true,
        "binding": {
          "type": "property",
          "name": "camunda:asyncAfter"
        }
      }
   ],
   "entriesVisible":{ 
      "id":true,
      "name":true
   }
}

After reloading the modeler you can choose the Element-Template for any Call activity and fill in the values in a more efficient way.

Benefits:

1. helps in an environment of reoccurring modelling of the same task.
2. helps to easily review entered values with one click on the task.

Tips and Tricks:

1. While 'implementing' the json file, the modeler must be restarted after every save of json. To do so, hit F12 Key in modeler. This opens chrome developer tools. Leave them open. Now simply hit Ctrl-R to reload the modeler in a faster more elegant way. Don't forget to save. This Tip I got from Nico Rehwaldt at CamundaCon 2019. Thanks alot!
2. Checkout the camunda modeler project and have a look at sample.json for all the possibilites you have.

Let me know what you think and if I can help you to understand this better. This was just a rough nutshell.

Remember the times you knew alot about unit testing but would never think of actually seeing your precious models as units? Well, times changed and nowadays I really enjoy the good feeling of knowing that a 100% BPM testcoverage is relatively easy to achieve.

A very developer friendly way to create tests for process models is brought to us by Martin Schimak, with camunda bpm assert scenario:

"This community extension to Camunda BPM enables you to write robust test suites for process models. The larger your process models, the more often you change them, the more value you will get out of using it."

Check it out! You wont regret it.

The idea of a scenario test though is to really create an end-to-end scenario including execution of all sub processes. But sometimes I dont need or want this - so if there is one thing I would add to this project it's the ability to mock call activities. Hence seeing only the main process as unit under test.

But you can achieve this mocking anyway by simply deploying a mock-process model on the fly, no xml file needed, using  Camundas BPMN model (fluent) api. Check this out:

Lets pretend this would be our process under test and we are not interested in taking care of the called subprocess. We just want to mock it and its behaviour. All we want is to test, if the main process works.

We run a testcase like this:

@Test
public void test_rejection() {
    deployMockedSubProcess("reject");
    Scenario scenario = Scenario.run(process).startByKey("process").execute();
    ProcessEngineAssertions.assertThat(scenario.instance(process)).hasPassed("EndEvent_Rejected");
  }

As you can see, before we actually kick off the process, we deploy a lightweight process model on the fly which will produce a mocked outcome. In this case we set the outcome to reject. Note: The id of this mock has to be the same id the main process is loocking for. In our case it is thesubprocess.

Here is the method:

private void deployMockedSubProcess(String result) {
    BpmnModelInstance modelInstance = Bpmn.createExecutableProcess() //
        .id("thesubprocess") //
        .startEvent() //
        .serviceTask().camundaResultVariable("result").camundaExpression(result) //
        .endEvent() //
        .done();

    Deployment deployment =
        rule.getProcessEngine().getRepositoryService().createDeployment()
            .addModelInstance("thesubprocess" + ".bpmn", modelInstance).deploy();
   
  }

In alot of cases this really suffices and it is a handy way to getting things done if you do not want to go full scenario.

check out and run the code

https://github.com/stefanfrena/camunda/tree/master/assert-scenario-mock-call-activity

Let me know what you think and if I can help you to understand this better. This was just a rough nutshell.

During the implementation of tasklists we should always think about runtime behaviour in a production scenario.
But lets be honest - first of all backend devs are more interested in data quality than response time (<2 secs). So in every developers life there comes the day he gets a speeding ticket.

The main problem during the retrieval of tasks and coresponding data often is, that user tasks are created and stored in the camunda schema (ACT_RU_TASK table) while business data (that has to be presented to the user) is stored in another business-related schema. So you may first

1. retrieve a camunda task list
2. followed by iterating over this list to get some IDs (customer, account) from the coresponding process variables to
3. collect data from your business-related tables (using those IDs) and
4. create a business task list using these entities.

Might take a while right...?

To solve this dilemma and make things performant camunda documentation suggests custom queries which is a fine approach if you can manage to have all your data in one place:

"Precondition: In order to use your own MyBatis (or all types of SQL) queries, your domain data and the process engine data must be stored in the same database. Otherwise you cannot technically construct a single SQL query, which is our goal in terms of performance optimization", [camunda documentation].

Unfortunately this was just not possible in a recent customer scenario so we went with a kind of unusual way:

Redundant user task management

The basic idea is to have a representation of each and every user task of your engine stored somewhere else in a spezialized table. And this representation contains exactly the information needed by the user.

Since we could not change the way on how to retrieve data while creating a task we changed the when! Imagine a task list containing 10 tasks and each task needs 1 second to get fully loaded with additional data. It takes 10 secs every time the task list is requested. Instead we now run this "1-second-running code" only once at task creation (before the user even takes notice of its existence) and store a co-responding record to our specialized table.

Requesting a task list now just means to query that specialized table. This sped up things a lot in our application.

Further thoughts:

1. Yes yes yes I know. Holding "same" data in different places and having to keep it in sync is nothing you want to do on a frequent base. There are lots of developers who do not really like this idea. You should maybe just use it for important tasklists that cannot be sped up in other ways.
2. The above shown example uses two service tasks for crating and removing a user task. This is just for the purpose of clarification. In our scenario, we worked with listeners at start and end of task creation.  This also has the important effect that you can use the actual taskId when storing and deleting it!

Let me know what you think and if I can help you to understand this better. This was just a rough nutshell.

In a recent project I was faced by a real classic in user task management. The age old question about how to handle holiday replacement the right way.

In this post I am going to explain my approach using as much of camunda ready-to-use functionality to avoid overhead.

Situation: Jack needs holidays and leaves for a week. John, the substitute, jumps in. He now has to deal with all of Jacks existing and newly created tasks.

A first approach often presented by developers is to postpone user assignment to the very last second before a user task is created. This can be done by some piece of code e.g. asking ldap for help.

But what about tasks already assigned to Jack? How can John get them to show up in his task list? The above mentioned solution does not work here.
The solution I was thinking of had to handle the following requirements:

1. assign new user tasks to the substitute collegue(s)
2. assign already existing user tasks to the substitute collegue(s)
3. holiday jack still can access all of his tasks (including new ones)
4. do not iterate over every single task and update the assignee

This is what I did: Instead of filling the assignee field of a user task during process modelling I made use of candidate groups. A candidate group contains all the users that have the right to work on a task.

For simplicity, lets call the candidate group "jacks_tasks". You can create it in camunda cockpit or using camunda's identity service at runtime. Create a user Jack and add him to his own candidate group.
Something like this (using IdentityService):

Group jacksGroup = identityService.newGroup("jacks_tasks");
identityService.saveGroup(jacksGroup);

User jack = identityService.newUser("Jack");
identityService.saveUser(jack);

identityService.createMembership(jack, jacksGroup);

I used a listener on task creation which ran the code in order to set up group and user straight before assignment.

To make sure Jack gets his task list filled (while not on holidays) you don't query for him as assignee but task candidate user (even the effort of refactoring this in an existing project isn't that bad):

List<Task> list = taskService.createTaskQuery().taskCandidateUser("Jack").list();

Note: the user Jack here is just a simple camunda user even without permission to log into camunda task list. Use any (external) user id you prefer and/or need in order to retrieve usertasks.

Now comes the substitution part

Create (even on the fly) a user John, add him to the candidate group jacks_tasks and John will have access to all of Jacks tasks immediately with this single configuration step.

User john = identityService.newUser("John");
identityService.saveUser(john);
identityService.createMembership(john, jacksGroup);

You don't need to iterate over dozens of tasks and update the assignee! Add more users to the group if John needs backup. Jack (member of the group) still can access his tasks. Nice and shiney.

Further thoughts:

1. Yes I know, it is not very likely that Jack just leaves the office without notice. But think about a scenario where he calls in sick... But still, what about a foreseeable absence coming up? For that purpose we built a self-service for Jack and his collegues to configure substitution for a certain timespan. A util process takes care of the rest:  
2. To prevent the camunda workflow engine from containing tons of generated users without any task (and hence purpose), you could clean up users and candidate groups in intervals/at process end. Take a look at this:

//get all users in jacks_tasks
List<User> userList = identityService.createUserQuery().memberOfGroup("jacks_tasks").list();

for (User user : userList) {
  List<Task> list = taskService.createTaskQuery().taskCandidateUser(user.getId()).list();
  //delete user if he has not tasks atm
  if(list.size() == 0){
    identityService.deleteUser(user.getId());
  }
}

List<Task> list = taskService.createTaskQuery().taskCandidateGroup("jacks_tasks").list();
//delete group if it has no tasks atm
if(list.size() == 0){
  identityService.deleteGroup(groupId);
}

check out and run the code

https://github.com/stefanfrena/camunda/tree/master/holiday-replacement

This approach works fine and I think it is a fine base for further requirements in user task management. Let me know what you think and if I can help you to understand this better. This was just a rough nutshell.

Welcome to this blog about our idea(s) of workflow automation and integration. We want to use it to discuss thoughts, patterns, suggestions, nutshells and bombshells.