Chapter 12. Human Tasks Management

The task permissions matrix below summarizes the actions that specific user roles are allowed to do. The cells of the permissions matrix contain one of three possible characters, each of which indicate the user role permissions for that operation:

User roles are assigned to users by the definition of the task in the JBoss BPM Suite (BPMN2) process definition.

Permissions Matrices

The following matrix describes the authorizations for all operations which modify a task:

Human tasks are similar to any other external service that are invoked and implemented as a domain-specific service. As a human task is an example of such a domain-specific service, the process itself only contains a high-level, abstract description of the human task to be executed and a work item handler that is responsible for binding this (abstract) task to a specific implementation.

You can plug in any human task service implementation, such as the one that is provided by JBoss BPM Suite, or may register your own implementation. The Red Hat JBoss BPM Suite provides a default implementation of a human task service based on the WS-HumanTask specification. If you do not need to integrate JBoss BPM Suite with another existing implementation of a human task service, you can use this service. The Red Hat JBoss BPM Suite implementation manages the life cycle of the tasks (such as creation, claiming, completion) and stores the state of all the tasks, task lists, and other associated information. It also supports features like internationalization, calendar integration, different types of assignments, delegation, escalation and deadlines. You can find the code for the implementation in the jbpm-human-task module. The Red Hat JBoss BPM Suite task service implementation is based on the WS-HumanTask (WS-HT) specification. This specification defines (in detail) the model of the tasks, the life cycle, and many other features.

The human task service exposes a Java API for managing the life cycle of tasks. This allows clients to integrate (at a low level) with the human task service. Note that, the end users should probably not interact with this low-level API directly, but use one of the more user-friendly task clients instead. These clients offer a graphical user interface to request task lists, claim and complete tasks, and manage tasks in general. The task clients listed below use the Java API to internally interact with the human task service. Of course, the low-level API is also available so that developers can use it in their code to interact with the human task service directly.

A task service (interface org.kie.api.task.TaskService) offers the following methods for managing the life cycle of human tasks:

  ...
  void start( long taskId, String userId );
  void stop( long taskId, String userId );
  void release( long taskId, String userId );
  void suspend( long taskId, String userId );
  void resume( long taskId, String userId );
  void skip( long taskId, String userId );
  void delegate(long taskId, String userId, String targetUserId);
  void complete( long taskId, String userId, Map<String, Object> results );
  ...

The common arguments passed to these methods are:

To make use of the methods provided by the internal interface InternalTaskService, you need to manually cast to InternalTaskService. One method that can be useful from this interface is getTaskContent():

Map<String, Object> getTaskContent( long taskId );

This method saves you from the complexity of getting the ContentMarshallerContext to unmarshall the serialized version of the task content. If you only want to use the stable or public API’s, you can use the following method:

import java.util.Map;

import org.jbpm.services.task.utils.ContentMarshallerHelper;
import org.kie.api.task.model.Content;
import org.kie.api.task.model.Task;
import org.kie.internal.task.api.ContentMarshallerContext;
import org.kie.internal.task.api.TaskContentService;
import org.kie.internal.task.api.TaskQueryService;

...

Task taskById = taskQueryService.getTaskInstanceById(taskId);
Content contentById = taskContentService.getContentById
  (taskById.getTaskData().getDocumentContentId());
ContentMarshallerContext context = getMarshallerContext(taskById);
Object unmarshalledObject = ContentMarshallerHelper.unmarshall
  (contentById.getContent(), context.getEnvironment(), context.getClassloader());

if (!(unmarshalledObject instanceof Map)) {
  throw new IllegalStateException
    (" The Task Content Needs to be a Map in order to use this method and it was: "
    + unmarshalledObject.getClass());
}

Map<String, Object> content = (Map<String, Object>) unmarshalledObject;

return content;

For a list of Maven dependencies, see example Embedded jBPM Engine Dependencies.

In order to get access to the Task Service API, it is recommended to let the Runtime Manager ensure that everything is setup correctly. From the API perspective, if you use the following approach, there is no need to register the Task Service with the Process Engine:

