Petals-SE-Flowable 1.4.0+

This version must be installed on Petals ESB 5.3.0+

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
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:

Administrative JMX operation Description
listPurgeableProcessInstances List all purgeable process instances of the given process definition. A purgeable process instance is a process instance that is terminated. The list of identifiers of purgeable process instances is returned.
purgeProcessInstance Purge a process instance deleting all its data. This operation returns all flow instance identifiers associated to the process instance that can be used to purge MONIT traces in a next step.
undeployProcessDefinition Undeploy a process definition.

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:

Value of action Operation executed on the process engine
startEvent Create a new instance of the process. See [petalscomponents:Associating an operation to the creation of an process definition instance] for more information on this operation.
userTask Complete a user task. See [petalscomponents:Associating an operation to the completion of a process instance task] for more information on this operation.
intermediateMessageCatch Catches an intermediate message. See [petalscomponents:Associating an operation to the catching of an intermediate message] for more information on this operation.

The action is completed with the another attribute as following:

Value of action Extra attributes
startEvent According to the nature of your start event step, you must use the following extra attribute to identify it:
  • none-start-event-id, for none start event step, it will contain the identifier of the none start event step in the process definition,
  • start-event-message-name, for message start event step, it will contain the name of the message in the process definition that fires this start event step.
userTask The identifier in the process definition of the user task to complete associated to the operation is given through the extra attribute user-task-id.
through the extra attribute {{user-task-id. }} The message name in the process definition of the intermediate message catch event associated to the operation is provided through this extra attribute.

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:

Value of the attribute action of the annotation flowable:operation Operation executed on the process engine
startEvent Expected input parameters are:
  • the process identifier,
  • the user identifier.
    See [petalscomponents:Associating an operation to the creation of an process definition instance] for more information on the declaration of this parameter.
userTask Expected input parameters are:
  • the process instance identifier,
  • the user identifier.
    See [petalscomponents:Associating an operation to the completion of a process instance task] for more information on the declaration of these parameters.
intermediateMessageCatch Expected input parameter is the process instance identifier. See [petalscomponents:Associating an operation to the catching of an intermediate message] for more information on the declaration of these parameters.

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:

XSL parameter name Type Description
{ http://petals.ow2.org/se/flowable/output-params/1.0/special

}processInstanceId

String Identifier of the process instance created
{ http://petals.ow2.org/se/flowable/output-params/1.0/special

}userId

String The user identifier used to create the process instance
{ http://petals.ow2.org/se/flowable/output-params/1.0/process-instance

}variable-name

String Process instance variables. <variable-name> is the name of a process instance variable.

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 mapping sample
<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>
Associated input request
<newOrderRequest>
   <userName>Jean Zé</userName>
   <customerName>Mr Dupont Martin</customerName>
   <address>23, rue de la Paie, 75000 Paris</address>
</newOrderRequest>
Associated output request
<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:

XSL parameter name Type Description
{ http://petals.ow2.org/se/flowable/output-params/1.0/special

}processInstanceId

String Identifier of the process instance created
{ http://petals.ow2.org/se/flowable/output-params/1.0/special

}userId

String The user identifier used to create the process instance
{ http://petals.ow2.org/se/flowable/output-params/1.0/process-instance

}variable-name

String Process instance variables. <variable-name> is the name of a process instance variable.
{ http://petals.ow2.org/se/flowable/output-params/1.0/task

}variable-name

String Task local variables. <variable-name> is the name of a task local variable.

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

Error Description XSL parameters
TaskCompletedException The associated user task is already completed
ProcessInstanceNotFoundException No active process instance found for the given process instance identifier process instance identifier: { http://petals.ow2.org/se/flowable/faults/1.0

}processInstanceId

UnexpectedUserException The task to complete is assigned to another user identifier

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 mapping sample
<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>
Associated input request
<validOrderRequest>
   <orderId>12345</orderId>
   <isValidated>true</isValidated>
   <creditCardNumber>1234567890123</customerName>
   <userName>Robert Té</userName>
</validOrderRequest>
Associated output request
<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:

