Providing a Service

To provide a service with the BPM component, you will have to:

1. Define your process using BPMN2.

2. Create a java interface, fronting your BPMN2 process, which can be exposed to other services, and/or to your binding(s).

3. Add the component containing the implementation and service interface to the SwitchYard configuration. This step can be automated using annotations and the SwitchYard plugin, explained below.

Here is an example of the component section of the SwitchYard configuration:

<component name="MyService">
    <implementation.bpm xmlns="urn:switchyard-component-bpm:config:1.0" processId="MyService">
        <manifest>
            <resources>
                <resource location="META-INF/MyService.bpmn" type="BPMN2">
            </resources>
        </manifest>
        <workItemHandlers>
            <workItemHandler class="org.switchyard.component.bpm.work.SwitchYardServiceWorkItemHandler" name="SwitchYard Service"/>
        </workItemHandlers>
    </implementation.bpm>
    <service name="MyService">
        <interface.java interface="org.switchyard.userguide.MyService"/>
    </service>
</component>

The MyService interface can be as simple as this, with no SwitchYard-specific imports:

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

However, if you want to have the SwitchYard configuration for this section auto-generated for you, you can use annotations and the SwitchYard Maven Plugin.  To do this, you can either add SwitchYard-specific annotations to your interface directly, or (and this is the recommended approach) you can create a separate interface for this purpose. Let's do that:

package org.switchyard.userguide;
import org.switchyard.component.bpm.annotation.BPM;
import org.switchyard.component.bpm.work.SwitchYardServiceWorkItemHandler;
import org.switchyard.component.common.knowledge.annotation.Manifest;
import org.switchayrd.component.common.knowledge.annotation.Resource;
@BPM(
    value=MyService.class,
    processId="MyService",
    manifest=@Manifest(resources={
        @Resource(location="META-INF/MyService.bpmn", type="BPMN2")
    }),
    workItemHandlers={@WorkItemHandler(value=SwitchYardServiceWorkItemHandler.class)}
)
public interface MyServiceProcess {}

At this point you might be wondering what the resources and workItemHandlers attributes of the annotations are.

First, a Resource represents an additional 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. You can either add the resource to the XML yourself, or use the annotation, similar to the examples above.

Next, 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 it to the SwitchYard configuration, either manually in XML, or by referencing your implementation via the workItemHandlers attribute of the BPM annotation, similarly to how we did with resources above.

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.

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

package org.switchyard.userguide;
import org.switchyard.component.bpm.annotation.AbortProcessInstance;
import org.switchyard.component.bpm.annotation.BPM;
import org.switchyard.component.bpm.annotation.SignalEvent;
import org.switchyard.component.bpm.annotation.StartProcess;
@BPM(MyService.class)
public interface MyServiceProcess extends MyService {
    @StartProcess @Override
    public void start(String data);
    @SignalEvent("myEvent") @Override
    public void signal(String data);
    @AbortProcessInstance @Override
    public void stop(String data);
}

<component name="MyService">
    <implementation.bpm xmlns="urn:switchyard-component-bpm:config:1.0" processId="MyService">
        <actions>
            <action operation="start" type="START_PROCESS"/>
            <action id="myEvent" operation="signal" type="SIGNAL_EVENT"/>
            <action operation="stop" type="ABORT_PROCESS_INSTANCE"/>
        </actions>
        <manifest>
            <resources>
                <resource location="META-INF/MyService.bpmn" type="BPMN2"/>
            </resources>
        </manifest>
        <workItemHandlers>
            <workItemHandler class="org.switchyard.component.bpm.work.SwitchYardServiceWorkItemHandler" name="SwitchYard Service"/>
        </workItemHandlers>
    </implementation.bpm>
    <service name="MyService">
        <interface.java interface="org.switchyard.userguide.MyService"/>
    </service>
</component>

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

<implementation.bpm ...>

    <actions>
        <action ...>
            <inputs>
                <mapping expression="exchange.serviceName.localPart" expressionType="MVEL" variable="service"/>
                <mapping expression="context['org.switchyard.messageId']" variable="messageId" contextScope="IN"/>
                <mapping expression="message.content" variable="contentIn"/>
            </inputs>
            <outputs>
                <mapping expression="message.content" variable="contentOut"/>
            </outputs>
        </action>
    </actions>
    ...
</implementation.bpm>

@StartProcess(...
    inputs={
        @Mapping(expression="exchange.serviceName.localPart", expressionType=ExpressionType.MVEL, variable="service"),
        @Mapping(expression="context['org.switchyard.messageId']", variable="messageId", contextScope=Scope.IN),
        @Mapping(expression="message.content", variable="contentIn")},
    outputs={
        @Mapping=(expression="message.content", variable="contentOut")
    })
public MyDataResponse process(MyData data);

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.