import java.util.List;

import org.kie.api.runtime.KieSession;
import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.api.task.TaskService;
import org.kie.api.task.model.TaskSummary;
import org.kie.internal.runtime.manager.context.EmptyContext;

...
RuntimeEngine engine = runtimeManager.getRuntimeEngine(EmptyContext.get());
KieSession kieSession = engine.getKieSession();

// Start a process:
kieSession.startProcess("CustomersRelationship.customers", params);

// Do task operations:
TaskService taskService = engine.getTaskService();
List<TaskSummary> tasksAssignedAsPotentialOwner = taskService
  .getTasksAssignedAsPotentialOwner("mary", "en-UK");

// Claim task:
taskService.claim(taskSummary.getId(), "mary");

// Start task:
taskService.start(taskSummary.getId(), "mary");
...

For a list of Maven dependencies, see example Embedded jBPM Engine Dependencies.

The Runtime Manager registers the Task Service with the Process Engine automatically. If you do not use the Runtime Manager, you have to set the LocalHTWorkItemHandler in the session to get the Task Service notify the Process Engine once the task completes. In Red Hat JBoss BPM Suite, the Task Service runs locally to the Process and Rule Engine. This enables you to create multiple light clients for different Process and Rule Engine’s instances. All the clients can share the same database.

Task variables can be accessed in the TaskEventListener for process instances.

The task service data model is illustrated in the following image. In this section, each entity of the database model is described in detail.

Tasks

The Task table stores information about a particular task.

The Task table stores also the information about an input and output task content in the following attributes:

The faultAccessType, faultContentId, faultName, and faultType attributes follow the same logic as the attributes described in the previous table, with the difference that they are used by failed tasks. While the completed tasks have an output document assigned (which can be for example a HashMap), the failed tasks return a fail document.

Task comments are stored in the task_comment table. See a list of task_comment attributes below:

For more information about task data model, see Section 13.2, “Audit Log”.

Entities and People Assignments

Information about particular users and groups are stored in the OrganizationalEntity table. The attribute DTYPE determines whether it is a user or a group and id is the name of a user (for example bpmsAdmin) or a group (for example Administrators).

See a list of different types of people assignments below. All the assignments have the following attributes: task_id, entity_id.

Reassignments

It is possible to set a reassignment time for each task. If the task has not started or has not been completed before the set time, it is reassigned to a particular user or a group.

The reassignments are stored in the Reassignment_potentialOwners table, where task_id is a unique ID of a task and entity_id is a user or a group to which a task is assigned after the deadline.

The Escalation table contains the unique ID of an escalation (id), the ID of a deadline (Deadline_Escalation_Id), and the deadline name (name) which is generated by default and cannot be changed.

The Deadline table stores deadline information: the unique ID of a deadline (id) and the time and date of a deadline (deadline_date). The escalated attribute determines whether the reassignment have been performed (the value can be either 1 or 0). If a task is reassigned after it has not started until the set deadline, the Deadlines_StartDeadLine_Id attribute will be nonempty. If a task is reassigned after it has not been completed until the set deadline, Deadlines_EndDeadLine_Id attribute will be nonempty.

The Reassignment table refers to the Escalation table: the Escalation_Reassignments_Id attribute in Reassignments is equivalent to the id attribute in Escalation.

Notifications

If a task has not started or has not been completed before the deadline, a notification is sent to a subscribed user or a group of users (recipients). These notification are stored in the Notification table: id is the unique ID of a notification, DTYPE is the type of a notification (currently only an email notifications are supported), priority is set to 0 by default, and Escalation_Notifications_Id refers to the Escalation table, which then refers to the Deadline table. For example, if a task has not been completed before the deadline, then the Deadlines_EndDeadLine_Id attribute is nonempty and a notification is sent.

Recipients of a notification are stored in the Notification_Recipients table, where task_id is the unique ID of a task and entity_id is the ID of a subscribed user or a group.

