Adding BPMN Processes

This wiki entry walks through the steps to add a new BPMN2 process to the BPE server.

Implementation

Maven Module

To implement a new process, create a maven module following the naming schema dsf-bpe-process-<name>. You can use the maven module dsf-bpe-process-hello-world as a starting point.

The only dependency needed is:

<dependency>
  <groupId>org.highmed.dsf</groupId>
  <artifactId>dsf-bpe-process-base</artifactId>
</dependency>

Create a source code package org.highmed.dsf.bpe in the main ▸ java folder and the following subpackages:

• spring.config
• service
• message (only needed if your process sends messages to other processes)
• variable (only needed if your process needs additional constants and process variables)

Additionally, you have to create the following packages in the main ▸ resources folder:

• bpe
• fhir
  • ActivitDefinition
  • StructureDefinition
• META-INF.services

Spring Configuration

• Create a spring configuration class according to HelloWorldConfig in the java-package spring.config.

BPMN Process

• Create your BPMN process and add it to the resources-package bpe. An example can be found in helloWorld.bpmn.
• Don't forget to set the process-id and the version.

Processes can only be initiated by using a Message Start Event. The message has to be a FHIR task resource and is pushed from the FHIR endpoint to the BPE using a websocket connection.

• Create a FHIR Task profile and add it to the resources-package fhir ▸ StructureDefinition. An example profile can be found in highmed-task-hello-world.xml.

• Your profile has to be derived from the profile highmed-task-base-0.4.0.xml, which is located in the package dsf-fhir ▸ dsf-fhir-validation ▸ resources ▸ fhir ▸ StructureDefinition of the highmed-dsf framework.

• The value instantiatesUri needs to be of the form http://highmed.org/bpe/Process/<process-id>/<version> and correspond to the values defined before in the BPMN process.

• Define a message-name in the profile and add it to the BPMN process Message Start Event.

• Create a FHIR ActivityDefinition profile and add it to the fhir ▸ ActivityDefinition resources-package. An example profile can be found in helloWorld.xml. This profile determines the organizational types that can start the process and whether the process can be started internally and/or externally.

Plugin

• Add a ProcessPluginDefinition to the root java-package org.highmed.dsf.bpe. An Example can be found in the HelloWorldProcessPluginDefinition.
• Add a Java ServiceLoader definition file to the resources-package META-INF.services:
  • The filname has to be org.highmed.dsf.ProcessPluginDefinition.
  • The content of the file has to be the class name incl. the package org.highmed.dsf.bpe.
  • An example is provided in the META-INF.services resources-package.

Services

• To execute a service task, copy/paste the class HelloWorld to the java-package service and adapt it to your needs.
• Each service class has to inherit from AbstractServiceDelegate.
• Add the new service class as bean to the spring configuration class created before.
• Add the new service class to the BPMN process file:
  • Change the BPMN task-type to Service Task.
  • In the implementation dropdown menu select Java Class.
  • Add the full name of the class incl. the package org.highmed.dsf.bpe.service to the new field Java Class.

The framework sets before starting a process the following process variables (to be retrieved and modified):

• VARIABLE_TASK: holds the task which started this process.
• VARIABLE_LEADING_TASK: if the currently running process is a subprocess, this variable holds the task which started the parent process.

The framework takes care of setting the state of the initiating FHIR Task resource as IN_PROGRESS or COMPLETED. An exception thrown in a service class will be catched by the framework in the AbstractServiceDelegate class and an error output containing the exception message will be added to the process initiating FHIR Task. Additionally, the FHIR Task state will be set to FAILED and the process instance will be stopped.

Messages

• Messages between organizations are sent as FHIR Task resources. Follow the steps above to create and add a new FHIR Task profile for the new message.

A message send example can be found as part of the process dsf-bpe-process-ping in the class SendPing.

• Java classes that send messages have to be placed in the java-package message.
• Each message send class has to inherit from AbstractTaskMessageSend.
• Add the message send class as bean to the spring configuration class created before.
• Add the new message class to the BPMN process file:
  • Change the BPMN task-type to Send Task.
  • In the implementation dropdown menu select Java Class.
  • Add the full name of the class incl. the org.highmed.dsf.bpe.message to the new field Java Class.
  • In the Input/Output tab add the input paramters (accordingly to the values defined in the FHIR Task recourse:
    • processDefinitionKey: Text
    • versionTag: Text
    • messageName: Text
    • profile: Text
• AbstractTaskMessageSend expects a process variable holding the recipient of the message --> the variable has to be stored with the name defined in the Constant VARIABLE_TARGET and to be of type Target. If you have multiple recipients use the Constant VARIABLE_TARGETS and adapt the BPMMN process the following way. An example can be found in SelectPingTargets.
  • Change the bpmn task to be Parallel Multi Instance.
  • In the field Collection add the value ${targets.entries}.
  • In the field Element Variable add the value target.

If you have additional FHIR Task input parameters, they can be added to a message by overriding the method getAdditionalInputParameters. An example can be found in the class SendRequest of the process dsf-bpe-process-update-resources.

Constants & Variables

Constants and additional variables should be stored in the java-package variable. An example can be found in the class org.highmed.dsf.bpe.ConstantsBase and the package org.highmed.dsf.fhir.variables of the process dsf-bpe-process-base.

If you have constant values in your new process, create an interface called Constants<ProcessName> and add them to this interface.

If there are objects that need to be passed from one BPMN task to another using execution variables, they need to be serializable. One way to realize this is using the Serializable interface provided by Java. But we prefer to use JSON serialization:

• Follow the example of the classes Target/Targets, TargetValues/TargetsValues, TargetSerializer/TargetsSerializer.
• Add the new serializers as bean to a new spring configuration class similar to the one created before for the process.
• All serializers are loaded by to the process engine using bean discovery on startup of the BPE server.
• Creating an instance of the variable class, for storage as execution variable, is then done using the values classes, e.g. TargetsValues.create(new Targets(<list-of-targets>))).

Testing

Maven Module

Additional dependencies are required for testing purposes. You can find them in the pom.xml of the hello-world process.

Create a test source code package org.highmed.dsf in the test ▸ java folder and the following subpackages:

• bpe.start
• fhir.profile

Starter Class

• Create in the package bpe.start a class to start the process (following HelloWorld3MedicTtpExampleStarter):
  • A starter class can be created using the static method ExampleStarter.forServer(args, baseUrl). args[0] should be the path to the client-certificate, args[1] the password of the client-certificate.
  • The element task.instantiatesUri should follow the naming schema http://highmed.org/bpe/Process/<process-id>/<process-version> and match the value defined previously in the FHIR Task profile.
  • The element task.input.valueString of the input with code message-name should match the message name of the BPMN start event and the value defined previously in the FHIR Task profile.

Tests

• Create in the package fhir.profile a class to test each (start-)message FHIR Task profile defined previously. As starting point you can use the class TaskProfileTest in the hello-world process.

Deployment

A new process can be deployed the following way:

• Build the maven module by running mvn clean install.
• Add the resulting jar to the BPE configuration folder app ▸ process.

For more information see the Wiki section Deployment.