Case management - jBPM v7 - Part 3 - dynamic activities

It's time for next article in "Case Management" series, this time let's look at dynamic activities that can be added to a case on runtime. Dynamic means process definition that is behind a case has no such node/activity defined and thus cannot be simply signaled as it was done for some of the activities in previous articles (Part 1 and Part 2).

So what can be added to a case as dynamic activity?

• user task
• service task - which is pretty much any type of service task that is implemented as work item 
• sub process - reusable

User and service tasks are quite simple and easy to understand, they are just added to case instance and immediately executed. Depending of the nature of the task, it might start and wait for completion (user task) or it might directly finish after execution (service tasks). Although most of the service tasks (as defined in BPMN2 spec - Service Task) will be invoked synchronously it might be configured to run in background or even wait for external signal to be completed - all depends on the implementation of the work item handler.
Sub process is slightly different in the expectations process engine will have - process definition that is going to be created as dynamic process must exists in kjar. That is to make sure process engine can find that process by its id to execute it. There are no restriction on what the subprocess will do, it can be synchronous without wait states or it can include user tasks or other subprocesses. Moreover such created subprocess will have correlation key set with first property being the case id of the case where the dynamic task was created. So from case management point of view it will belong to that case and thus see all case data (from case file - see more details about case file in Part 2).

Create dynamic user task

To create dynamic user task there are few things that must be given:

• task name
• task description (optional though recommended to be used)
• actors - list of comma separated actors to assign the task, can refer to case roles for dynamic resolving 
• groups - same as for action but referring to groups, again can use case roles
• input data - task inputs to be available to task actors

Dynamic user task can be created via following endpoint:

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/instances/IT-0000000001/tasks

where 

• itorders is container id
• IT-0000000001 is case id

Method::

POST

Body::

{

 "name" : "RequestManagerApproval",

 "data" : {

  "reason" : "Fixed hardware spec",

  "caseFile_hwSpec" : "#{caseFile_hwSpec}"

  }, 

 "description" : "Ask for manager approval again",

 "actors" : "manager",

 "groups" : "" 

}

this will then create new user task associated with case IT-000000001 and the task will be assigned to person who was assigned to case role named manager. This task will then have two input variables:

• reason
• caseFile_hwSpec - it's defined as expression to allow runtime capturing of process/case data

There might be a form defined to provide user friendly UI for the task which will be then looked up by task name - in this case it's RequestManagerApproval (and the form file name should be RequestManagerApproval-taskform.form in kjar).

Create dynamic service task

Service tasks are slightly less complex from the general point of view, though they might need more data to be provided to properly perform the execution. Service tasks require following things to be given:

• name - name of the activity
• nodeType - type of a node that will be then used to find the work item handler
• data - map of data to properly deal with execution

Service task can be created with the same endpoint as user task with difference in the body payload.

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/instances/IT-0000000001/tasks

where 

• itorders is container id
• IT-0000000001 is case id

Method::

POST

Body::

{

 "name" : "InvokeService",

 "data" : {

  "Parameter" : "Fixed hardware spec",

  "Interface" : "org.jbpm.demo.itorders.services.ITOrderService",

  "Operation" : "printMessage",

  "ParameterType" : "java.lang.String"

  }, 

 "nodeType" : "Service Task"

}

In this example, an java based service is executed. It consists of an interface that is a public class org.jbpm.demo.itorders.services.ITOrderService, public printMessage method with single argument of type String. Upon execution Parameter value is passed to the method for execution.

Number and names, types of data given to create service tasks completely depends on the implementation of service task's handler. In this example org.jbpm.process.workitem.bpmn2.ServiceTaskHandler was used.

NOTE: For any custom service tasks, make sure handler is registered in deployment descriptor in WorkItem Handler section where the name is same as nodeType used when creating a dynamic service task.

Create dynamic subprocess

Dynamic subprocess expects only optional data to be provided, there are no special parameters as for tasks so it's quite straight forward to be created. 

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/instances/IT-0000000001/processes/itorders-data.place-order

where 

• itorders is container id
• IT-0000000001 is case id
• itorders-data.place-order is the process id of the process to be created

Method::

POST

Body::

{

 "any-name" : "any-value"

}

Mapping of output data

