BPM API

You can use Flowable API to interact with the process engine. This API allows you to start process instances programmatically, complete tasks, and execute various queries, for example, get a list of tasks for a user or get active instances of a process definition.

Flowable services can be obtained in two ways:

  • Using ProcessEngines as a starting point:

    ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();

RuntimeService runtimeService = processEngine.getRuntimeService();
RepositoryService repositoryService = processEngine.getRepositoryService();
TaskService taskService = processEngine.getTaskService();

  • Injecting services inside your beans as they are registered as Spring beans:

    @Component("sample_MyCustomBean")
public class MyCustomBean {

    @Autowired
    private RuntimeService runtimeService;

The add-on provides BpmTaskService that extends TaskService of Flowable. See an example of usage below.

Starting Process Programmatically

In the example below, the process is started programmatically from the regular entity editor using RuntimeService:

@Autowired
private RuntimeService runtimeService;

@Subscribe("commitAndCloseBtn")
public void onCommitAndCloseBtnClick(Button.ClickEvent event) {
    Customer customer = getEditedEntity();
    String name = customer.getName();
    Map<String, Object> params = new HashMap<>();
    params.put("customer", customer); (1)
    params.put("name", name); (2)
    runtimeService.startProcessInstanceByKey( (3)
            "new-customer", (4)
            params); (5)
}
1 Puts the edited entity to the process variable with the customer name.
2 The customer’s name is put to the process variable with a String type.
3 RuntimeService is used to start the process.
4 new-customer is the process definition key.
5 Puts the process variables map.

Getting List of User Tasks

Let’s look at the examples that show getting a list of active tasks assigned to the authenticated user:

@Autowired
private TaskService taskService;

@Autowired
private CurrentAuthentication currentAuthentication;

public List<Task> getCurrentUserTasks() {
    return taskService.createTaskQuery() (1)
            .processDefinitionKey("approval") (2)
            .taskAssignee(currentAuthentication.getUser().getUsername()) (3)
            .active()
            .orderByTaskCreateTime()
            .desc()
            .list();
}
1 Uses TaskService to get a list of tasks.
2 Searches for the tasks of the approval process.
3 Searches for the tasks assigned to the current user.

Getting List of Process Instances

The example below shows getting a list of process instances of the approval definition related to the specified Order entity:

@Autowired
private RuntimeService runtimeService;

public List<ProcessInstance> getActiveProcessInstances() {
    return runtimeService.createProcessInstanceQuery() (1)
            .processDefinitionKey("approval") (2)
            .variableValueEquals("orderId", "N-1") (3)
            .active()
            .list();
}
1 Uses RuntimeService to get a list of tasks.
2 Searches for the instances of the approval process.
3 Searches for the process instances with the specified orderId process variable.

Using BpmTaskService

BpmTaskService extends the TaskService and adds a method for completing tasks with an outcome:

void completeTaskWithOutcome(String taskId, String outcomeId, Map<String, Object> processVariables);

You can inject the service into your Spring component:

@Autowired
private BpmTaskService bpmTaskService;

or use the ProcessEngines class:

BpmTaskService bpmTaskService = (BpmTaskService) ProcessEngines
        .getDefaultProcessEngine()
        .getTaskService();