Error Description XSL parameters
ProcessInstanceNotFoundException No process instance found for the given process instance identifier process instance identifier: { http://petals.ow2.org/se/flowable/faults/1.0

}processInstanceId

ProcessInstanceEndedException The process instance found for the given process instance identifier is ended process instance identifier: { http://petals.ow2.org/se/flowable/faults/1.0

}processInstanceId

UnexpectedMessageEventException No catcher is expecting the intermediate message event on BPMN engine side

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 mapping sample
<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>
Associated input request
<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:

Input parameter name Type Description Required
isActive Boolean Only active task are returned. No
responsibleUser String Only select tasks for which the given user is a candidate are returned. No
responsibleGroup String Only select tasks for which users in the given group are candidates are returned. No

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:

XSL parameter name Type Description
processInstances Quel type 'list' est exploitable coté XSL The list of process instance identifier matching criteria.

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:

Parameter
Description
Default
Required
Support placeholders
interface-name
Interface name of the service provider. Must match the one defined in the WSDL.
-
Yes
No
service-name
Service name of the service provider. Must match the one defined in the WSDL.
-
Yes
No
endpoint-name
Endpoint name of the service provider. Must match the one defined in the WSDL. The value 'autogenerate' will force Petals ESB to generate an endpoint name as UUID at deployment time.
-
Yes
No
timeout
Timeout in milliseconds of a synchronous send. This parameter is used by the method sendSync(Exchange exchange) proposes by the CDK Listeners classes.
Set it to 0 for an infinite timeout.
30000
No
Yes
su-interceptors
Service unit interceptor configuration. See Service unit interceptor configuration.
-
No
No
exchange-properties
This sections defines the list of properties to set to the JBI exchange when processing a service.
-
No
No
message-properties
This sections defines the list of properties to set to the JBI message when processing a service.
-
No
No
validate-wsdl
Activate the validation of the WSDL when deploying a service unit.
true
No
No
forward-security-subject
Defines if the security subject will be forwarded from IN message to OUT message.
false
No
No
forward-message-properties
Defines if the message properties will be forwarded from IN message to OUT message.
false
No
No
forward-attachments
Defines if attachment will be forwarded from IN message to OUT message.
false
No
No
activate-flow-tracing
Enable ('true') or disable ('false') the flow tracing for this service provider. This value overrides the value defined at component level and can be overridden at incoming exchange level.
Value defined at component
No
Yes
wsdl
Path to the WSDL document describing services and operations exposed by the provided JBI endpoints defined in the SU.
The value of this parameter is :
  • an URL
  • a file relative to the root of the SU package
    If not specified, a basic WSDL description is automatically provided by the CDK.
-
Yes
No

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>

Interceptors configuration for SU (CDK)

Parameter Description Default Required
send Interceptor dedicated to send phase, for an exchange sent by a consumer - No
accept Interceptor dedicated to receive phase, for an exchange received by a provider - No
send-response Interceptor dedicated to send phase, for an exchange (a response) received by a consumer - No
accept-response Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider - No
interceptor - name Logical name of the interceptor instance defined at component level, see CDK Component Interceptor configuration. - Yes
param[] - name The name of the parameter to use for the interceptor for this SU - No
param[] The value of the parameter to use for the interceptor for this SU - No

Dedicated configuration

Parameter Description Default Required
tenant_id Tenant identifier. As the multitenancy is supported, such an identifier is required. myTenant No
category_id Deployment category identifier. For example to group business processes. myCategory No
process_file Name of the process definition file into the service unit (relative to the root of the service unit).
To deploy several process definition files use process_file<X> where <X> is a number starting to 1. process_file<X> must have its own version<X>.
Yes
version Version of the process definition.
Yes

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:

Parameter
Description
Default
Required
Support placeholders
interface-name
Interface name of the service provider to invoke.
-
Yes
No
service-name
Service name of the service provider to invoke.
-
No
No
endpoint-name
Endpoint name of the service provider to invoke.
-
No
No
timeout
Timeout in milliseconds of a synchronous send. This parameter can be used in conjunction with the sendSync(Exchange exchange) method of the Listeners. Set 0 for an infinite timeout. 30000
No
Yes
operation
Operation to call on the service provider. If no operation is specified in the Message Exchange to send, this parameter will be used.
-
No
No
activate-flow-tracing
This parameter makes sens only for service consumer running on binding component.
-
-
-
propagate-flow-tracing-activation
Control whether the flow tracing activation state must be propagated to next flow steps or not. If 'true', the flow tracing activation state is propagated to the invoked service provider. This value overrides the value defined at component level. Value defined at component
No
Yes
su-interceptors
Service unit interceptor configuration. See Service unit interceptor configuration.
-
No
No
mep
Message exchange pattern to use.
-
Yes
No

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>

Interceptors configuration for SU (CDK)

Parameter Description Default Required
send Interceptor dedicated to send phase, for an exchange sent by a consumer - No
accept Interceptor dedicated to receive phase, for an exchange received by a provider - No
send-response Interceptor dedicated to send phase, for an exchange (a response) received by a consumer - No
accept-response Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider - No
interceptor - name Logical name of the interceptor instance defined at component level, see CDK Component Interceptor configuration. - Yes
param[] - name The name of the parameter to use for the interceptor for this SU - No
param[] The value of the parameter to use for the interceptor for this SU - No

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:

Interface name Service name Description
ProcessInstances ProcessInstancesService To manage process instances
Executions ExecutionsService To manage internal Flowable executions
Task TaskService To manage tasks of process instances
User UserService To manage users of Flowable identity service
Group GroupService To manage groups of Flowable identity service
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:

Operation name Description
get Get information about a user.
search Search users according to criteria.

The operation "get"

Parameter name Description Default value
id User id. No default value
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"

Parameter name Description Default value
group-id Group id for which users returned must be member of. No default value
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:

Operation name Description
search Search groups according to criteria.

The operation "search"

Parameter name Description Default value
user-id Identifier of the user member of groups returned. No default value

The operation returns identifier of groups matching the given criteria.

The service "ProcessInstancesService"

The service "ProcessInstancesService" provides following operations:

Operation name Description
getProcessInstances Query process instances according to the given criteria.
suspendProcessInstances Suspend a process instance list.
activateProcessInstances Activate a process instance list.

The operation "getProcessInstances"

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

Parameter name Description Default value
state Process instances returned must match this state. Possible values are:
  • 'active', means that neither the process instance nor the corresponding process definition are suspended,
  • 'suspended', means that the process instance or the corresponding process definition are suspended,
  • 'finished', means that the process instance has ended.
any
process-definition-identifier Process instances returned must match this process definition identifier. No default value
process-instance-identifier Only the process instance matching this identifier is returned. No default value
variables Process instances returned must match theses variables, names and values.
An optional attribute 'as' should be used for variable types different from 'string'. Possible values are: 'long', 'double', 'date', 'string', 'boolean'.
No default value

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:

Operation name Description
getExecutions Query executions according to the given criteria.

The operation "getExecutions"

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

Parameter name Description Default value
process-definition-identifier Executions returned must match this process definition identifier. No default value
process-instance-identifier Only the executions matching this identifier are returned. No default value
event-name Only the executions waiting this event through an intermediate message catch event' are returned. No default value

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:

Operation name Description
getTasks Query tasks according to the given criteria

The operation "getTasks"

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

Parameter name Description Default value
active If "true", only selects tasks which are active (ie. for which the process instance is not suspended) true
assignee Only select tasks for which the given user is a candidate or the assignee. No default value
process-instance-identifier Only select tasks for the given process instance identifier. No default value
process-definition-identifier Only select tasks member of the process instances matching the given process definition identifier. No default value
task-definition-identifier Only select tasks matching the given task definition identifier. No default value
with-process-instance-variable If 'true', process variables associated to each task will be returned. false

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:

Parameter name Description Mandatory
users-file File name of the file containing the user declarations. If it is an existing absolute file name, the file is read as a file from the filesystem, otherwise it is read as a resource from the component classloader. Yes
groups-file File name of the file containing the user group declarations. If it is an existing absolute file name, the file is read as a file from the filesystem, otherwise it is read as a resource from the component classloader. Yes
privileges-file File name of the file containing the privilege declarations of users and groups. If it is an existing absolute file name, the file is read as a file from the filesystem, otherwise it is read as a resource from the component classloader. Privilege declarations are required by Flowable UIs or Flowable REST API Yes, can be emty

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:

Parameter name Description Mandatory
server The server on which the LDAP system can be reached. Yes
port The port on which the LDAP system is running. Yes
user The user id that is used to connect to the LDAP system. No
password The password that is used to connect to the LDAP system. No
baseDn The base distinguished name (DN) from which the searches for users and groups are started. Yes
userBaseDn The base distinguished name (DN) from which the searches for users are started. If not provided, baseDn (see above) will be used. Yes
groupBaseDn The base distinguished name (DN) from which the searches for groups are started. If not provided, baseDn (see above) will be used. Yes
searchTimeLimit The timeout that is used when doing a search in LDAP in milliseconds. Default value: 1 hour. No
queryUserByUserId The query that is executed when searching for a user by userId. Here, all the objects in LDAP with the class inetOrgPerson and who have the matching uid attribute value will be returned. As shown in the example, the user id is injected by using {0}. For example: (&(objectClass=inetOrgPerson)(uid={0})) Yes
queryUserByFullNameLike The query that is executed when searching for a user by full name. Here, all the objects in LDAP with the class inetOrgPerson and who have the matching first name and last name values will be returned. Note that {0} injects the firstNameAttribute (as defined above), {1} and {3} the search text and {2} the lastNameAttribute. For example: (&(objectClass=inetOrgPerson)(({0}={1})({2}={3}))) Yes
queryAllUsers The query that is executed when searching on users without a filter. Here, all the objects in LDAP with the class inetOrgPerson will be returned. For example: (objectClass=inetOrgPerson) Yes
queryGroupsForUser The query that is executed when searching for the groups of a specific user. Here, all the objects in LDAP with the class groupOfUniqueNames and where the provided DN (matching a DN for a user) is a uniqueMember are returned. As shown in the example, the user id is injected by using {0}. For example: (&(objectClass=groupOfUniqueNames)(uniqueMember={0})) Yes
queryAllGroups The query that is executed when searching on groups without a filter. Here, all the objects in LDAP with the class groupOfUniqueNames will be returned. For example: (objectClass=groupOfUniqueNames) Yes
userFirstNameAttribute Name of the attribute that matches the user first name. Yes
userLastNameAttribute Name of the attribute that matches the user last name. Yes
groupIdAttribute Name of the attribute that matches the group id. Yes
groupNameAttribute Name of the attribute that matches the group name. Yes

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>

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.

Parameter Description Default Scope*
acceptor-pool-size The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread. 1
Runtime
acceptor-retry-number Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed. 40
Installation
acceptor-retry-wait Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one plus this base duration. 250
Installation
acceptor-stop-max-wait The max duration (in milliseconds) before, on component stop, each acceptor is stopped by force. 500
Runtime
processor-pool-size The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool. 10 Runtime
processor-max-pool-size The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time.
50
Runtime
processor-keep-alive-time When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds.
300
Runtime
processor-stop-max-wait The max duration (in milliseconds) of message exchange processing on stop phase (for all processors).
15000
Runtime
time-beetween-async-cleaner-runs The time (in milliseconds) between two runs of the asynchronous message exchange cleaner.
2000
Installation
properties-file Name of the file containing properties used as reference by other parameters. Parameters reference the property name using a placeholder in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property.

The properties file can be reloaded using the JMX API of the component. The runtime configuration MBean provides an operation to reload these place holders. Check the service unit parameters that support this reloading.

The value of this parameter is :
  • an URL
  • a file relative to the PEtALS installation path
  • an absolute file path
  • an empty value to stipulate a non-using file.
- Installation
monitoring-sampling-period Period, in seconds, of a sample used by response time probes of the monitoring feature. 300 Installation
activate-flow-tracing Enable ('true') or disable ('false') the flow tracing. This value can be overridden at service consumer or service provider level, or at exchange level. true Runtime
propagate-flow-tracing-activation Control whether the flow tracing activation state must be propagated to next flow steps or not. If 'true', the flow tracing activation state is propagated. This value can be overridden at service consumer level. true Runtime
component-interceptors Component interceptor configuration. See CDK Component interceptor configuration. - See Maven Petals plugin to known how to inject component interceptor configuration in component configuration

* Definition of CDK parameter scopes:

  • 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>

Interceptors configuration for Component (CDK)

Parameter Description Default Required
interceptor - class Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. - Yes
interceptor - name Logical name of the interceptor instance. It is referenced at service unit level to register this interceptor for services of the service unit. See SU Interceptor configuration. - Yes
interceptor - active If true, the Interceptor instance is activated for every SU deployed on the component.
If false, the Interceptor can be activated:
-by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU.
-by a SU configuration
- Yes
param[] - name The name of the parameter to use for the interceptor. - No
param[] The value of the parameter to use for the interceptor. - No

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.

Parameter Description Default Required Scope
integration-mode-enable Enable the mode 'Integration'
true
No
Installation
jdbc_url URL of the database. The default database is an in-memory database
jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000
Yes
Installation
jdbc_driver JDBC driver. Except for the default JDBC driver, it must be provided as shared-library.
org.h2.Driver
Yes
Installation
jdbc_username Username used for the database connection.
sa
Yes
Installation
jdbc_password Password used for the database connection.
""
Yes
Installation
jdbc_max_active_connections The number of active connections that the database connection pool at maximum at any time can contain.
10
No
Installation
jdbc_max_idle_connections The number of idle connections that the database connection pool at maximum at any time can contain.
-
No
Installation
jdbc_max_checkout_time The amount of time in milliseconds a connection can be 'checked out' from the connection pool before it is forcefully returned.
20000 (20 seconds)
No
Installation
jdbc_max_wait_time This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured).
20000 (20 seconds)
No
Installation
database_type The database type: it's normally not necessary to specify this property it is automatically analyzed from the database connection meta data. Should only be specified in case automatic detection fails on Flowable engine side. Possible values: h2, mysql, oracle, postgres, mssql, db2.
-
No
Installation
database_schema_update The database schema update: allows to set the strategy to handle the database schema on process engine boot and shutdown:
  • false: Checks the version of the DB schema against the library when the process engine is being created and throws an exception if the versions don't match.
  • true: Upon building the process engine, a check is performed and an update of the schema is performed if it is necessary. If the schema doesn't exist, it is created.
  • create-drop: Creates the schema when the process engine is being created and drops the schema when the process engine is being closed.
