Overview

The BPM Component is a pluggable container in SwitchYard which allows a business process to be exposed as a service. One fronts their business process with a custom interface and, if desired, can easily annotate it's methods to define which should start a process, signal a process event, or abort a process.

Creating a BPM Service

To create a new BPM service in SwitchYard, you'll need the following information:

• File Name : the file name that will be used to create a new, empty BPMN 2 Process definition.

• Interface Type : the contract for the service being provided.  BPM supports Java, WSDL, and ESB contract types.

• Service Name : the name of the service your process will provide.

After clicking Finish, you will have a new service component definition for your process service and an empty BPMN process definition.  The next phase in developing your BPM service is to author the BPMN 2 process definition (details outside the scope of this documentation) and then configure the BPM service component to interact with that process definition.

Process Interaction

Interaction with a process is defined via actions on a BPM service component.  Take the following service contract as an example:

package org.switchyard.userguide;
public interface MyService {
    public void start(String data);
    public void signal(String data);
    public void stop(String data);
}

Actions allow you to map an operation in the service contract to one of the following interactions with a business process:

• START_PROCESS

• SIGNAL_EVENT

• ABORT_PROCESS_INSTANCE

<soap:Header>
    <bpm:processInstanceId xmlns:bpm="urn:switchyard-component-bpm:bpm:1.0">1</bpm:processInstanceId>
</soap:Header>

Process Variables

Consuming a Service

There are two ways of consuming Services with the SwitchYard BPM component:

1. 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.  This could be a SOAP Binding or a Camel Binding, for example. (Please refer to those sections of this guide for more information.)

2. 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 new widget for the Eclipse BPMN2 Modeler visual editor palette. Here is a screenshot from the "Help Desk" demo quickstart:

On the bottom right hand side under "Custom Task", you can see the SwitchYard Service widget. On the left hand side, you can see the various points of the business process where SwitchYard Services are being invoked. Once you have dropped a SwitchYard Service task in the main window, you can customize it via the Eclipse Properties Editor.

You can read a more detailed explanation of the Help Desk quickstart demo, as well as how to set up Eclipse to make use of new widget, on this wiki page.

SwitchYard Service Fault Handling

During your process execution, the SwitchYardServiceWorkItemHandler class is used to handle Switchyard Service tasks.  It executes service references, per the properties specified in the panel above.  Pay particular attention to the list of Fault-Handling Properties.  These properties define the behavior of the SwitchYardServiceWorkItemHandler in the case were a fault is encountered when executing the service reference.  There are 2 scenarios that the fault-handling covers:

1. "In my process flow, after the SwitchYard Service task, I would like a split gateway where I can inspect a process variable (a "flag") that can tell me that a fault occurred, so that I can diverge one way or another." 

   • To do this, specify the FaultResultName property.  The SwitchYardServiceWorkItemHandler will make the fault itself available as an output parameter of the task, so that it can be associated with a process variable, and inspected for existence in your split gateway.  You must also set the FaultWorkItemAction property to complete, so that the process will continue on to your split gateway!

   • An example bpmn2 process can be found in our JUnit test suite here: BPMWorkTests-FaultResultProcess.bpmn

2. "In my process flow, I have multiple places where faults could occur, and I want to have one shared path of fault-handling." 

   • To do this, specify the FaultSignalId property.  This must match a signal id you specify in your bpmn2 process definition.  You can then add an event node in your process that is triggered with this signal id; the flow from that event node on is your fault-handling path. The SwitchYardServiceWorkItemHandler will then signal the proper event with the configured id.

   • An example bpmn2 process can be found in our JUnit test suite here: BPMWorkTests-FaultEventrocess.bpmn

Whether you choose scenario 1 or 2 above, the question remains "What next?"  If you don't specify a FaultWorkItemAction property, nothing is done.  The work item is not completed, nor is it aborted.  You can set the property to complete to complete the work item after a fault, or you can set the property to abort to abort the work item after a fault.

Resources

A Resource represents an artifact that is required by your BPM process. It could be anything you could think of, including a properties file, a Drools Rule Language file, or whatever.  But it needs to be available to the BPM component's runtime for that process.  The list of resources available to your process is a configurable aspect of the BPM service component.

WorkItemHandlers

A WorkItemHandler is a way for you to add your own code into the business process.  Simply implement the org.kie.runtime.process.WorkItemHandler interface and add a handler definition to your BPM service component.

By default, the SwitchYardServiceWorkItemHandler is always added for you by the SwitchYard Maven plugin.  That handler allows you to easily call out to other SwitchYard services by name within your business process. Please see the section "Consuming a BPM Service" below for more information.

Auditing a Process

Please see the Listeners and Loggers sections found in the Knowledge Services documentation.