The Notification_email_header stores the ID of a notification in the Notification_id attribute and the ID of an email that is sent in the emailHeader_id attribute. The email_header table contains the unique ID of an email (id), content of an email (body), the name of a user who is sending an email (fromAddress), the language of an email (language), the email address to which it is possible to reply (replyToAddress), and the subject of an email (subject).

Attachments

You can attach an attachment with an arbitrary type and content to each task. These attachments are stored in the Attachment table.

The Content table stores the actual binary content of an attachment. The content type is defined in the Attachment table. The maximum size of an attachment is 2 GB.

Delegations

Each task defines whether it can be escalated to another user or a group in the allowedToDelegate attribute of the Task table. The Delegation_delegates table stores the tasks that can be escalated (in the task_id attribute) and the users to which the tasks are escalated (entity_id).

It is often necessary to establish a connection and transfer data from existing systems and services, such as LDAP, to get data on actors and groups for User Tasks. To do so, implement the UserGroupInfoProducer interface. This enables you to create your own implementation for user and group management, and then configure it using CDI for Business Central.

To implement and activate the interface:

A dedicated UserGroupCallback implementation for LDAP servers is provided with the product to enable the User Task service to retrieve information about users, groups, and roles directly from an LDAP service. See LDAP Callback Connection Example for example configuration.

The LDAP UserGroupCallback implementation takes the following properties:

You can use the NotificationListener interface to configure a custom implementation of the Email Notification Events in the Task Escalation service. A custom notification implementation provides greater flexibility for your existing task escalation configurations.

To configure a custom implementation of Email Notification Events, follow these steps:

After you restart your server, the Task Escalation Service triggers your custom Email Notification Event. This feature is based on notification broadcasting, which enables all the notification handlers to handle the event. You can specify the following identifying information in any calls that your application makes to the desired handlers:

QueryResultMapper maps data to an object. It is similar to other object-relational mapping (ORM) providers, such as hibernate, which maps tables to entities. Red Hat JBoss BPM Suite provides a number of mappers for various object types:

Alternatively, you can build custom mappers. The name for each mapper serves as a reference that you can use instead of the class name. It is useful, for example, when you want to reduce the number of dependencies and you do not want to rely on implementation on the client side. To reference QueryResultMapper, use the mapper’s name, which is a part of jbpm-services-api. It acts as a (lazy) delegate as it will search for the mapper when the query is performed.

Following example references ProcessInstanceQueryMapper by name:

queryService.query("my query def", new NamedQueryMapper<Collection<ProcessInstanceDesc>>("ProcessInstances"), new QueryContext());

When you use the QueryService query method which accepts QueryParam instances, all of the parameters are joined by logical conjunction (AND) by default. Alternatively, use QueryParamBuilder to create custom builder which provides filters when the query is issued.

You can use a predefined builder, which includes a number of QueryParam methods based on core functions. Core functions are SQL-based conditions and include following conditions:

QueryParamBuilder is an interface that is invoked when its build method returns a non-null value before the query is performed. It allows you to build complex filter options that a QueryParam list cannot express.

import java.util.Map;

import org.dashbuilder.dataset.filter.ColumnFilter;
import org.dashbuilder.dataset.filter.FilterFactory;
import org.jbpm.services.api.query.QueryParamBuilder;

public class TestQueryParamBuilder implements QueryParamBuilder<ColumnFilter> {

  private Map<String, Object> parameters;
  private boolean built = false;

  public TestQueryParamBuilder(Map<String, Object> parameters) {
    this.parameters = parameters;
  }

  @Override
  public ColumnFilter build() {

    // Return NULL if it was already invoked:
    if (built) {
      return null;
    }

    String columnName = "processInstanceId";

    ColumnFilter filter = FilterFactory.OR(
      FilterFactory.greaterOrEqualsTo((Long)parameters.get("min")),
      FilterFactory.lowerOrEqualsTo((Long)parameters.get("max")));

    filter.setColumnId(columnName);

    built = true;

    return filter;
  }
}