true
No
Installation
engine-enable-job-executor Enable or disable the Flowable job executor. See [petalscomponents:Enabling/disabling the Flowable job executor]
true
No
Installation
engine-job-executor-core-pool-size The minimal number of threads that are kept alive in the thread pool for job execution of the Flowable engine job executor.
2
No
Installation
engine-job-executor-max-pool-size The maximum number of threads that are kept alive in the thread pool for job execution of the Flowable engine job executor.
10
No
Installation
engine-job-executor-keep-alive-time The time, in milliseconds, a thread used for job execution must be kept alive before it is destroyed.
5000
No
Installation
engine-job-executor-queue-size The size of the queue on which jobs to be executed are placed.
100
No
Installation
engine-job-executor-max-timer-jobs-per-acquisition The number of timer jobs that are fetched from the database in one query.
1
No
Installation
engine-job-executor-max-async-jobs-due-per-acquisition The number of asynchronous jobs due that are fetched from the database in one query.
1
No
Installation
engine-job-executor-async-job-acquire-wait-time The time, in milliseconds, between asynchronous job due queries being executed.
10000
No
Installation
engine-job-executor-timer-job-acquire-wait-time The time in milliseconds between timer job queries being executed.
10000
No
Installation
engine-job-executor-timer-lock-time The time, in milliseconds, that a timer job is locked before being retried again.
300000
No
Installation
engine-job-executor-async-job-lock-time The time in milliseconds that an asynchronous job is locked before being retried again.
300000
No
Installation
engine-enable-bpmn-validation Enable or disable the BPMN validation of processes to deploy into the Flowable engine
true
No
Installation
engine-default-failed-job-wait-time The default wait time for a failed job, in seconds
10
No
Installation
engine-async-failed-job-wait-time The default wait time for a async failed job, in seconds
10
No
Installation
idm-engine-configurator-class-name Class name of the identity service to use.
org.ow2.petals.flowable.identity.file.FileIdmEngineConfigurator
No
Installation
idm-engine-configurator-config-file Configuration file of the identity service used.
The default configuration of the identity service is service dependent. See documentation of the identity service
No
Installation
engine-rest-api-enable Enable the REST API of the Flowable engine. The REST API will be available at the following endpoint: http://<petals-host>:<engine-rest-api-port>/flowable-rest-api and requires a BASIC authentication with a user having the privilege defined by <engine-rest-api-access-privilege
true
No
Installation
engine-rest-api-port Listenning port of the REST API of the Flowable engine.
8089
No
Installation
engine-rest-api-address Listenning interface of the REST API of the Flowable engine. To listen on all network interface use the value '0.0.0.0'
0.0.0.0
No
Installation
engine-rest-api-access-privilege Name of the privilege to access the Flowable REST API. By default the user 'rest-api-user/user-api-rest-password' is the only member having the privilege 'rest-access-api'
rest-access-api
No
Installation

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. A dedicated map variable containing all placeholders is set when starting the process instance: petalsPlaceholders. If the placeholder 'signaturePeriod' is defined, it can be used as following in the process definition:

    <intermediateCatchEvent id="waitBeforeGetStatus" name="Wait">
      <timerEventDefinition>
        <timeDuration>${empty execution.variableInstances.petalsPlaceholders.getValue().signaturePeriod ? "PT1H" : execution.variableInstances.petalsPlaceholders.getValue().signaturePeriod}</timeDuration>
      </timerEventDefinition>
    </intermediateCatchEvent>
The dedicated map variable is automatically copied to be accessible as variable of sub-processes.

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
A&#32;Gliffy&#32;Diagram&#32;named&#58;&#32;MONIT&#32;trace&#32;correlations
  • 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:

Metrics, as MBean attribute Description Detail of the value Configurable
MessageExchangeAcceptorThreadPoolMaxSize The maximum number of threads of the message exchange acceptor thread pool integer value, since the last startup of the component yes, through acceptor-pool-size
MessageExchangeAcceptorThreadPoolCurrentSize The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. instant integer value no
MessageExchangeAcceptorCurrentWorking The current number of working message exchange acceptors. instant long value no
MessageExchangeAcceptorMaxWorking The max number of working message exchange acceptors. long value, since the last startup of the component no
MessageExchangeAcceptorAbsoluteDurations The aggregated durations of the working message exchange acceptors since the last startup of the component. n-tuple value containing, in nanosecond:
  • the maximum duration,
  • the average duration,
  • the minimum duration.
no
MessageExchangeAcceptorRelativeDurations The aggregated durations of the working message exchange acceptors on the last sample. n-tuple value containing, in nanosecond:
  • the maximum duration,
  • the average duration,
  • the minimum duration,
  • the 10-percentile duration (10% of the durations are lesser than this value),
  • the 50-percentile duration (50% of the durations are lesser than this value),
  • the 90-percentile duration (90% of the durations are upper than this value).
no
MessageExchangeProcessorAbsoluteDurations The aggregated durations of the working message exchange processor since the last startup of the component. n-tuple value containing, in milliseconds:
  • the maximum duration,
  • the average duration,
  • the minimum duration.
no
MessageExchangeProcessorRelativeDurations The aggregated durations of the working message exchange processor on the last sample. n-tuple value containing, in milliseconds:
  • the maximum duration,
  • the average duration,
  • the minimum duration,
  • the 10-percentile duration (10% of the durations are lesser than this value),
  • the 50-percentile duration (50% of the durations are lesser than this value),
  • the 90-percentile duration (90% of the durations are upper than this value).