Typically when dealing with regular tasks or subprocesses to map output data, users define data output associations to instruct the engine on what output of the source (task or sub process instance) to be mapped to what process instance variable. Since dynamic tasks do not have data output definition there is only one way to put output from task/subprocess to the process instance - by name. This means the name of the returned output of a task must match by name process variable to be mapped. Otherwise it will ignore that output, why is that? It's to safe guard case/process instance of putting unrelated variables and thus only expected information will be propagated back to case/process instance.

Look at this in action

As usual, there are screen casts to illustrate this in action. First comes the authoring part that shows:

• creation of additional form to visualize dynamic task for requesting manager approval
• simple java service to be invoked by dynamic service task
• declaration of service task handler in deployment descriptor

Next, it is shown how it actually works in runtime environment (kie server)




Complete project that can be imported and executed can be found in github.

So that concludes part 3 of case management in jBPM 7. Comments and ideas more than welcome. And that's still not all that is coming :)

Case management - jBPM v7 - Part 2 - working with case data

In Part 1, basic concepts around case management brought by jBPM 7 were introduced. It was a basic example (it order handling) as it was limited to just moving through case activities and basic data to satisfy milestone conditions.

In this article, case file will be described in more details and how it can be used from within a case and process. So let's start with quick recap of variables available in processes.

There are several levels where variables can be defined:

• process level - process variable
• subprocess level - subprocess variable
• task level - task variable

Obviously the process level is the entry point where all other take the variables from. Meaning if a process instance creates subprocess it will usually include mapping from process level to subprocess level. Similar for tasks, tasks will get variables from process level. 

In such case it means the variable is copied to ensure isolation for each level. That is, in most of the cases, the desired behavior unless you need to keep all variables always up to date, regardless of the level they are in. That, in turn, is usual situation in case management which expects always the most up to date variables at any time in the case instance, regardless of their level.

So that's why case management in jBPM is equipped with Case File, which is then only one for entire case, regardless how many process instances compose the case instance. Storing data in case file promotes reuse instead of copy, so each process instance can take variable directly from case file and same for updates. There is no need to copy variable around, simply refer to it from your process instance.

Support for case file data is provided at design time by marking given variable as case file

as can be seen in the above screenshot, there is variable hwSpec marked as case file variable. And the other (approved) is process variable. That means hwSpec will be available to all processes within a case, and moreover it will be accessible directly from a case file even without process instance involvement.

Next, case variables can be used in data input and output mapping

case file variables are prefixed with caseFile_ so the engine can properly handle it. Though a simplified version (without the prefix) is expected to work as well. Though for clarity and readability it's recommended to always use the prefix.

Extended order hardware example

In part 1, there was a very basic, with no data case definition for handling order of IT hardware. In this article we extend the example to illustrate:

• use of case file variables
• use of documents
• share of the information between process instances via case file
• use business process (via call activity) to handle placing order activity

Following screencast shows entire design time activities to extend the part 1 example, including awesome feature to copy entire project!

So what was done here:

• create new business process - place-order that will be responsible for placing order activity instead of script task from previous example
• define case file variables:
• hwSpec - which is a physical document that needs to be uploaded
• ordered - which is indication for Milestone 1 to be achieved 
• replace script task for Place order activity with reusable subprocess - important to note is that there are no variables mapping in place, all is directly taken from case file
• generate forms to handle file upload and slightly adjust their look

With these few simple steps our case definition is enhanced with quite a bit of new features making it's applicability much better. It's quite common to include files/documents in a case, though they should be still available even if given process instance that uploaded them is gone. And that's provided by case file that is there as long as case instance was not destroyed.

Let's now run the example to see it in action

The execution is similar as it was in part one, meaning to start the case we need to use REST api. A worth noting part here is that we made a new version of the project:

•  org.jbpm.demo
• itorders
• 2.0

and then it was deployed on top of the first version, in exact same kie server. Even though there are both versions running the URL to start the case didn't change:

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/itorders.orderhardware/instances

where

• itorders is the container alias that was deployed to KIE Server
• itorders.orderhardware is case definition id

Method: POST

As described above, at the time when new case is started it should provide basic configuration - role assignments:

POST body::