For a list of Maven dependencies, see Embedded jBPM Engine Dependencies.

When you implement QueryParamBuilder, use its instance through QueryService:

import org.jbpm.services.api.query.QueryService;

...

queryService.query("my query def", ProcessInstanceQueryMapper.get(), new QueryContext(), paramBuilder);

QueryService is a part of the jBPM Services API, a cross-framework API built to simplify embedding Red Hat JBoss BPM Suite. You can also use advanced querying through the Intelligent Process Server, described in Section 12.9.5, “Advanced Queries Through Intelligent Process Server”. When you use QueryService in embedded mode, follow these steps:

You can now use the query definition. The following example does not use filtering:

import java.util.Collection;

import org.jbpm.services.api.model.ProcessInstanceDesc;
import org.kie.api.runtime.query.QueryContext;
import org.jbpm.services.api.query.QueryService;
import org.jbpm.kie.services.impl.query.mapper.ProcessInstanceQueryMapper;

...

Collection<ProcessInstanceDesc> instances = queryService.query("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext());

You can change the query context, that is paging and sorting of the query:

import java.util.Collection;

import org.kie.api.runtime.query.QueryContext;
import org.jbpm.services.api.model.ProcessInstanceDesc;
import org.jbpm.services.api.query.QueryService;
import org.jbpm.kie.services.impl.query.mapper.ProcessInstanceQueryMapper;

...

QueryContext ctx = new QueryContext(0, 100, "start_date", true);

Collection<ProcessInstanceDesc> instances = queryService.query
  ("getAllProcessInstances", ProcessInstanceQueryMapper.get(), ctx);

You can also use filtering:

import java.util.Collection;

import org.jbpm.kie.services.impl.model.ProcessInstanceDesc;
import org.jbpm.services.api.query.QueryService;
import org.jbpm.kie.services.impl.query.mapper.ProcessInstanceQueryMapper;
import org.kie.api.runtime.query.QueryContext;
import org.jbpm.services.api.query.model.QueryParam;

...

// Single filter parameter:
Collection<ProcessInstanceDesc> instances = queryService.query
  ("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext(),
  QueryParam.likeTo(COLUMN_PROCESSID, true, "org.jbpm%"));

// Multiple filter parameters (AND):
Collection<ProcessInstanceDesc> instances = queryService.query
  ("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext(),

QueryParam.likeTo(COLUMN_PROCESSID, true, "org.jbpm%"),
QueryParam.in(COLUMN_STATUS, 1, 3));

For a list of Maven dependencies, see Embedded jBPM Engine Dependencies.

To use advanced queries, you need to deploy the Intelligent Process Server. See chapter The Intelligent Process Server from Red Hat JBoss BPM Suite User Guide to learn more about the Intelligent Process Server. Also, for a list of endpoints you can use, view chapter Advanced Queries for the Intelligent Process Server from the Red Hat JBoss BPM Suite User Guide.

Through the Intelligent Process Server, users can:

To use advanced queries through the Intelligent Process Server, you need to build your Intelligent Process Server to use query services. For Maven projects, see Embedded jBPM Engine Dependencies. To build your Intelligent Process Server:

import java.util.Date;
import java.util.HashSet;
import java.util.Set;

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.client.KieServicesClient;
import org.kie.server.client.KieServicesConfiguration;
import org.kie.server.client.KieServicesFactory;
import org.kie.server.client.QueryServicesClient;

...

KieServicesConfiguration configuration = KieServicesFactory
  .newRestConfiguration(serverUrl, user, password);

Set<Class<?>> extraClasses = new HashSet<Class<?>>();
extraClasses.add(Date.class); // for JSON only to properly map dates

configuration.setMarshallingFormat(MarshallingFormat.JSON);
configuration.addJaxbClasses(extraClasses);

KieServicesClient kieServicesClient =  KieServicesFactory
  .newKieServicesClient(configuration);

QueryServicesClient queryClient = kieServicesClient
  .getServicesClient(QueryServicesClient.class);

// Maven dependency list shown above

You can now list available queries on your system:

List<QueryDefinition> queryDefs = queryClient.getQueries(0, 10);
System.out.println(queryDefs);

To use advanced queries, register a new query definition:

import org.jbpm.services.api.query.model.QueryDefinition;

...

QueryDefinition query = new QueryDefinition();
query.setName("getAllTaskInstancesWithCustomVariables");
query.setSource("java:jboss/datasources/ExampleDS");

query.setExpression("select ti.*,c.country,c.productCode,c.quantity,c.price,c.saleDate " +
  "from AuditTaskImpl ti " +
  "inner join (select mv.map_var_id, mv.taskid from MappedVariable mv) mv " +
  "on (mv.taskid = ti.taskId) " +
  "inner join ProductSale c " +
  "on (c.id = mv.map_var_id)");

query.setTarget("Task");

queryClient.registerQuery(query);

// Maven dependency list shown above

Note that Target instructs QueryService to apply default filters. Alternatively, you can set filter parameters manually. Target has the following values:

public enum Target {
    PROCESS,
    TASK,
    BA_TASK,
    PO_TASK,
    JOBS,
    CUSTOM;
}

Once registered, you can start with queries:

import java.util.List;

import org.kie.server.api.model.instance.TaskInstance;

//necessary for the queryClient object
import org.kie.server.client.QueryServicesClient;

List<TaskInstance> tasks = queryClient.query
  ("getAllTaskInstancesWithCustomVariables", "UserTasks", 0, 10, TaskInstance.class);

System.out.println(tasks);

// Maven dependency list shown above

This query returns task instances from the defined dataset, and does not use filtering or UserTasks mapper.

Following example uses advanced querying:

import java.text.SimpleDateFormat;
import java.util.Arrays;
import java.util.Date;
import java.util.List;

import org.kie.server.api.model.definition.QueryFilterSpec;
import org.kie.server.api.model.instance.TaskInstance;
import org.kie.server.api.util.QueryFilterSpecBuilder;

//necessary for the queryClient object
import org.kie.server.client.QueryServicesClient;
...

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");

Date from = sdf.parse("2016-02-01");
Date to = sdf.parse("2016-03-01");

QueryFilterSpec spec = new QueryFilterSpecBuilder()
  .between("processInstanceId", 1000, 2000)
  .greaterThan("price", 800)
  .between("saleDate", from, to)
  .in("productCode", Arrays.asList("EAP", "WILDFLY"))
  .oderBy("saleDate, country", false)
  .addColumnMapping("COUNTRY", "string")
  .addColumnMapping("PRODUCTCODE", "string")
  .addColumnMapping("QUANTITY", "integer")
  .addColumnMapping("PRICE", "double")
  .addColumnMapping("SALEDATE", "date")
  .get();

List<TaskInstance> tasks = queryClient.query
  ("getAllTaskInstancesWithCustomVariables", "UserTasksWithCustomVariables",
  spec, 0, 10, TaskInstance.class);

System.out.println(tasks);

// Maven dependency list shown above

It searches for tasks which have following attributes:

The query example uses QueryFilterSpec to specify query parameters and sorting options. It also allows to specify column mapping for custom elements to be set as variables, and combine it with default column mapping for task details. In the example, the UserTasksWithCustomVariables mapper was used.

When you use QueryFilterSpec, all the conditions are connected by logical conjunction (AND). You can build custom advanced filters with different behavior by implementing QueryParamBuilder. You need to include it in one of the following:

To use QueryParamBuilder, you need to:

You can now request your query builder:

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.kie.server.api.model.instance.TaskInstance;

...

Map<String, Object> params = new HashMap<String, Object>();
params.put("min", 10);
params.put("max", 20);

List<TaskInstance> instances = queryClient.query
  ("getAllTaskInstancesWithCustomVariables", "UserTasksWithCustomVariables", "test",
  params, 0, 10, TaskInstance.class);

// Maven dependencies shown above

Similarly, to create a custom mapper, follow these steps: