Adding BPMN Processes

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

Maven Submodule

To add a new process you have to add a new maven submodule to the folder dsf-bpe following the naming schema dsf-bpe-process-<name>. You can use the existing module dsf-bpe-process-ping as an example.

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 and the following subpackages:

• spring.config
• plugin
• service
• message (only needed if your processes send messages)

Spring Configuration

• Create a spring configuration class according to PingConfig in the package spring.config.

BPMN2 Processes & FHIR Task Resources

• Create your BPMN2 process. An example can be found in resources > ping.bpmn.
• 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 profile which is derived from the profile dsf-fhir > dsf-fhir-server > resources > fhir > StructureDefinition > highmed-task-base-0.1.0.xml and add it to the StructureDefinition folder. An example can be found in highmed-task-start-process-0.1.0.xml. Additionally, create put file to add the new profile to the initially loaded bundle of the FHIR endpoint. An example can be found in highmed-task-start-process-0.1.0.xml.put.
• Create in the test resources folder an example FHIR task resource to start the process (following start-process-task.example.json):
  • The element task.instantiatesUri should follow the naming schema http://highmed.org/bpe/Process/<process-id>/<process-version>.
  • The element task.input.valueString of the input with code message-name should match the message name of the BPMN2 start event.

Plugin

• Add the BPMN2 processes you want to execute to the main resources folder of your maven submodule.
• Copy/paste the PingPlugin to the plugin package and adapt it according to the new BPMN2 files in the resources folder.
• Add the plugin as bean to the spring configuration class created before.

Services

• To execute a service task, copy/paste the class LogPing to the package service and adapt accordingly.
• Each service task class has to inherit from AbstractServiceDelegate.
• Add the service class as bean to the spring configuration class created before.
• 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.
  • VARIABLE_PROCESS_OUTPUTS: holds the outputs that are written to the output elements of process initiating task (only if the process finishes successfully).
• The framework takes care of setting the state of the initiating FHIR task resource as IN_PROGRESS and COMPLETED.
• An exception thrown in a service task class will be catched by the framework in the AbstractServiceDelegate and an error output containing the exception message will be added to the task. The task state will be set to FAILED.

Messages

• Sending messages is again only possible as a FHIR task resource (follow the steps above to create a FHIR profile and and example task resource).
• To execute a message send event, copy/paste the class SendPing from the package message and adapt accordingly.
• Each message send class has to inherit from AbstractTaskMessageSend.
• Sending messages expects a process variable holding all the recipients of the message --> the variable has to be stored with the name VARIABLE_MULTI_INSTANCE_TARGET and to be of type MultiInstanceTarget. An example can be found in SelectPingTargets.
• Additional input parameters can be added by overriding the method getAdditionalInputParameters. An example can be found in the dsf-bpe-process-update-resources submodule in the class SendRequest.
• Add the message send class as bean to the spring configuration class created before.