{

  "case-data" : {  },

  "case-user-assignments" : {

    "owner" : "maciek",

    "manager" : "maciek"

  },

  "case-group-assignments" : {

    "supplier" : "IT"

 }

}

itorders is an alias that when used will always select the latest version of the project. Though if there is a need to explicitly pick given version then simply replace the alias with the container id (itorders_2.0 or itorders_1.0)

Once the process is started supplier (based on role assignment - IT group) will have task to complete to provide hardware specification - upload a document. Then manager can review the specification and approve (or not) the order. Then it goes to subprocess to actually handle the ordering, which once done will store status into case file which will then trigger milestone 1.

Throughout all these user oriented activities, case file information (hwSpec) is shared without any need to copy that around. Moreover, there was no need to configure anything to handle documents either, that is all done by creating a case project that by default sets up everything that is needed.

At any time (as long as case was not destroyed) you can get the case file to view the data. This can be retrieved by following endpoint

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/instances/IT-0000000001/caseFile 

where:

• itorders - is the container alias
• IT-0000000001 - is the case ID

Method: GET

With this, part 1 concludes with a note that since it is bit enhanced order hardware case, it's certainly not all that you can do with it so stay tuned for more :)

Try it yourself

As usual, complete source code is located in github.

Case management - jBPM v7 - Part 1

This article starts a new series of blog posts about case management feature that is coming in jBPM v7 to illustrate its capabilities with complete examples that will get more complex/advanced on each part.

One of the most frequently requested features in jBPM is so called Case Management. Case management can mean different things depending who you talked to so I'd like to start with small scope definition what does it mean in context of jBPM (at the moment as that might change based on feedback, supported features and use cases and further evolution).

Case management can be best described when compared to business processes. Business processes are usually modeled as flow charts with clearly defined paths to reach a business goal. These processes usually have one (might have more) starting points and are structurally connected to build end to end flow of work and data.

While cases are more dynamic, they provide room for improvements as the case evolve without the need to foresee all possible actions in advance. So case definition usually consists of loosely coupled process fragments that can be connected (directly on indirectly) to lead to certain milestones and finally business goal.

Looking at different notations that can be used for case management, processes and cases might be represented differently:

• BPMN2
• CMMN

jBPM comes with cases support based on BPMN2 as most users are familiar with this notation and most if not all features can be represented with BPMN2 constructs. That's at least a starting point which might be revisited further on. A good comparison between BPMN2 and CMMN was published by Bruce Silver.

These article series will introduce readers to case management support gradually with more features as we go to not provide too much details at once and let the features described be backed with examples that can be seen (screencast) and executed on the actual environment with jBPM v7.

Case project

First thing to start with, is to create Case project - it's a special type of project in KIE workbench that is on top of regular project to configure it for the case management:

• set runtime strategy to Per Case
• configure marshallers for case file and documents
• create WorkDefinition.wid files in the project and its packages to ensure case related nodes (e.g. Milestone) are available in palette 

Case definition

So let's start with basic case definition example that covers following use case - IT hardware orders. As in any company, there is a need from time to time to order new IT equipment - such as computers, phones, etc. This kind of system can be represented with a good case management as they usually deal with a bit of dynamic decisions that might influence the flow. 

Case definition is created in authoring perspective in KIE workbench - it expects name, location and optionally case ID prefix. What's that? Case ID prefix is configurable element that allows to easily distinguish different types of cases. Default mechanism is that the prefix is then followed with generated id in following format:

ID-XXXXXXXXXX

where X is generated number to produce unique id with the prefix. If prefix is not given it defaults to CASE and then each subsequent instance of that case definition will be:

CASE-0000000001

CASE-0000000002

CASE-0000000003

or when prefix is set to HR

HR-0000000001

HR-0000000002

HR-0000000003

Case definition is always an adhoc process definition meaning it is a dynamic process so does not require to have explicit start nodes.

Once the clean definition is created, it's time to define roles involved in the usual case of ordering new IT hardware:

• owner - is the person who requests the hardware (can be only one)
• manager - is direct manager of the owner to approve the requested hardware
• supplier - set of people that can order and deliver physical equipment (usually more than one)

When the roles are known, case management must ensure that these are not hardcoded to single set of people/groups as part of case definition and that it can differ per each case instance. This is where case role assignments come into the picture and can be:

