Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

Adding BPMN Processes

Jump to bottom
Reto Wettstein edited this page Jul 23, 2020 · 21 revisions

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

Implementierung

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 Task FHIR profile which is derived from the profile dsf-fhir > dsf-fhir-server > resources > fhir > StructureDefinition > highmed-task-base-0.2.0.xml and add it to the StructureDefinition folder. An example can be found in highmed-task-start-ping-process-0.2.0.xml. Additionally, create a post 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.2.0.xml.post. This profile defines the message and the input parameters that are required to start the process.
  • Create an ActivityDefinition FHIR profile and add it to the folder dsf-fhir > dsf-fhir-server > resources > fhir > ActivityDefinition folder. An example can be found in ping-0.2.0.xml. Additionally, create a post file to add the new profile to the initially loaded bundle of the FHIR endpoint. An example can be found in ping-0.2.0.xml.post. This profile determines the organizational type that can start the process and whether the process can be started internally and/or externally.
  • Create in the test src folder an example class to start the process (following Ping3MedicFromTtpExampleStarter.java):
    • 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 the process initiating this 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 for this service task. Additionally, the task state will be set to FAILED and the process instance will be stopped.

Variables

If there are objects that need to be passed from one service 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:

  • Create another subpackage called variables.
  • Follow the example of the classes Output/Outputs, OutputValues/OutputsValues, OutputSerializer/OutputsSerializer.
  • Add the new serializers as bean to the spring configuration class created before.
  • Add the new serializers as constructor parameters to the above create plugin class and override the method preInit(ProcessEngineConfigurationImpl processEngineConfiguration) and add all new serializers to the engine by calling processEngineConfiguration.setCustomPreVariableSerializers(<list-of-serializers>).
  • Creating an instance of the variable class for storage as execution variable is then done using the values classes, e.g. OutputsValues.create(new Outputs(<list-of-outputs>))).

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.

Deployment

New process plugins can be deployed in two different ways:

  • A process can be added directly to the framework as maven dependency in dsf-bpe > pom.xml and dsf-bpe > dsf-bpe-server > pom.xml and will be packaged as part of the framework in every build as well as in DSF releases. This type of deployment is intended for processes that are important for all sites. One example is again the module dsf-bpe-process-ping.
  • The other possibility is through the plugin interface, by dropping the build jar of the process into the folder dsf-bpe > dsf-bpe-server-jetty > plugin or the designated docker plugin folders. The plugin jars will be added to the classpath and loaded on startup of the BPE server. This type of deployment is intended for processes that are only used locally at one location and therefore are not part of DSF releases.
Clone this wiki locally