8.2. BPM
8.2.1. BPM Component
SwitchYard implements the Business Process Management (BPM) functionality through the BPM Component. The BPM Component is a pluggable container in SwitchYard that allows you to expose a business process as a service. Using the BPM component, you can start a process, signal a process event, or abort a process.
Important
A JBoss Fuse subscription includes an entitlement to use embedded BPM as a SwitchYard component only. All other uses (for example, with Apache Camel) require a separate BPM subscription.
8.2.2. Create a BPM Service
Prerequisites
- File Name: The file name of the new BPMN 2 Process definition.
- Interface Type: The contract for the service provided by your bean. BPM supports Java and WSDL contract types.
- Service Name: The name of the service provided by your bean.
Procedure 8.6. Task
- Create a new BPMN file in the SwitchYard Editor JBoss Developer Studio plug-in.
- Input the values into the SwitchYard Editor's New SwitchYard BPMN File Screen.
Figure 8.2. New SwitchYard BPMN File Screen
- Click Finish.This creates a new service component definition for your process service and an empty BPMN process definition.
- After creating a new BPM Service, create the BPMN 2 process definition and configure the BPM service component to interact with that process definition.
8.2.3. Process Interaction
You define interaction with a process by the actions you add to a BPM service component. Study this sample code which is for a service contract:
package org.switchyard.userguide;
public interface MyService {
public void start(String data);
public void signal(String data);
public void stop(String data);
}
By using actions, you can map an operation in the service contract to one of the following interactions with a business process:
- START_PROCESS
- Operations configured with the START_PROCESS action type start new process instances.When you start your process (actually, any interaction with a service whose implementation is bpm), the processInstanceId is put into the SwitchYard context at Scope.EXCHANGE and is fed back to your client in a binding-specific way. For SOAP, it is in the form of a SOAP header in the SOAP response envelope:
<soap:Header> <bpm:processInstanceId xmlns:bpm="urn:switchyard-component-bpm:bpm:1.0">1</bpm:processInstanceId> </soap:Header>In future process interactions, you need to send back that same processInstanceId, so that the correlation is done properly. For SOAP, that means including the same SOAP header that was returned in the response to be sent back with subsequent requests.ImportantIf you are using persistence, the sessionId is also available in the Context, and must be fed back as well. It looks the same as the processInstanceId in the SOAP header. - SIGNAL_EVENT
- Operations configured with the SIGNAL_EVENT action type have to signal the associated process instance. The processInstanceId must be available in the Context so the correct process instance is correlated.There are two other pieces of information that are needed when signaling an event:
- The "id". In BPMN2 lexicon, this is known as the "signal id", but in jBPM can also be known as the "event type". This is set as the id of the annotation.NoteIn BPMN2, a signal looks like this:
<signal id="foo" value="bar"/>
In jBPM, it is the signal id that is respected, not the name. This might require you to tweak a tooling-generated id if you want to customize its name. - The "event object". This is the data representing the event itself. There are two ways to pass in the event object:
- The first way is through a Context object. The way in which this is passed is similar to the processInstanceId, and it is known as "signalEvent". If you use this, you are limited to a String type.
- The second way is through the Message content object itself (that is, your payload). If the signalEvent Context property is absent, the content of the Message is used as the event object.
- ABORT_PROCESS_INSTANCE
- If an operation is configured with the ABORT_PROCESS_INSTANCE action type, associated process instances are aborted. Note that the processInstanceId must be available in the Context so the correct process instance is correlated.
8.2.4. Use Process Variables
Prerequisites
- JBoss Developer Studio jBPM Plug-In
Procedure 8.7. Use Process Variables
- Click on the white space around a process or on any of your process nodes.
- Access the Properties view.
- Declare the variablenames at the process level and in the Parameter Mapping (and possibly Result Mapping).
8.2.5. Mappings
Mappings are the way to move data in or out of the action for that operation. You can specify as many mappings as you like for an action, and they get grouped as globals, inputs or outputs:
Mapping variables from your SwitchYard Exchange, Context or Message into jBPM process variables can be done with expressions. Each action for a process service has a distinct set of variable mappings.
- Global mappings are used to provide data that is applicable to the entire action, and is often used in classic in/out param (or data-holder/provider) fashion. An example of a global mapping is a global variable specified within a Drools Rule Language (DRL) file.
- Input mappings are used to provide data that represents parameters being fed into an action. An example of an input mapping for BPM is a process variable used while starting a business process. For Rules, it could be a fact to insert into a rules engine session.
- Output mappings are used to return data from an action. An example of an output mapping is a BPM process variable that you want to set as the outgoing (response) message’s content.
Note
The onlyexpressionType supported currently is MVEL, so you do not have to specify it. The expression itself can be any MVEL expression
8.2.6. expressionType Properties
These variables are available by default:
- exchange
- The current org.switchyard.Exchange.
- context
- The current org.switchyard.Context.
- message
- The current org.switchyard.Message.
Whatever the resultant value of the expression is constitutes the data that is made available to the action.
expression="message.content"
This is the same as
message.getContent().
expression="context[‘foo’]" scope="IN"
This is the same as
context.getProperty("foo", Scope.IN).getValue() in a null-safe manner.
Note
Specifying the scope attribute only matters if you use the context variable inside your expression. If you don’t specify a scope, the default Context access (which is done like a Map, if you picked up on that), is done with Scope.EXCHANGE for global mappings, Scope.IN for input mappings, and Scope.OUT for output mappings.
Specifying the variable attribute is often optional, but this depends on the usage. For example, if you are specifying a global variable for a rule, or a process variable to put into (or get out of) a BPM process, then it is required. However, if the result of the expression is to be used as facts for rule session insertion, then specifying a variable name is not applicable.
Here is some XML sample code:
<mapping expression="theExpression" expressionType="MVEL" scope="IN" variable="theVariable"/>
8.2.7. Consuming a Service
There are two ways of consuming Services with the SwitchYard BPM component:
- By invoking the BPM implementation through a gateway binding. Since the BPM component exposes a Java interface fronting the business process, you can use any of the bindings provided by SwitchYard. (You could, for example, use either a SOAP Binding or a Camel Binding.)
- By invoking other SwitchYard Services from inside a BPM process itself. To do this, you can use the SwitchYardServiceWorkItemHandler, which is provided out-of-the-box. (To make authoring BPMN2 processes easier, SwitchYard provides a widget for the Eclipse BPMN2 Modeler visual editor palette.)
8.2.8. SwitchYard Service Task Properties
You can use the following properties to configure the SwitchYard Service task.
Service Naming Properties:
- ServiceName
- This is the name of the SwitchYard service to invoke. It is a mandatory property
- ServiceOperationName
- This is the name of the operation within the SwitchYard service to invoke. It is an optional property. (The default behavior is to use the single method name in the service interface, if there is just one.)
Content I/O Properties:
- ContentInputName
- This is the process variable into which the message content is placed. It is an optional property. The default value is contentInput.
- ContentOutputName
- The process variable from which the message content is obtained. It is an optional property. The default value is contentOutput.
Fault-Handling Properties:
- FaultResultName
- This is the name of the output parameter (in other words, the result variable) under which the exception is stored. It is optional.
- FaultSignalId
- This is the bpmn signal id (or event type) that is used to signal an event in the same process instance. The event object is the exception. This is an optional property.
- FaultWorkItemAction
- This property determines what happens after a fault occurs. If it is set to null, nothing is done. If set to complete, the current work item (that is, the SwitchYard service task) is completed. If it is set to abort, the current work item is aborted. (The default setting is null.) This property is optional.
8.2.9. SwitchYard Service Fault Handling
The
SwitchYardServiceWorkItemHandler class is used for fault handling in the Switchyard Service tasks during process execution. It executes service references according to the SwitchYard's fault-handling properties that you have configured. The SwitchYard's fault-handling properties define the behavior of the SwitchYardServiceWorkItemHandler class when a fault is encountered during the execution of the service reference.
You can use the
SwitchYardServiceWorkItemHandler class for fault handling in the following scenarios:
- If you want to have a split gateway in your process flow, to inspect a process variable for any occurrence of a fault. To achieve this, you need to set the following fault-handling properties in your SwitchYard Service task:
- FaultResultName: Specifying the FaultResultName property enables the
SwitchYardServiceWorkItemHandlerclass to make the fault available as an output parameter of the task. You can then associate it with a process variable, and inspect for existence in your split gateway. - FaultWorkItemAction: Specifying the FaultWorkItemAction property to complete enables the process to continue on to your split gateway.
- If you want to have a single shared path of fault-handling in your process flow. To achieve this, you need to set the following fault-handling properties in your SwitchYard Service task:
- FaultSignalId: Specifying the FaultSignalId property same as the Signal ID you specified in your bpmn2 process definition, enables you to add an event node in your process that is triggered with this signal id. The flow starting from this event node is your fault handling path. The
SwitchYardServiceWorkItemHandlerclass then signals the proper event with the configured ID.
8.2.10. Using The Standard BPMN2 Service Task
You can invoke SwitchYard Services using the standard BPMN2 Service Task. You can use the Service Task icon from the BPMN2 Editor palette and configure its properties. To configure the Service Task, keep in mind the following points:
- The
<serviceTask>attribute invokes SwitchYard when it has animplementation="##SwitchYard"attribute. - The ServiceName is derived from the BPMN2 interfaceImplementationRef.
- The ServiceOperationName is derived from the BPMN2 operationImplementationRef.
- The ContentInputName is always called Parameter.
- The ContentOutputName is always called Result.
8.2.11. Resources
A resource represents an artifact that your BPM process uses at runtime. A resource can be a properties file or a Drools Rule Language file. You can configure the list of resources available to your process in the BPM service component.
8.2.12. WorkItemHandler Interface
A work item handler is responsible for executing work items of a specific type. They represent the glue code between an abstract, high-level work item that is used inside the process and the implementation of this work item. You can add your own code into the business process using the WorkItemHandler. To do so, implement the
org.kie.runtime.process.WorkItemHandler interface and add a handler definition to your BPM service component.