• given when case starts
• set at any given point in time while case is active
• removed at any given point in time while case is active

second and third option does not alter the task assignments for already active tasks.

What is important to note here, is that in case management users should always use roles for task assignments instead of actual user/group names, that is to make the case as dynamic as possible so actual user/group assignment is done as late as possible. It's similar to process variables though without expression syntax (#{variable}).

Let's take a look at our case definition:

So what do we have here? First thing that is directly seen is - no start nodes of the process. Does that mean there is no way to tell what is going to be triggered when new instance of this case definition is created?

Quite the opposite - nodes that have no incoming connections and are marked as Adhoc Autostart (a property of a node) will be automatically triggered when instance is started.

In this case these are:

• Prepare hardware spec
• Milestone 1: Order placed

Both of these nodes are wait states, meaning they are triggered but they are not left, they wait for further action:

• Prepare hardware spec - wait for supplier to provide the spec and complete the task
• Milestone 1: Order placed - wait for condition to be met - there is a case file variable named "ordered" with value true

Hmmm, but what is a case file then? Case File is like a bucket for data for entire case instance. Since case can span across number of process instances, instead of coping data back and forth (that first of all might be expensive and second can lead to use of out of date information) process instance can write and read from case file that is accessible to all process instance that belong to the same case. CaseFile is stored in working memory and thus is persiteable same as ksession and process instance - meaning can use marshaling strategies to store in different places e.g. documents, JPA entities etc. Though what's more important - it is a fact in working memory and thus can be subject for rules.

Milestone actually uses case file as condition to trigger only if there is a ordered variable available in case file and its value is true. Only then milestone will be completed and will follow to next node.

Another worth noting part is the end signals that are at the end of Milestone 1 and Milestone 2 fragments. These signals are responsible for triggering next Milestone in line, but again, only triggering and not completing it as they will wait on condition. The scope of signal is process instance only so completing Milestone 1 in first case instance will not cause any side effects on other active case instances of the same definition.

Here is a complete design of this project and case definition as screencast.

Complete source code of this project (and the entire repository) can be found here. This repository can be cloned directly to workbench for build and deploy.

... speaking of build and deploy....

The project can be directly build and deploy in workbench and (assuming you have KIE Server connected to workbench) provisioned to execution environment where it can be started and worked on.

At the moment workbench does not provide any case management UI, thus we will use REST calls to start a case and put data into case file but we can use workbench for user task interaction and overall monitoring - process instance logs, process instance image, active nodes, etc.

Start new case

To start a new case use following endpoint:
Endpoint::
http://host:port/kie-server/services/rest/server/containers/itorders/cases/itorders.orderhardware/instances

where

• itorders is the container alias that was deployed to KIE Server
• itorders.orderhardware is case definition id

As described above, at the time when new case is started it should provide basic configuration - role assignments:

POST body::

{

  "case-data" : {  },

  "case-user-assignments" : {

    "owner" : "maciek",

    "manager" : "maciek"

  },

  "case-group-assignments" : {

    "supplier" : "IT"

 }

}

At the moment case-data is empty as we don't supply any data/information to the case. But we do configure our defined roles. Two of them are user assignments (as can be seen in the above screen cast they are referenced in Actor property of user tasks) and third is group assignments (as it is referenced in Groups property of user task).

Once successfully stared it will return case ID that should look like
IT-0000000001

Then this case can already be seen in process instance list in workbench, and its tasks should be available in task perspective. So the tasks can be completed and various milestones will be achieved until it reaches the Milestone that requires shipped variable to be present in case file.

Insert case file data

Case file data can be easily inserted into active case using REST api.

Endpoint::

http://host:port/kie-server/services/rest/server/containers/itorders/cases/instances/IT-0000000001/caseFile/shipped

where

• itorders is the container alias that was deployed to KIE Server
• IT-0000000001 is the unique id of a case instance
• shipped is the name of the case file variable to be set/replaced

POST body::

true

Same should be later repeated to insert "delivered" case file variable to achieve Milestone 3 and move to final task - Customer Satisfaction Survey. And that's all for this basic case example.

Execution in action can be found in this screencast

Comments and ideas more than welcome. And in addition, contribution to what cases should be provided as example are wanted!