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, COMPLETED or 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.