This version must be installed on Petals ESB 5.3.0+ Previous service units are no more compliant with this component version and must be migrated. See Migrating service units developed for previous versions Features The component SE Flowable includes a BPMN 2.0 engine and provides two operational mode: integration mode, that exposes a service-based API of a BPMN 2.0 engine (Flowable), service mode to implement your services using orchestrations and workflows, the service tasks invoke natively, through the NMR, the services available into Petals ESB Integration mode The mode "Integration" of the SE Flowable permits to interact directly with the BPMN 2.0 engine (Flowable) through a service-based API. Several services are provided by the component to interact directly with the BPMN 2.0 engine. This mode is activated at the component level. Concurrency Several instance of the component can be deployed concurrently on Petals ESB. A sequence of service-based API invocations can be exploded on each component instances Service mode The mode "Service" of the SE Flowable permits to implement your services using orchestration and/or process capabilities of BPMN 2.0. This mode is available through the deployment of a service unit including the process definition. Orchestration An orchestration is sequence of automatic service invocations, and can be modeled as a sequence of service tasks in a BPMN2 description. Creating an instance of such a process will start automatically the sequence of service invocations. With BPMN2 it is possible to implement your orchestration as a process containing only service tasks. For example, the following orchestration can be an implementation of a service processing a "New Order": Process A process or workflow can be "servicized" at different levels: when creating a new instance of the process definition, when completing a task of the process instance when searching process instances or tasks For example, the previous sample can be reworked replacing two service tasks by human tasks with such a process: Then created services are: the service "New Order" associated to a process instance creation, the service "Order Prepared" associated to the completion of the task "prepareOrder", the service "Order Delivered" associated to the completion of the task "deliverOrder". Concurrency Several instance of the component can be deployed concurrently on Petals ESB. So, you are able to deploy each process definitions on several component instances to get high availability.

Table of contents 1 Features 1.1 Integration mode 1.2 Service mode 2 Introduction 3 System requirements 4 Using the mode "service" 4.1 About deployment/undeployment and versioning 4.1.1 Deployment 4.1.2 Undeployment 4.1.3 Versioning 4.2 Creating a service-unit for a process definition 4.2.1 Creating the service contract 4.2.1.1 Identifying operations 4.2.1.2 Identifying input parameters of operations 4.2.1.3 Identifying output parameters of operations 4.2.1.4 Identifying faults of operations 4.2.1.5 Associating an operation to the creation of an process instance 4.2.1.6 Associating an operation to the completion of a process instance task 4.2.1.7 Associating an operation to the intermediate message catch event 4.2.1.8 Associating an operation to retrieve process instances 4.2.2 Creating the service unit 4.2.2.1 CDK parameters defining service provider implementation 4.2.2.2 CDK parameters driving interceptors 4.2.2.3 Dedicated configuration 4.2.2.4 Service Unit Content 5 Invoking Petals service providers from Flowable process 5.1 Importing the service contract of the Petals service provider 5.2 Defining the Petals service provider address 5.3 Creating the associated service task 5.4 Configuring the service consumer 5.4.1.1 CDK parameters defining service consumer implementation 5.4.1.2 CDK parameters driving interceptors 6 Using the mode "integration" 6.1 The service "UserService" 6.1.1 The operation "get" 6.1.2 The operation "search" 6.2 The service "GroupService" 6.2.1 The operation "search" 6.3 The service "ProcessInstancesService" 6.3.1 The operation "getProcessInstances" 6.3.2 The operation "suspendProcessInstances" 6.3.3 The operation "activateProcessInstances" 6.4 The service "ExecutionsService" 6.4.1 The operation "getExecutions" 6.5 The service "TaskService" 6.5.1 The operation "getTasks" 7 IDM engine integration 7.1 File-based IDM engine 7.1.1 Configuration 7.1.2 File formats 7.2 LDAP-based IDM engine 7.2.1 Configuration 7.3 Petals services based IDM engine 7.4 Write your own IDM engine 8 Flowable's extensions 8.1 Custom JUEL functions 8.1.1 date:parse 8.1.2 petals:getPlaceholder 8.1.3 petals:getPlaceholderWithDefault 9 Configuring the component 9.1 CDK parameters 9.2 Interception configuration 9.3 Component specific parameters 9.3.1 Enabling/disabling the Flowable job executor 9.4 Using placeholders to configure the process definition 10 Business monitoring 10.1 Flow tracing activation 10.2 Flow tracing propagation 11 Logging 12 Monitoring the component 12.1 Using metrics 12.1.1 Common metrics 12.1.2 Dedicated metrics 12.2 Receiving alerts 12.2.1 Common alerts 12.2.2 Dedicated alerts 13 Unit testing 13.1 Checking the compliance of the WSDL 13.2 Unit-testing your XSLs 13.3 Unit-testing your process definition 14 Migration guide 14.1 Migrating service units developed for previous versions 14.1.1 From 1.3.2 to 1.4.x Contributors No contributors found for: authors on selected page(s)

Introduction

This version of the component is based on:

• Flowable v6.7.2 as embedded BPMN engine. Flowable extensions can be used at the runtime level,
• Eclipse Jetty v9.4.44.v20210927 as HTTP server for Flowable REST API.

System requirements

The Petals SE Flowable MUST be deployed on a container running with a Java Development Kit (JDK), not a Java Runtime Environment !!

Using the mode "service"

About deployment/undeployment and versioning

Deployment

A service unit embeds process definition(s). So when deploying a service unit:

• its process definition(s) are automatically deployed,
• and the associated services providers are registered.

When you redeploy a service unit, the embedded process definition(s) will not be redeployed because the process definition is already deployed for the given version of the process definition. In this way, we can push some changes outside process definition as service consumer parameters (timeout, ...). If some changes are needed into process definition(s), it is needed to increment the associated BPMN version.

When a Petals ESB node restarts, all service units previously deployed are redeployed. As process definition versions are the same no redeployment of process definitions occurs.

With a Petals ESB topology based on at least two nodes, you can deploy the Petals SE Flowable on several nodes to have high availability on your service providers associated to your process definitions. As service tasks are executed by any SE Flowable through the Flowable job async executor, you must deployed all your service units on all your Petals SE Flowable having the Flowable job async executor enabled.

Undeployment

A process definition can be undeployed only when no more process instance is in progress and when no more historic process instance exists. That's why process definition are not undeployed when undeploying a service unit. You can undeploy a process instance using the administrative JMX operation 'undeployProcessDefinition' after to have purged associated process instances.

Several administrative JMX operations can help you:

Versioning

Process definition must be deployed as long as an associated process instance is in progress, and/or process instance histories exist. So, once a Flowable service unit has been deployed you must think to its potential changes to be able:

• to continue to execute process instances in progress,
• to continue to access process instance histories,
• to deploy minor changes: minor changes of process definition and/or minor changes of the JBI part. A change is considered as minor when the service provider interfaces are not changed,
• to deploy major changes: major changes of the service providers and process definition. A change is considered as major when a service provider interface is changed.

To apply minor changes, you will replace the deployed service unit. So you will undeploy the service unit before to deploy the new version.

To apply major changes, as the service provider interfaces change, you will need to deploy concurrently the new version. So you need only to deploy the new version.

When deploying a process definition, Flowable requires a 'process definition resource home' from which some resources can be resolved relatively to the BPMN file of the process definition, for example WSDLs of the service providers invoked through service tasks. This 'process definition resource home' is set as an URI containing the service unit name and the BPMN file name.
So when deploying a new minor version of a service unit, the new service unit MUST have the same service name than the previous one to be able to continue to execute process instances created with the previous version.
For a new major version, you can set a new service unit name because no process instance is already in progress.