no
MessageExchangeProcessorThreadPoolActiveThreadsCurrent The current number of active threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolActiveThreadsMax The maximum number of threads of the message exchange processor thread pool that was active integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolIdleThreadsCurrent The current number of idle threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolIdleThreadsMax The maximum number of threads of the message exchange processor thread pool that was idle integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolMaxSize The maximum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-max
MessageExchangeProcessorThreadPoolMinSize The minimum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-min
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent The current number of enqueued requests waiting to be processed by the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolQueuedRequestsMax The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component instant integer value no
ServiceProviderInvocations The number of service provider invocations grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
integer counter value since the last startup of the component no
ServiceProviderInvocationsResponseTimeAbs The aggregated response times of the service provider invocations since the last startup of the component grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time.
no
ServiceProviderInvocationsResponseTimeRel The aggregated response times of the service provider invocations on the last sample, grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time,
  • the 10-percentile response time (10% of the response times are lesser than this value),
  • the 50-percentile response time (50% of the response times are lesser than this value),
  • the 90-percentile response time (90% of the response times are lesser than this value).
no

Dedicated metrics

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

Metrics, as MBean attribute Description Detail of the value Configurable
ProcessDefinitions List current process definitions deployed with some metrics on process instances n-tuple value containing:
  • the suspension state: '1' the process definition is suspended, '0' it is not suspended,
  • the number of active process instances,
  • the number of suspended process instances,
  • the number of ended process instances.
no
AsyncExecutorThreadPoolActiveThreadsCurrent The current number of active threads of the message exchange processor thread pool instant integer value no
AsyncExecutorThreadPoolActiveThreadsMax The maximum number of threads of the message exchange processor thread pool that was active integer value, since the last startup of the component no
AsyncExecutorThreadPoolIdleThreadsCurrent The current number of idle threads of the message exchange processor thread pool instant integer value no
AsyncExecutorThreadPoolIdleThreadsMax The maximum number of threads of the message exchange processor thread pool that was idle integer value, since the last startup of the component no
AsyncExecutorThreadPoolMaxSize The maximum size, in threads, of the message exchange processor thread pool instant integer value no
AsyncExecutorThreadPoolMinSize The minimum size, in threads, of the message exchange processor thread pool instant integer value no
AsyncExecutorThreadPoolQueuedRequestsCurrent The current number of enqueued requests waiting to be processed by the message exchange processor thread pool instant integer value no
AsyncExecutorThreadPoolQueuedRequestsMax The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component instant integer value no
DatabaseConnectionPoolActiveConnectionsCurrent The current number of active connections of the database connection pool instant integer value no
DatabaseConnectionPoolActiveConnectionsMax The maximum number of connections of the database connection pool that was active integer value, since the last startup of the component no
DatabaseConnectionPoolIdleConnectionsCurrent The current number of idle connections of the database connection pool instant integer value no
DatabaseConnectionPoolIdleConnectionsMax The maximum number of connections of the database pool that was idle integer value, since the last startup of the component no
DatabaseConnectionPoolMaxActiveSize The maximum number of active connections in the database connection pool instant integer value no
DatabaseConnectionPoolMaxIdleSize The maximum number of idle connections in the database connection pool instant integer value no

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

Defect JMX Notification
A message exchange acceptor thread is dead
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.thread.dead
  • no user data
No more thread is available in the message exchange acceptor thread pool
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.exhausted
  • no user data
No more thread is available to run a message exchange processor
  • type: org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted
  • no user data

Dedicated alerts

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

Defect JMX Notification
No more thread is available for the asynchronous job executor
  • type: org.ow2.petals.se.flowable.engine.async.executor.thread.pool.exhausted
  • no user data
No more connection is available in the database pool
  • type: org.ow2.petals.se.flowable.engine.database.connection.pool.exhausted
  • no user data

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.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.