WSO2 Business Process Server v3.1.0 Documentation

##### Overview

- Home
- Release Note
- WS-BPEL Compliance
- License

##### Downloads

- Releases

##### Installation Guide

- Installing WSO2 BPS

##### Quick Start Guide

- Modeling the process
- Deploying the process
- Testing the process

##### User Guide

- Deploying BPEL Processes
- Deploying Human Tasks
- Managing BPEL processes
- Managing BPEL process instances
- QoS for BPEL processes
- Securing BPEL processes
- Invoking secured partner services
- Versioning
- Management API

##### Human Task Guide

- Human Tasks Quick Start Guide
- Deploying HumanTasks
- Managing Tasks
- Developing a Human Task Artifact
- Human Task Management and Configuration
- Human Task Concepts

##### Administrator Guide

- External data sources Configuration
- Registry Configuration
- Events
- Unified Endpoints
- BPEL Extensions
- Transaction Factory Configuration
- Message Exchange Interceptors
- OpenJPA specific properties
- JMS Transport Configuration
- Process Instance Cleanup Tasks
- Process Hydration and Dehydration
- Enabling Peer-to-Peer(P2P) Communication
- Setting up a BPS Cluster

##### Best Practices

- Process Deployment Best Practices

##### Concepts

- Process Versioning
- Process instance events
- Partner links

##### WS-BPEL Extensions

- Activity Failure and Recovery
- Extension Activities and Extensible Assign Operations
- XPath Extensions
- Iterable ForEach
- Flexible Assigns
- BPEL4People Extension

##### Samples

- HelloWorld
- If-Else
- ForEach
- While
- Repeat Until
- Flow and Links
- Pick
- Synchronous and Asynchronous Service Invocations
- Fault Handling
- Split
- XslTransform
- Compensation Handler
- Event Handler

##### Resources

- FAQ
- External Articles
- Library
- Source Code

##### Community

- Forum
- Mailing Lists

##### Project Information

- Issue Tracking

# Concepts

### Table of Content

- Process Versioning
- Process Instance Events
- Partner links

## Process Versioning

### Versioning

If a package with existing package name is uploaded, all the processes in the package will be versioned. In this case, all the old processes in the package will be retired while a new version will be be deployed. Since there is only package level versioning, the new package should include all the processes defined in the old package, eventhough you may only need to update a single process in that package.

## Process Instance Events

### Events

- Event Types
- Filtering Events
  - Filtering at the process level
  - Filtering at the scope level
- Event Listeners

WSO2 Business Process Server generates events to let you track what is exactly happening in the engine and produces detailed information about process executions. These events are persisted in BPS's database and can be queried using the Management API. The default behaviour for the engine is to always generate all events for every executed action. However from a performance standpoint it is better to deactivate some of the events you're not interested in (or even all of them). Inserting all these events generates a non-negligible overhead.

### Event Types

The following table details each event possibly generated by ODE:

Event Name | Process/Scope | Description | Type
--- | --- | --- | ---
ActivityEnabledEvent | Scope | An activity is enabled (just before it's started) | activityLifecycle
ActivityDisabledEvent | Scope | An activity is disabled (due to dead path elimination) | activityLifecycle
ActivityExecStartEvent | Scope | An activity starts its execution | activityLifecycle
ActivityExecEndEvent | Scope | An activity execution terminates | activityLifecycle
ActivityFailureEvent | Scope | An activity failed | activityLifecycle
CompensationHandlerRegistered | Scope | A compensation handler gets registered on a scope | scopeHandling
CorrelationMatchEvent | Process | A matching correlation has been found upon reception of a message | correlation
CorrelationNoMatchEvent | Process | No matching correlation has been found upon reception of a message | correlation
CorrelationSetWriteEvent | Scope | A correlation set value has been initialized | dataHandling
NewProcessInstanceEvent | Process | A new process instance is created | instanceLifecycle
PartnerLinkModificationEvent | Scope | A partner link has been modified (a new value has been assigned to it) | dataHandling
ProcessCompletionEvent | Process | A process instance completes | instanceLifecycle
ProcessInstanceStartedEvent | Process | A process instance starts | instanceLifecycle
ProcessInstanceStateChangeEvent | Process | The state of a process instance has changed | instanceLifecycle
ProcessMessageExchangeEvent | Process | A process instance has received a message | instanceLifecycle
ProcessTerminationEvent | Process | A process instance terminates | instanceLifecycle
ScopeCompletionEvent | Scope | A scope completes | scopeHandling
ScopeFaultEvent | Scope | A fault has been produced in a scope | scopeHandling
ScopeStartEvent | Scope | A scope started | scopeHandling
VariableModificationEvent | Scope | The value of a variable has been modified | dataHandling
VariableReadEvent | Scope | The value of a variable has been read | dataHandling

The second column specifies whether an event is associated with the process itself or with one of its scopes. The event type is used for filtering events.

### Filtering Events

#### Filtering at the process level

Using the deployment descriptor, it is possible to tweak events generation to filtrate which ones get created. First, events can be filtered at the process level using one of the following stanza:

    <dd:process-events generate="all"/> <!-- Default configuration -->

    <dd:process-events generate="none"/>

    <dd:process-events>
        <dd:enable-event>dataHandling</dd:enable-event>
        <dd:enable-event>activityLifecycle</dd:enable-event>
    </dd:process-events>

The first form just duplicates the default behaviour, when nothing is specified in the deployment descriptor, all events are generated. The third form lets you define which type of event is generated, possible types are:

- instanceLifecycle
- activityLifecycle
- dataHandling
- scopeHandling
- correlation

#### Filtering at the scope level

It is also possible to define filtering for each scope of your process. This overrides the settings defined on the process. In order to define event filtering on a scope, the scope activity MUST have a name in your process definition. Scopes are referenced by name in the deployment descriptor:

    <dd:deploy xmlns:dd="http://www.apache.org/ode/schemas/dd/2007/03">
        ...
        <dd:process-events generate="none">
            <dd:scope-events name="aScope">
                <dd:enable-event>dataHandling</bpel:enable-event>
                <dd:enable-event>scopeHandling</bpel:enable-event>
            </dd:scope-events>
            <dd:scope-events name="anotherScope">
                <dd:enable-event>activityLifecycle</bpel:enable-event>
            </dd:scope-events>
        </dd:process-events>
        ...
    </dd:deploy>

Note : Note that it is useless to enable an event associated with the process itself when filtering events on scopes. The filter defined on a scope is automatically inherited by its inner scopes. So if no filter is defined on a scope, it will use the settings of its closest parent scope having event filters (up to the process). Note that what gets inherited is the full list of selected events, not each event definition individually.

### Event Listeners

WSO2 Business Process Server lets you register your own event listeners to analyse all produced events and do whatever you want to do with them. To create a listener, you just need to implement the org.apache.ode.bpel.iapi.BpelEventListener interface.

Then add your implementation in the server's classpath (BPS_HOME/repository/components/lib) and add a property in bps.xml giving your fully qualified implementation class name:

    <tns:WSO2BPS xmlns:tns="http://wso2.org/bps/config">
      ...
        <tns:EventListeners>
            <tns:listener class="org.wso2.bps.samples.eventlistener.CustomEventListener"/>
        </tns:EventListeners>
      ...
    </tns:WSO2BPS>

You can try the sample event listener that is shipped with WSO2 Business Process Server by adding above configuration to the bps.xml and restart the server. You can find the source of the sample implementation of event listener here.

## Partner links

Partner-links are the abstraction for end-point references used in a the BPEL process. So a partner-link definition should be able to represent all the information required to interact with a external partner. Also the interaction can be two sided as follows.

- The process invokes a partner
- A partner invokes the process

So a partner-link may hold information on WSDL port-type that the business process offers to and the WSDL port-type that the partner suppose to offer. These information are characterized by a partner-link-type and role name at each partner-link. There can be two roles may be defined for a partner-link known as "myRole" and "partnerRole". "myRole" specifies the portType provided by the BPEL process to the partner. "partnerRole" specifies the interface provided by the partner. Partner-links can be defined in global level or scope level at a BPEL process.

eg -

    <partnerLink
       xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
       name="helloPartnerLink" partnerLinkType="ns:HelloPartnerLinkType"
       myRole="me" />

The relevant partnerLinkType should be declared in the partner WSDL or the BPEL process it-self such that it declares the set of roles and the port-types defined by each of the roles.

eg -

    <plnk:partnerLinkType name="HelloPartnerLinkType"
       xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype">
       <plnk:role name="me" portType="ns:processPortType"/>
       <plnk:role name="you" portType="ns:partnerPortType"/>
    </plnk:partnerLinkType>