Usually, the service unit name is set by the Maven Petals plugin building the service assembly. By default, the service unit name is defined as '<artifact-id>-<version>'. With this template, the service unit name will change for any version. So you MUST configure the template to have a different value for each major version. For example, you can use the following template '<artifact-id>-<version.major>.<version.minor>' for a version naming convention defined as '<major>.<minor>.<increment>'.

Creating a service-unit for a process definition

Creating the service contract

The SE Flowable provides a service with several operation for a process definition. A WSDL is associated to this service. This WSDL can be written freely. The user can use its own namespace, its own names, ... It is only constraint by the following rules:

• the operations of the binding section are annotated to link them to the supported operations of the process definition (create an instance of the process definition, complete the current task of the process instance, ...)
• the parameters of the operation are annotated to retrieve the right values to transmit to the BPMN engine,
• the output and fault of the operations are annotated to build the service output from the result of the operation on the BPMN engine side.

For a unit test purpose, an extension of JUnit is available to validate your WSDL not only in a our WSDL point of view, but also in a SE Flowable point of view. See chapter "Unit testing".

Identifying operations

The mapping between operations of the WSDL and operations supported by the BPMN 2.0 engine embedded in the SE Flowable is declared using a dedicated binding. The binding "Flowable" is done adding the element {http://petals.ow2.org/se/flowable/annotations/1.0}operation to the element operation of the binding. Its attribute action defines the operation that will be executed on the process engine according to the following values:

The action is completed with the another attribute as following:

Identifying input parameters of operations

In the same way, input parameters of operations are mapped through annotations placed inside of the binding operation. Two natures of input parameters exists:

• the expected input parameters
• and, variables.

Each BPMN 2.0 engine API operation can require mandatory or optional input parameter, the expected input parameters, and can accept to set several variables in the same time.

Expected input parameters are declared using dedicated annotation according to the operation:

Variables are identified by the annotation adding the element {http://petals.ow2.org/se/flowable/annotations/1.0}variable:

• its attribute name defines the variable name used in the process definition.
• its content defines the value to set to the variable using an XPath expression.

Supported variable types are the one supported by Flowable variable: string, long, double, enum, date, boolean and json. No extra check is done by the SE Flowable about the compliance of the variable value with the process definition.
For variable type "json", the XML node resulting of the XPath expression is automatically converted into JSON. The following extra attrbiutes can be used to drive the definition of a JSON variable:

• json-pre-xsl: Name of the XSL to execute on the XPath result before converting into JSON,
• json-pre-xsl-result-json: true if the result of the XSL transformation on the XPath result is in JSON format; false if the result is in XML format and must be converted into JSON,
• json-virtual-root: XML element use for wrapping the JSON root element.

<flowable:variable name="numberOfDays">
   /*[local-name()='demande']/*[local-name()='nbJourDde']
</flowable:variable>

See operation details to know if variables can be set.
No extra check is done by the SE Flowable about the compliance of the variable with the process definition.

TODO. Les types ?; les arborescences

Identifying output parameters of operations

Output parameters of the BPMN 2.0 engine API operation can not be mapped to the output reply of the service operation using a simple XPath expression as for input parameters. An XSL style-sheet is required to generated the full output reply. It is identified using the annotation adding the element {http://petals.ow2.org/se/flowable/annotations/1.0}output that contains the XSL style-sheet name. The XSL style-sheet is read from the classloader or through a file relative to the root directory of the service unit. The XSL style-sheets are mainly located in the service-units, they can also be packaged as a shared library.

According to the operation executed by the BPMN 2.0 engine, its output parameters are transmitted to the XSL style-sheet through XSL parameters. You will use these XSL parameters to generate your service reply from your service request payload. See operation details to know the available XSL parameters.

For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "Unit testing".

Identifying faults of operations

When an error occurs on the BPMN engine side, this error can be returned as business fault or technical error. The business faults are declared into the WSDL of the service.

The mapping of an error of the BPMN engine to a business fault is defined using the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}fault set as child element of the WSDL fault. The attribute name will contain a key word identifying the error on the BPMN engine. And the content value is the name of the XSLT style-sheet to use to generate the business fault.

The XSL style-sheet is read from the classloader or through a file relative to the root directory of the service unit. The XSL style-sheets are mainly located in the service-units, they can also be packaged as a shared library.

An error of the BPMN engine that can be mapped to a business fault has also parameters that will be transmitted to the XSL to generate the right business fault content.

See operation details to known the errors thrown, and their parameters, that can be mapped to a business fault.

For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "Unit testing".

Associating an operation to the creation of an process instance

The operation creating instances of process definition is identified by the value startEvent set on the attribute action of the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}operation. As your service unit can include several process definition, you need to clarify the process definition to use to create the process instance using the attribute processDefinitionId. As a process definition can include several start events, the right start event to use to create the new process instance is clarified with attributes:

• none-start-event-id for none start event,
• or start-event-message-name for message start event.

This operation accepts variables and requires the following input parameters:

• user identifier, declared using the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}userId containing an XPath expression that is applied on incoming XML payload to get the value of the user identifier to use on the BPMN engine side.

The XSL parameters available to generate the service output reply are:

On this operation, no error thrown by the BPMN engine can be mapped to business fault.

It is possible to map several operations of the WSDL to the creation of process instances, but this has perhaps no sens.

<wsdl:binding name="Order" xmlns:flowable="http://petals.ow2.org/se/bpmn/annotations/1.0">
   <wsdl:operation name="newOrder" type="...">
      <flowable:operation processDefinitionId="order" action="startEvent" start-event-message-name="newOrder"/>
      <flowable:userId>/*[local-name()='newOrderRequest']/*[local-name()='userName']</flowable:userId>
      <flowable:variable name="address">
            /*[local-name()='newOrderRequest']/*[local-name()='address']
      </flowable:variable>
      <flowable:output>newOrderOutput.xsl</flowable:output>
      <wsdl:input/>
      <wsdl:output/>
   </wsdl:operation>
</wsdl:binding>

<newOrderRequest>
   <userName>Jean Zé</userName>
   <customerName>Mr Dupont Martin</customerName>
   <address>23, rue de la Paie, 75000 Paris</address>
</newOrderRequest>

<newOrderResponse>
   <orderNumber>12345</orderNumber>
</newOrderResponse>

Associating an operation to the completion of a process instance task

The operation completing a task of a process instance is identified by the value userTask set on the attribute action of the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}operation. To guarantee that the expected user task is the right one, its identifier is clarified with the attribute user-task-id.

This operation accepts variables and requires the following input parameters:

• process instance identifier, declared using the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}processId containing an XPath expression that is applied on incoming XML payload to get the value of the process instance identifier to use on the BPMN engine side.
• user identifier, declared using the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}userId containing an XPath expression that is applied on incoming XML payload to get the value of the user identifier to use on the BPMN engine side.

Note: The completion status of the task is a variable and so it takes any form.

The XSL parameters available to generate the service output reply are:

The following errors thrown by the BPMN engine can be mapped to business fault:

A such operation is defined for each task of the process definition to complete. C'est le cas d'un service par tache à terminer. Essayer de mieux expliquer..

<wsdl:binding name="Order" xmlns:flowable="http://petals.ow2.org/se/flowable/annotations/1.0" >
   <wsdl:operation name="validOrder">
      <flowable:operation processDefinitionId="order" action="userTask" user-task-id="validOrder"/>
      <flowable:processId>/*[local-name()='validOrderRequest']/*[local-name()='orderId']</flowable:processId>
      <flowable:userId>/*[local-name()='validOrderRequest']/*[local-name()='userName']</flowable:userId>
      <flowable:variable name="validationApproved">
            /*[local-name()='validOrderRequest']/*[local-name()='isValidated']
      </flowable:variable>
      <flowable:variable name="creditCardNumber">
            /*[local-name()='validOrderRequest']/*[local-name()='creditCardNumber']
      </flowable:variable>
      <flowable:output>validOrderOutput.xsl</flowable:output>
      <wsdl:input/>
      <wsdl:output/>
      <wsdl:fault name="orderUnknown">
         <bpmn:fault name="ProcessInstanceNotFoundException">orderUnknown.xsl</bpmn:fault>
         <soap:fault name="orderUnknown" use="literal" />
      </wsdl:fault>
      <wsdl:fault name="orderAlreadyValidated">
         <bpmn:fault name="TaskCompletedException">orderAlreadyValidated.xsl</bpmn:fault>
         <soap:fault name="orderAlreadyValidated" use="literal" />
      </wsdl:fault>
   </wsdl:operation>
</wsdl:binding>

<validOrderRequest>
   <orderId>12345</orderId>
   <isValidated>true</isValidated>
   <creditCardNumber>1234567890123</customerName>
   <userName>Robert Té</userName>
</validOrderRequest>

<validOrderResponse />

Associating an operation to the intermediate message catch event

The operation receiving an intermediate message event identified by the value intermediateMessageCatch set on the attribute action of the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}operation. To guarantee that the expected intermediate message catch event is the right one, the message name is clarified with the attribute message-event-name.

Caution: The value of {{message-event-name is the message name that should be received in the BPMN definition, not the identifier of the intermediate message catch event. For the following BPMN definition the value will be 'messageName':

<definitions ...>
  <process id="intermediate-message-catch-event-process" name="My process" isExecutable="true">
    ...
    <intermediateCatchEvent id="messageintermediatecatchevent1" name="MessageCatchEvent">
      <messageEventDefinition messageRef="messageRef"/>
    </intermediateCatchEvent>
    ...
  </process>
  <message id="messageRef" name="messageName"/>
</definitions>

This operation accepts variables and requires the following input parameters:

• process instance identifier, declared using the annotation {http://petals.ow2.org/se/flowable/annotations/1.0}processId containing an XPath expression that is applied on incoming XML payload to get the value of the process instance identifier to use on the BPMN engine side.

This operation is limited to the JBI MEPs: InOnly and RobustInOnly. So no output reply is returned, only fault and error according to the MEP.

The following errors thrown by the BPMN engine can be mapped to business fault:

A such operation can be defined for each intermediate message catch event of the process definition to complete. Don't forget to define the variable types in the WSDL.

<wsdl:binding name="Order" xmlns:flowable="http://petals.ow2.org/se/flowable/annotations/1.0" >
   <wsdl:operation name="paymentReceived">
      <flowable:operation processDefinitionId="order" action="intermediateMessageCatch" message-event-name="paymentReceived"/>
      <flowable:processId>/*[local-name()='paymentReceivedRequest']/*[local-name()='orderId']</flowable:processId>
      <flowable:variable name="checkNumber" type="string">
            /*[local-name()='paymentReceivedRequest']/*[local-name()='checkNumber']
      </flowable:variable>
      <wsdl:input/>
      <wsdl:fault name="orderUnknown">
         <bpmn:fault name="ProcessInstanceNotFoundException">orderUnknown.xsl</bpmn:fault>
         <soap:fault name="orderUnknown" use="literal" />
      </wsdl:fault>
   </wsdl:operation>
</wsdl:binding>

<paymentReceivedRequest>
   <orderId>12345</orderId>
   <checkNumber>1234567890123</checkNumber>
</paymentReceivedRequest>

Associating an operation to retrieve process instances

The operation retrieving process instances is identified by the value retrieveProcInst set on the attribute action:

<wsdl:binding name="Order" xmlns:flowable="http://petals.ow2.org/se/flowable/annotations/1.0">
   <wsdl:operation name="searchOrder" type="...">
      <flowable:operation action="retrieveProcInst" />
      <flowable:input-parameter name="isActive" value="/searchOrderRequest/isInProgress" />
      <flowable:input-parameter name="responsibleUser" value="/searchOrderRequest/responsibleUser" />
      <flowable:input-parameter name="responsibleGroup" value="/searchOrderRequest/responsibleGroup" />
      <flowable:output>searchOrderOutput.xsl</flowable:output>
      <wsdl:input/>
      <wsdl:output/>
   </wsdl:operation>
</wsdl:binding>

This operation requires the following input parameters:

It does not use variables.

The process instances returned by the component are all associated to the current process definition (the process definition packaged in the service unit).

The XSL parameters available to generate the service output reply are:

It is possible to map several operations of the WSDL to search process instance, for example with different search criteria.

Creating the service unit

All services provided by a business process are defined into the JBI descriptor of a service unit as a section 'provides':

<jbi:provides
         interface-name="process:vacation"
         service-name="process:vacationService"
         endpoint-name="autogenerate">
			
         <petalsCDK:wsdl>vacationService.wsdl</petalsCDK:wsdl>
			
         <petals-se-flowable:tenant_id>my-tenant</petals-se-flowable:tenant_id>
         <petals-se-flowable:category_id>samples</petals-se-flowable:category_id>
         <petals-se-flowable:process_file1>vacationRequest.bpmn20.xml</petals-se-flowable:process_file1>
         <petals-se-flowable:version1>1</petals-se-flowable:version1>

</jbi:provides>

Only one section 'provides' is accepted by the Petals SE Flowable.

If your business process includes service tasks to invoke service providers, you can add a section 'consumes' for each one to drive more precisely the invocation:

<jbi:provides ...>
         ...
         <petals-se-flowable:process_file1>vacationRequest.bpmn20.xml</petals-se-flowable:process_file1>
         <petals-se-flowable:version1>1</petals-se-flowable:version1>
</jbi:provides>

<jbi:consumes
           interface-name="archiveService:archive"
           service-name="archiveService:archiveService">
         <petalsCDK:timeout>15000</petalsCDK:timeout>
         <petalsCDK:mep>RobustInOnly</petalsCDK:mep>
         <petalsCDK:operation>archiveService:archiver</cdk:operation>
</jbi:consumes>

Supported parameters of the section 'consumes' are:

• timeout, to set on the message exchange used for the service provider invocation,
• mep, that define the message exchange pattern to use. If not set, the pattern used isthe one defined in the imported WSDL,
• operation, should be used if several operations of the same consumer are invoked by the process. You can add several section 'consumes' for the same consumer but for different operations.
• exchange-properties, the properties to set on the message exchange used to invoke the service provider,
• message-properties, the properties to set on the message of message exchange used to invoke the service provider.

If you want specify a specific endpoint to invoke a service provider, just define it in the section 'consume': <jbi:consumes interface-name="archiveService:archive" service-name="archiveService:archiveService" endpoint-name="mySpecificEndpointName"> <petalsCDK:timeout>15000</petalsCDK:timeout> </jbi:consumes>

All needed information is set in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:

• JBI parameters that defines the service provider identification,
• CDK parameters that are parameters driving the service provider implementation at CDK layer,
• CDK interceptor parameters that are parameters driving interceptors at CDK layer,
• Dedicated parameters that are parameters driving the service provider implementation at component layer.

CDK parameters defining service provider implementation

The following parameters correspond to the CDK configuration of the service provider implementation.

The service provider is defined into the section 'provides' of the JBI descriptor, containing:

CDK parameters driving interceptors

The following parameters drive interceptors at CDK layer.

Interceptors can be defined to inject some post or pre-processing in the service provider processing or service consumer processing.

Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5">
   <jbi:services>
      <jbi:provides|consumes>
         <!--...-->
         <petalsCDK:su-interceptors>
            <petalsCDK:send>
               <petalsCDK:interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
                  <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
               </petalsCDK:interceptor>
            </petalsCDK:send>
            <petalsCDK:accept>
               <petalsCDK:interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:interceptor>
            </petalsCDK:accept>
            <petalsCDK:send-response>
               <petalsCDK:Interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:Interceptor>
            </petalsCDK:send-response>
            <petalsCDK:accept-response>
               <petalsCDK:Interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:Interceptor>
            </petalsCDK:accept-response>
         </petalsCDK:su-interceptors>
         <!--...-->
      </jbi:provides|consumes>
      <!--...-->
   </jbi:services>
</jbi:jbi>

Dedicated configuration

Service Unit Content

The service unit has to contain the following elements, packaged in the archive:

• the META-INF/jbi.xml descriptor file as described above,
• the WSDL description for service provider embedded in the service-unit with BPMN annotations,
• the WSDL descriptions of service consumers,
• XSL stylesheets used to generate response and faults from Flowable API replies.

service-unit.zip
  + META-INF
    - jbi.xml (as defined above)
  - service-provider.wsdl
  - service-consumer.wsdl
  - request.xsl
  - response.xsl

Invoking Petals service providers from Flowable process

The Petals service providers can be invoked natively from Flowable process using a 'ServiceTask' into your process definition through three steps:

1. petalscomponents:import the service contract of the Petals service provider into your service-unit project,
2. petalscomponents:define the Petals service provider address,
3. petalscomponents:create the associated service task,
4. petalscomponents:configure the associated service consumer.

Importing the service contract of the Petals service provider

The service contract of the Petals service provider (ie. its WSDL file) must be added to the service unit project. We recommend you to import the WSDL file in the same directory than the process definition file (ie. src/main/resources/jbi.

Defining the Petals service provider address

The address of the Petals service provider (ie. interface name, service name and/or endpoint) must be defined into the service contract previously imported, as a basic service endpoint in XML tag '/wsdl:service/wsdl:port/soap:address/@location'. The address is defined with an URL matching the following pattern: petals:///interfacename[:servicename[petalscomponents::endpointname]].
Example:

<wsdl:definitions ...>
   ...
   <wsdl:service name="notifyVacationService">
      <wsdl:port name="autogenerate" binding="notifyService:notifyVacationBinding">
         <soap:address location="petals:///{http://petals.ow2.org/samples/se-flowable/notifyVacationService}notifyVacation" />
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

Creating the associated service task

Once a 'ServiceTask' has been added to your process, you will configure it as following to invoke the right Petals service provider:

1. First, import the Petals service provider contract into the Flowable process definition:

   <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
      <import location="CommunicationService.wsdl" namespace="http://org.ow2.petals.samples.rld.service.technical.communication/1.0/"
            importType="http://schemas.xmlsoap.org/wsdl/" />
      <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true">
         ...
      </process>
   </definitions>
   

2. Next, at your service task level, select the service task implementation '##WebService' and identify the reference of the service to call (ie. the operation of a web-service):

   <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
      ...
      <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true">
         ...
         <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager"
            implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp">
            ...
         </serviceTask>
         ...
      </process>
   </definitions>
   

3. The service to call is referenced through the definition of a BPMN interface:

   <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
      ...
      <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true">
         ...
         <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager"
            implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp">
            ...
         </serviceTask>
         <interface name="User base service" implementationRef="userbaseService:userBase">
            <operation id="getHumanResourceManagerOp" name="Get HR manager" implementationRef="userbaseService:humanResourceManager">
               <inMessageRef>rldProcess:getHumanResourceManagerRequestMessage</inMessageRef>
               <outMessageRef>rldProcess:getHumanResourceManagerResponseMessage</outMessageRef>
            </operation>
         </interface>
         <message id="getHumanResourceManagerRequestMessage" itemRef="rldProcess:getHumanResourceManagerRequestItem" />
         <message id="getHumanResourceManagerResponseMessage" itemRef="rldProcess:getHumanResourceManagerResponseItem" />
         <itemDefinition id="getHumanResourceManagerRequestItem" structureRef="userbaseService:humanResourceManager" />
         <itemDefinition id="getHumanResourceManagerResponseItem" structureRef="userbaseService:humanResourceManagerResponse" />
         ...
      </process>
   </definitions>
   

   where 'implementationRef' is the port name of the service, and 'structureRef' is the type of messages exchanged with the service. These both references are defined in the imported WSDL.

4. Next, define mapping of the service request and the service reply

   <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
      ...
      <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true">
         ...
         <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager"
            implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp">
            <ioSpecification>
               <dataInput itemSubjectRef="rldProcess:getHumanResourceManagerRequestItem" id="getHRManagerEmailTaskInput" />
               <dataOutput itemSubjectRef="rldProcess:getHumanResourceManagerResponseItem" id="getHRManagerEmailTaskOutput" />
               <inputSet>
                  <dataInputRefs>getHRManagerEmailTaskInput</dataInputRefs>
               </inputSet>
               <outputSet>
                  <dataOutputRefs>getHRManagerEmailTaskOutput</dataOutputRefs>
               </outputSet>
            </ioSpecification>
            <dataInputAssociation>
               <targetRef>getHRManagerEmailTaskInput</targetRef>
               <assignment>
                  <from>${employeeId}</from>
                  <to>${getHRManagerEmailTaskInput.userId}</to>
               </assignment>
            </dataInputAssociation>
            <dataOutputAssociation>
               <targetRef>hrManagerEmail</targetRef>
               <transformation>${getHRManagerEmailTaskOutput.email}</transformation>
            </dataOutputAssociation>
         </serviceTask>
         ...
      </process>
   </definitions>
   

Dash ('-') included in XML tag of service request/reply are removed. In BPMN assignment you must use the standard naming convention. Example: the XML tag 'user-id' must be used as '{{userId}' in assignments.

More information about the syntax of expression used in data associations can be found in: The Java EE 6 Tutorial.

Configuring the service consumer

The service consumer that invokes the service provider can be configured to adjust following parameters by operation:

• the message exchange pattern used: using MEP 'InOut' or 'RobustInOnly' forces the service task to wait the response of the service provider while MEP 'InOnly' ends the service provider without waiting the service provider acknowledgment,
• the timeout to apply on service invocation.

All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:

• JBI parameters that defines the service provider identification,
• CDK parameters that are parameters driving the service consumer implementation at CDK layer,
• CDK interceptor parameters that are parameters driving interceptors at CDK layer.

Example:

<jbi:jbi ...>

   <jbi:services binding-component="false">
      <jbi:provides ...>
         ...
      </jbi:provides>
      
      <jbi:consumes
           interface-name="ns:my-interface"
           service-name="ns:my-service">
         <cdk:mep>InOut</cdk:mep>
         <cdk:operation>tdt-helios-generique:creer</cdk:operation>
         <cdk:timeout>360000</cdk:timeout>
      </jbi:consumes>
         
      <jbi:consumes ...>
         ...
      </jbi:consumes>
      ...

   </jbi:services>
</jbi:jbi>

If no service consumer configuration is found into the SU JBI descriptor for the invoked operation, the following default parameters are used:

• interface name, service name and endpoint name are the one defined on the location of the WSDL endpoint,
• the MEP is the one defined into the WSDL according to input, output and fault of the operation,
• the default timeout defined at CDK level.

Note about timeout on service provider invocation: it can be configured into the associated section 'consumes' of the SU JBI descriptor but it has not to be too long otherwise the Flowable database transaction timeout will be fired. To invoke very long service provider you should use an asynchronous mechanism based on a service task launching your service provider and an intermediate catch event waiting the service provider reply:

CDK parameters defining service consumer implementation

The following parameters correspond to the CDK configuration of the service consumer implementation.

A service consumer is defined into the section 'consumes' of the JBI descriptor, containing:

CDK parameters driving interceptors

The following parameters drive interceptors at CDK layer.

Interceptors can be defined to inject some post or pre-processing in the service provider processing or service consumer processing.

Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5">
   <jbi:services>
      <jbi:provides|consumes>
         <!--...-->
         <petalsCDK:su-interceptors>
            <petalsCDK:send>
               <petalsCDK:interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
                  <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
               </petalsCDK:interceptor>
            </petalsCDK:send>
            <petalsCDK:accept>
               <petalsCDK:interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:interceptor>
            </petalsCDK:accept>
            <petalsCDK:send-response>
               <petalsCDK:Interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:Interceptor>
            </petalsCDK:send-response>
            <petalsCDK:accept-response>
               <petalsCDK:Interceptor name="myInterceptorName">
                  <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
               </petalsCDK:Interceptor>
            </petalsCDK:accept-response>
         </petalsCDK:su-interceptors>
         <!--...-->
      </jbi:provides|consumes>
      <!--...-->
   </jbi:services>
</jbi:jbi>

Using the mode "integration"

The mode "integration" provides different services to interact directly with the BPMN 2.0 engine embedded in the SE Flowable. It goes back over the BPMN 2.0 engine API. Available services are:

The namespace of interface name and service name is http://petals.ow2.org/components/flowable/generic/1.0

The service "UserService"

The service "UserService" provides following operations:

The operation "get"

If no parameter is given, all users are returned.

The operation returns information about the user identified:

• first-name: first name of the user,
• last-name: last name of the user,
• email: e-mail of the user.

The operation "search"

If no parameter is given, all groups are returned.

The operation returns identifier of users matching the given criteria.

The service "GroupService"

The service "GroupService" provides following operations:

The operation "search"

The operation returns identifier of groups matching the given criteria.

The service "ProcessInstancesService"

The service "ProcessInstancesService" provides following operations:

The operation "getProcessInstances"

The search criteria are given by the following parameters, each criteria operates as a filter:

The operation returns a list of process instances. Each process instance contains:

• process-definition-identifier: the process definition identifier of the current process instance,
• process-instance-identifier: the current process instance identifier,
• state: the state of the current process instance, possible values are: 'active', 'suspended' or 'finished',
• variables: all variables set at the the process instance level. Each variable is given with its name and value as String, except for variable type java.util.Date for which the date is converted to xsd:DateTime.

The operation "suspendProcessInstances"

For each process instance identifier of the given list, the process instance will be suspended.

The response returns by this operation is an execution report, where the adjournment result is given for each process instance identifier:

• 'suspended', the adjournment succeeds and the process instance is now suspended,
• 'not-found', no process instance found for the given process instance identifier,
• 'already-suspended', the process instance is already suspended.

The operation "activateProcessInstances"

For each process instance identifier of the given list, the suspended process instance will be activated.

The response returns by this operation is an execution report, where the activation result is given for each process instance identifier:

• 'activated', the activation succeeds and the process instance is now active,
• 'not-found', no process instance found for the given process instance identifier,
• 'already-activated', the process instance is already activated.

The service "ExecutionsService"

The service "ExecutionsService" provides following operations:

The operation "getExecutions"

The search criteria are given by the following parameters, each criteria operates as a filter:

The operation returns a list of executions. Each execution contains:

• process-instance-identifier: the process instance identifier associated to the execution.

The service "TaskService"

The service "TaskService" provides following operations:

The operation "getTasks"

The search criteria are given by the following parameters, each criteria operates as a filter:

The operation returns a list of tasks. Each task contains:

• process-definition-identifier: the process definition identifier of the process instance associated to the current task,
• process-instance-identifier: the process instance identifier of the current task,
• task-identifier: the current task identifier that you can retrieve in the process definition,
• task-name: the current task name that you can retrieve in the process definition,
• task-description: the current task description that you can retrieve in the process definition, with variable substitution,
• task-due-date: the current task due date as defined in the process definition,
• task-priority: the current task priority that you can retrieve in the process definition.
• process-variables: all process variables set at the the process instance level associated to the task. Each variable is given with its name and value as String, except for variable type java.util.Date for which the date is converted to xsd:DateTime.

IDM engine integration

The Flowable engine requires an IDM engine in charge of managing users and groups. It is required by the user tasks that are assigned to users or groups.

Once you have selected your IDM engine implementation, just configure it (the configurator implementation) at component level through the parameters idm-engine-configurator-class-name and idm-engine-configurator-config-file. By default, the Petals SE Flowable uses a file-based IDM engine.

Available IDM engines are:

• file-based IDM engine where users and groups are stored into files,
• LDAP-based IDM engine where users and groups are managed into a LDAP directory,
• Petals service based IDM engine invoking Petals services to retrieve users and groups,
• you can also write your own IDM engine,
• in next versions, new IDM engines will be added.

File-based IDM engine

This IDM engine is a demonstration IDM engine, that's why it is embedded into the Petals SE Flowable. It is based on two files, one containing the users, another containing the group definitions.

Configuration

Parameters of the configuration file of this IDM engine are:

The file-based IDM engine includes a default configuration used when the IDM engine configurator configuration file is not set at the component level. This default configuration is inspired of Flowable itself defining users and groups as mentioned as examples below in file formats. No default provilege is granted.

File formats

The user file is defined as following:

#
# Property format:
#    <user-id> = <user-password>
#
kermit = kermit
fozzie = fozzie
gonzo = gonzo

The group file is defined as following:

#
# Property format:
#    <group-id> = <user-id-1> <user-id-2> ... <user-id-n>
#
admin = kermit
manager = kermit gonzo
management = kermit gonzo
accountancy = kermit fozzie gonzo
engineering = kermit
sales = kermit gonzo
user = fozzie

LDAP-based IDM engine

This IDM engine is the one provided by Flowable as modules flowable-ldap-configurator and flowable-ldap.

Configuration

Parameters of the configuration file of this IDM engine are the ones of the Flowable LDAP configurator:

The LDAP-based IDM engine includes a default configuration used when the IDM engine configurator configuration file is not set at the component level. This default configuration is inspired of Flowable default configuration.

Petals services based IDM engine

TODO

Write your own IDM engine

You can write your own IDM engine. It will be available as a shared library that you will configure to be used by the Petals SE Flowable.

To implement it, just create a class implementing the interface org.ow2.petals.flowable.identity.SeFlowableIdmServiceConfigurator or extending the class org.ow2.petals.flowable.identity.AbstractProcessEngineConfigurator. You can find an example here (the file-based IDM engine), or here (the LDAP-based IDM engine).

Flowable's extensions

The Petals SE Flowable embeds few Flowable's extensions.

Currently, only one extension is available as a custom JUEL function.

Custom JUEL functions

The custom JUEL functions can be used into any JUEL expression.

date:parse

This custom JUEL function parse a date provided as String into a java.util.Date according to the given pattern.

Two arguments are required:

• the first argument is the date value as String to parse,
• the second argument is the date pattern to use to parse the value. The date pattern is driven by java.text.SimpleDateFormat.

Example:

      <serviceTask>
         <ioSpecification>
            ...
         </ioSpecification>
         <dataInputAssociation>
            <targetRef>...</targetRef>
            <assignment>
               <from>${date:parse(myDateStr, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX")}</from>
               <to>...</to>
            </assignment>
         </dataInputAssociation>
      </serviceTask>

petals:getPlaceholder

This custom JUEL function retrieve the value as String of the given placeholder.

Required argument:

• the first argument is the placeholder name as String.

Returned value:

• the placeholder value as String, or null if the placeholder is not defined.

Example:

      <serviceTask id="servicetask1" name="User Task"
         flowable:class="org.ow2.petals.flowable.junit.tasks.DummyJavaDelegate">
         <extensionElements>
            <flowable:field name="param1">
               <flowable:expression>${petals:getPlaceholder('my-placeholder')}</flowable:expression>
            </flowable:field>
         </extensionElements>
      </serviceTask>

petals:getPlaceholderWithDefault

This custom JUEL function retrieve the value as String of the given placeholder.

Required arguments:

• the first argument is the placeholder name as String.
• the second argument is the default value, as String, to return if the given placeholder is not defined.

Returned value:

• the placeholder value as String, or the given default value if the placeholder is not defined.

Example:

      <serviceTask id="servicetask1" name="User Task"
         flowable:class="org.ow2.petals.flowable.junit.tasks.DummyJavaDelegate">
         <extensionElements>
            <flowable:field name="param1">
               <flowable:expression>${petals:getPlaceholderWithDefault('my-placeholder', 'my-placeholder-default-value')}</flowable:expression>
            </flowable:field>
         </extensionElements>
      </serviceTask>

Configuring the component

The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:

• JBI parameters that have not to be changed otherwise the component will not work,
• CDK parameters that are parameters driving the processing of the CDK layer,
• Dedicated parameters that are parameters specific to this component.

CDK parameters

The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.

• Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
• Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.

Interception configuration

Interceptors can be defined to inject some post or pre-processing in the component during service processing.

Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" ...>
   <jbi:component>
      <!--...-->
      <petalsCDK:component-interceptors>
         <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName">
            <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
            <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
         </petalsCDK:interceptor>
      </petalsCDK:component-interceptors>
      <!--...-->
   </jbi:component>
</jbi:jbi>

Component specific parameters

These parameters drive features proposed by the component and configure the Flowable engine embedded in the SE:

• activation of the mode 'integration',
• Flowable engine configuration:
  • the database parameters: your are responsible to provide this database according to your needs. And especially, you must assume that the database is highly available to have a SE Flowable highly available,
  • asynchronous job executor activation and configuration,
  • BPMN validation,
  • identity service to use.

Enabling/disabling the Flowable job executor

Flowable requires a job executor to manage a couple of threads to fire timers, to invoke service tasks, other asynchronous tasks. At least one job executor is required.

When deploying several Petals SE Flowable running with the same database, you can disable the job executor on some Petals SE Flowable. Or even, you can specialized a Petals SE Flowable to process all asynchronous tasks enabling the job executor on only one Petals SE Flowable.

Using placeholders to configure the process definition

The placeholders defined in the properties file of the SE Flowable can be used in the process definition through the custom JUEL function 'petals:getPlaceholder(...)'.

Business monitoring

MONIT traces are logged to each step of the BPMN process interacting with Petals ESB:

• when creating and terminating process instances,
• when starting and completing user tasks,
• when executing service task implemented through Petals services,
• when intermediate catch message event is waiting and receiving message.

The principle of the flow instance identifier of MONIT traces is to permit to retrieve all MONIT traces of a given process flow.

When creating a process instance, two flows are running:

• the flow from which the process instance creation request is coming,
• the flow associated to the process instance that will be created.

When completing a user task, two flow are running also:

• the flow from which the user task completion request is coming,
• the flow associate to the process instance for which the user task must be completed.

When a intermediate catch message event receives its message, two flow are running also:

• the flow from which the message receipt request is coming,
• the flow associate to the process instance for which the intermediated catch message event must be completed.

The service tasks are flow steps of the flow associated to the process instance.

So, we must be able to correlate the flow associated to the process instance with flows associated to interaction requests (process instance creation, user task completion):

Full Size

• on process instance creation, we have the following MONIT traces ordered:
  1. a MONIT trace associated to the start of the interaction request creating the process instance, with following attributes:
     • traceCode set to provideFlowStepBegin,
     • flowInstanceId set to an UUID value,
     • flowStepId set to an UUID value,
     • flowStepInterfaceName set to the interface name of the service creating the process instance,
     • flowStepServiceName set to the service name of the service creating the process instance,
     • flowStepOperationName set to the operation name of the service creating the process instance,
     • flowStepEndpointName set to the endpoint name of the service creating the process instance,
     • flowPreviousStepId set to the step identifier of the previous step in the interaction flow.
  2. a MONIT trace associated to a new flow associated to the process instance, with following attributes:
     • traceCode set to consumeFlowStepBegin
     • flowInstanceId set to a new UUID value,
     • flowStepId set to a new UUID value,
     • flowStepInterfaceName set to the interface name of the service creating the process instance,
     • flowStepServiceName set to the service name of the service creating the process instance,
     • flowStepOperationName set to the operation name of the service creating the process instance,
     • flowStepEndpointName set to the endpoint name of the service creating the process instance,
     • correlatedFlowInstanceId set to the flow instance identifier of the associated interaction request,
     • correlatedFlowStepId set to the flow step identifier of the associated interaction request,
     • processDefinitionName set to the process definition of the created process instance (the value of the process definition attribute: <bpmn:definitions>/<bpmn:process>/@id),
     • processInstanceId set to the identifier of the created process instance.
  3. a MONIT trace associated to the end of the interaction request creating the process instance, with following attributes:
     • traceCode set to provideFlowStepEnd or provideFlowStepFailure,
     • flowInstanceId set to the flow step identifier of the associated interaction request.
     • flowStepId set to the flow step identifier of the associated interaction request.
• on user task completion:
  1. a MONIT trace associated to the start of the interaction request completing the user task, with following attributes:
     • traceCode set to provideFlowStepBegin,
     • flowInstanceId set to an UUID value,
     • flowStepId set to an UUID value,
     • flowStepInterfaceName set to the interface name of the service completing the user task,
     • flowStepServiceName set to the service name of the service completing the user task,
     • flowStepOperationName set to the operation name of the service completing the user task,
     • flowStepEndpointName set to the endpoint name of the service completing the user task,
     • flowPreviousStepId set to the step identifier of the previous step in the interaction flow.
  2. a MONIT trace associated to a new step associated to the user task, with following attributes:
     • traceCode set to provideFlowStepBegin,
     • flowInstanceId set to the flow instance identifier of the process instance
     • flowStepId set to a new UUID value,
     • flowStepInterfaceName set to the interface name of the service completing the user task,
     • flowStepServiceName set to the service name of the service completing the user task,
     • flowStepOperationName set to the operation name of the service completing the user task,
     • flowStepEndpointName set to the endpoint name of the service completing the user task,
     • flowPreviousStepId set to the flow previous step identifier of the process instance,
     • correlatedFlowInstanceId set to the flow instance identifier of the associated interaction request,
     • correlatedFlowStepId set to the flow step identifier of the associated interaction request.
  3. a MONIT trace associated to the end of the interaction request completing the user task, with following attributes:
     • traceCode set to provideFlowStepEnd or provideFlowStepFailure,
     • flowInstanceId set to the flow step identifier of the associated interaction request.
     • flowStepId set to the flow step identifier of the associated interaction request.
• on start of intermediate catch message event:
  1. a MONIT trace associated to a new step associated to an intermediate catch message event, with following attributes:
     • traceCode set to provideFlowStepBegin,
     • flowInstanceId set to the flow instance identifier of the process instance
     • flowStepId set to a new UUID value,
     • flowPreviousStepId set to the flow previous step identifier of the process instance,
     • intermediateCatchMessageEventId set to the identifier of the intermediate catch message event,
     • messageName set to the message name of the the intermediate catch event,
     • intermediateCatchMessageEventId set to the execution instance identifier of intermediate catch message event.
• on completion of an intermediate catch message event
  1. a MONIT trace associated to the start of the interaction request completing an intermediate catch message event, with following attributes:
     • traceCode set to provideFlowStepBegin,
     • flowInstanceId set to an UUID value,
     • flowStepId set to an UUID value,
     • flowStepInterfaceName set to the interface name of the service completing the intermediate catch message event,
     • flowStepServiceName set to the service name of the service completing the intermediate catch message event,
     • flowStepOperationName set to the operation name of the service completing the intermediate catch message event,
     • flowStepEndpointName set to the endpoint name of the service completing the intermediate catch message event,
     • flowPreviousStepId set to the step identifier of the previous step in the interaction flow.
  2. a MONIT trace associated to the message receipt of an intermediate catch message event, with following attributes:
     • traceCode set to provideFlowStepEnd or provideFlowStepFailure,
     • flowInstanceId set to the flow step identifier of the intermediate catch message event.
     • flowStepId set to the flow step identifier of the intermediate catch message event.
     • correlatedFlowInstanceId set to the flow instance identifier of the associated interaction request,
     • correlatedFlowStepId set to the flow step identifier of the associated interaction request.
  3. a MONIT trace associated to the end of the interaction request completing an intermediate catch message event, with following attributes:
     • traceCode set to provideFlowStepEnd or provideFlowStepFailure,
     • flowInstanceId set to the flow step identifier of the associated interaction request.
     • flowStepId set to the flow step identifier of the associated interaction request.
• on process instance termination:
  1. a MONIT trace associated to the end of the process instance, with following attributes:
     • traceCode set to consumeFlowStepEnd or consumeFlowStepFailure,
     • flowInstanceId set to the flow instance identifier of the process instance,
     • flowStepId set to the flow step identifier of the process instance creation step.

Some information about flow are set as variables into each process instance:

• as process variables:
  • petals.flow.instance.id : The flow instance identifier of the process instance,
  • petals.flow.step.id: The flow step identifier associated to the step creating the process instance, and used as previous flow step for all other process tasks,
  • petals.correlated.flow.instance.id: The flow instance identifier of the interaction request having created the process instance,
  • petals.correlated.flow.step.id: The flow step identifier of the interaction request having created the process instance,
• as local variable of user tasks:
  • petals.correlated.flow.instance.id: The flow instance identifier of the interaction request having completed the user task,
  • petals.correlated.flow.step.id: The flow step identifier of the interaction request having completed the user task.
• as local variable of intermediate catch message event:
  • petals.flow.step.id: The flow step identifier associated to intermediate catch message event,
  • petals.correlated.flow.instance.id: The flow instance identifier of the interaction request having completed the intermediate catch message event,
  • petals.correlated.flow.step.id: The flow step identifier of the interaction request having completed the intermediate catch message event.

Flow tracing activation

The flow tracing (ie. MONIT traces generation) is defined according to the property 'org.ow2.petals.monitoring.business.activate-flow-tracing' of the incoming JBI request. If the property does not exist, the parameter activate-flow-tracing of the service provider definition will be inspected. If no parameter is defined at service provider level, the component configuration parameter 'activate-flow-tracing' is used. Finally, by default, the flow tracing is enabled.

Flow tracing propagation

On process instance creation, the current flow tracing activation is stored in the process instance into the variable 'petals.flow.external.tracing.activation.state'. The flow tracing propagation from the process instance to a service provider (through a service task) is driven by the parameter propagate-flow-tracing-activation of the service consumer definition. If no parameter is defined at service consumer level, the component configuration parameter 'propagate-flow-tracing-activation' is used. Finally, by default, the flow tracing propagation is enabled.

Logging

The traces of the BPMN 2.0 engine "Flowable" are activated through the logging configuration file of Petals ESB. The root logger for Flowable is org.flowable:

...
org.activiti.level=INFO
org.activiti.engine.impl.level=FINE
...

Monitoring the component

Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

Common metrics

The following metrics are provided through the Petals CDK, and are common to all components:

Dedicated metrics

Moreover the common metrics, some dedicated probes are include on the component:

Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios.

Common alerts

Dedicated alerts

Moreover the common metrics, some dedicated alerts can be sent by the component:

Unit testing

The unit testing can occur at several levels in your Flowable service unit:

• to check the annotation compliance of the WSDL with the attendees of the component,
• to unit test your XSL generating outputs,
• to unit test your process definition.

A dedicated framework is available as an extension of JUnit providing facilities:

• to validate your WSDL:
  • in a WSDL point of view,
  • and checking the compliance of the WSDL with the attendees of the component,
• to verify easily the XSL used to generate output replies.

This dedicated framework is provided by the Maven artifact org.ow2.petals:petals-se-flowable-junit:

<project>
   ...
   <dependencies>
      ...
      <dependency>
         <groupId>org.ow2.petals</groupId>
         <artifactId>petals-se-flowable-junit</artifactId>
         <version>1.1.1</version>
         <scope>test</scope>
      </dependency>
      ...
   </dependencies>
   ...
</project>

See the Compatibility Matrix to known the version of the SE Flowable Junit framework compliant with your version of the SE Flowable.

Checking the compliance of the WSDL

The unit test framework contains an assertion 'assertWsdlCompliance' to verify easily the compliance of your WSDL with the attendees of the mode 'service':

import static org.ow2.petals.flowable.junit.Assert.assertWsdlCompliance;
import javax.xml.namespace.QName;
import org.junit.Test;

public class ValidateTest {

    @Test
    public void validate() throws Exception {
        assertWsdlCompliance(new QName[] { new QName("http://petals.ow2.org/samples/se-flowable/vacationService", "new"),
                new QName("http://petals.ow2.org/samples/se-flowable/vacationService", "validate"),
                new QName("http://petals.ow2.org/samples/se-flowable/vacationService", "update") });
    }

}

See the Javadoc for more details on parameters.

Unit-testing your XSLs

The unit test framework contains an assertion 'assertXslTransformation' to verify easily the result of your XSL transformations:

import static org.ow2.petals.flowable.junit.Assert.assertXslTransformation;
import ...
import org.junit.Test;

public class XslTest {

    @Test
    public void newVacationRequestResponse_Nominal() throws IOException, TransformerException, SAXException {
        assertXslTransformation(NEW_VACATION_RESULT_DIR + "nominal.xml", XSL_NEW_VACATION, "AZE123", null, null, false);
    }

}

See the Javadoc for more details on parameters.

Unit-testing your process definition

Flowable provides a JUnit framework to write unit tests about business processes. You can find several articles on this subject on Internet, for example here.
We don't discuss how to use the Flowable JUnit framework but how to integrate it into a service unit project.

We provided a JUnit framework inherited from the Flowable one that add several utility methods to simplify checks about our process. These methods are available as member methods of PetalsFlowableRule:

• awaiting methods (wait...) as 'waitEndOfProcessInstance' to wait the end of a process instance.
• assertion methods (assert...) as 'assertProcessInstanceFinished' to check that your process instance is ended.
  See the class PetalsFlowableRule to get the list of methods.

First, you must embedd an Flowable engine for your test, adding an dependency on it with scope test into your POM file. Don't forget to add also the JDBC driver, H2 for example, and the Petals JUnit Flowable framework:

<project>
   ...
   <dependencies>
      ...
      <dependency>
         <groupId>org.flowable</groupId>
         <artifactId>flowable-engine</artifactId>
         <version>6.0.1</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>com.h2database</groupId>
         <artifactId>h2</artifactId>
         <version>1.4.178</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.ow2.petals</groupId>
         <artifactId>petals-se-flowable-junit</artifactId>
         <version>1.0.0</version>
         <scope>test</scope>
      </dependency>
      ...
   </dependencies>
   ...
</project>

Caution to use the same version of the Flowable engine as the one embedded into the Petals SE Flowable

Next, you can configure the Flowable engine through a Spring configuration located into the file src/test/resources/flowable.cfg.xml containing something like:

<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans.xsd">

   <bean id="processEngineConfiguration" class="org.flowable.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration">
      <!-- Database configuration. By default an in-memory embeded database is used -->
      <property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000" />
      <property name="jdbcDriver" value="org.h2.Driver" />
      <property name="jdbcUsername" value="sa" />
      <property name="jdbcPassword" value="" />

      <!-- Enable and configure the async executor -->
      <property name="asyncExecutorActivate" value="true"/>
      <property name="asyncExecutor" ref="asyncExecutor"/>
   </bean>
    
   <bean id="asyncExecutor" class="org.flowable.job.service.impl.asyncexecutor.DefaultAsyncJobExecutor">
      <property name="defaultAsyncJobAcquireWaitTimeInMillis" value="1000"/>
      <property name="defaultTimerJobAcquireWaitTimeInMillis" value="1000"/>
   </bean>
    
</beans>

So, with this, you will be able to test the deployment of your process definition and check process instance creations using the Petals Flowable JUnit framework:

public class ProcessDeploymentTest {
    
    @Rule
    public final PetalsFlowableRule flowableRule = new PetalsFlowableRule();
    
    @Test
    @Deployment(resources = {"jbi/vacationRequest.bpmn20.xml"})
    public void theProcessIsDeployableAndInstanciable() {
        final ProcessDefinition processDefinition = this.flowableRule.getRepositoryService()
                .createProcessDefinitionQuery().processDefinitionKey("vacationRequest").singleResult();
        assertNotNull(processDefinition);

        final Map<String, Object> variables = new HashMap<String, Object>();
        variables.put("numberOfDays", 10);
        variables.put("startDate", new Date());
        variables.put("vacationMotivation", "Vacations");
        final ProcessInstance processInstance = this.flowableRule.getRuntimeService().startProcessInstanceByKey("vacationRequest", variables);
        assertNotNull(processInstance);
    }
}

If your process definition includes Petals service invocations, you must use mocks for these services. These mocks can be SoapUI mock services invoked as standard web-services, using HTTP/SOAP. The URLs of these mock services must be mapped on the endpoint names define in service provider WSDLs used in the process definition. The mapping is declared in the Spring configuration file as following:

   <bean id="archiveEndpoint" class="javax.xml.namespace.QName">
      <constructor-arg index="0" value="http://petals.ow2.org/samples/se-flowable/archiveService" />
      <constructor-arg index="1" value="autogenerate" />
   </bean>

   <bean id="notifyEndpoint" class="javax.xml.namespace.QName">
      <constructor-arg index="0" value="http://petals.ow2.org/samples/se-flowable/notifyVacationService" />
      <constructor-arg index="1" value="autogenerate" />
   </bean>

   <bean id="wsOverridenEndpointAddresses" class="java.util.concurrent.ConcurrentHashMap">
      <constructor-arg index="0">
         <map>
            <entry>
               <key>
                  <ref bean="archiveEndpoint" />
               </key>
               <value type="java.net.URL">http://localhost:8188/mockarchiveSoapBinding</value>
            </entry>
            <entry>
               <key>
                  <ref bean="notifyEndpoint" />
               </key>
               <value type="java.net.URL">http://localhost:8188/mocknotifyVacationBinding</value>
            </entry>
         </map>
      </constructor-arg>
   </bean>
 
   <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration">
      ...
      <property name="wsOverridenEndpointAddresses">
         <ref bean="wsOverridenEndpointAddresses" />
      </property>
   </bean>

and SoapUI mock services can be automatically started at Maven level with following declaration in the POM file of the service unit:

<project>
   ...
   <pluginRepositories>
      <pluginRepository>
         <id>smartbear-sweden-plugin-repository</id>
         <url>http://www.soapui.org/repository/maven2/</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>false</enabled>
         </snapshots>
      </pluginRepository>
   </pluginRepositories>

   <build>
      <plugins>
         ...
         <plugin>
            <groupId>com.smartbear.soapui</groupId>
            <artifactId>soapui-maven-plugin</artifactId>
            <version>5.2.1</version>
            <executions>
               <execution>
                  <id>startup-mock-archive</id>
                  <configuration>
                     <projectFile>${basedir}/src/test/soapui/su-flowable-vacationService-provide-soapui-project.xml</projectFile>
                     <mockService>archiveSoapBinding MockService</mockService>
                     <noBlock>true</noBlock>
                  </configuration>
                  <goals>
                     <goal>mock</goal>
                  </goals>
                  <phase>process-test-classes</phase>
               </execution>
               <execution>
                  <id>startup-mock-notify</id>
                  <configuration>
                     <projectFile>${basedir}/src/test/soapui/su-flowable-vacationService-provide-soapui-project.xml</projectFile>
                     <mockService>notifyVacationBinding MockService</mockService>
                     <noBlock>true</noBlock>
                  </configuration>
                  <goals>
                     <goal>mock</goal>
                  </goals>
                  <phase>process-test-classes</phase>
               </execution>
            </executions>
         </plugin>
         ...
      </plugins>
   </build>
   ...
</project>

where SoapUI project files contains mock service definitions.

Migration guide

Migrating service units developed for previous versions

To be deployed on this version of the Petals SE Flowable, the Petals SE Flowable service units must be migrated. Please follow the following chapters to know which changes must be applied.

From 1.3.2 to 1.4.x

Please apply the following changes in your Petals SE Flowable service unit to migrate them from Petals SE Flowable 1.3.2 to Petals SE Flowable 1.4.x:

• in your process definitions and unit tests:
  • the process variable 'petalsPlaceholders' associated to the placeholders is now replaced by the custom JUEL functions 'petals:getPlaceholder' or 'petals:getPlaceholderWithDefault'.