{section}
{column}

{warning}This version must be installed on [Petals ESB 5.3.0|petalsesb530:Petals ESB 5.3.0]+{warning}

{multi-excerpt-include:petalscomponents:Petals-SE-Flowable|name=features|nopanel=true}

{column}

{column:width=40%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Introduction

This version of the component is based on:
* [Flowable|https://www.flowable.org/] v6.4.2 as embedded BPMN engine. Flowable extensions can be used at the runtime level,
* [Eclipse Jetty|http://www.eclipse.org/jetty/] v9.4.11.v20180605 as HTTP server for Flowable REST API.

h1. System requirements

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

h1. Using the mode "service"

h2. About deployment/undeployment

h3. Deployment

A service unit embeds process definition(s). So when deploying a service unit, its process definition(s) are automatically deployed, and the associated consumer services are registered.

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}}'.

Next, if you redeploy the service unit, the embedded process definition(s) will not be redeployed because the process definition is already deployed for the given version. 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 association version.

According to changes into your process definition, it can be required to create new version of your associated service providers:
* if your changes concern all BPMN object except service task, you can undeploy your service unit and next you can deploy new version of your service unit including the new version of your process definition. Process instances started before the deployment continue to work fine because all service consumers can be resolved against your new service unit (service consumers are the same),
* if your changes include changes about service tasks, it will be needed to create new version of your service providers. All process instances in progress require to keep deployed your initial service unit to correctly invoke services. Your new process definition will be deployed with its own service unit. So we will have two service units deployed concurrently, so:
** names of service provider associated to service unit must be different,
** and service unit names must be different to be abler to deploy them on the same Petals ESB containe.

{note}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.{note}

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.

h3. Undeployment

A version of a process definition can be undeployed only if no more associated process instance exists, in progress or ended. If process instances exist, they must be purged before process definition undeployment.

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

h2. Creating a service-unit for a process definition

h3. 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.

{tip}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|#Unit_Testing]".{tip}

h4. 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|#associating_startEvent] for more information on this operation. |
| {{userTask}} | Complete a user task. See [petalscomponents:Associating an operation to the completion of a process instance task|#associating_userTask] for more information on this operation. |
| {{intermediateMessageCatch}} | Catches an intermediate message. See [petalscomponents:Associating an operation to the catching of an intermediate message|#associating_intermediateMessageCatchEvent] 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. |

h4. 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|#associating_startEvent] 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|#associating_userTask] 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|#associating_intermediateMessageCatchEvent] 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.

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

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.

{color:red}*TODO. Les types ?; les arborescences*{color}

h4. 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.

{tip}For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "[Unit testing|#Unit_Testing]".{tip}

h4. 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.

{tip}For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "[Unit testing|#Unit_Testing]".{tip}

{anchor:associating_startEvent}
h4. 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.

{code:title=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>
{code}

{code:title=Associated input request}
<newOrderRequest>
<userName>Jean Zé</userName>
<customerName>Mr Dupont Martin</customerName>
<address>23, rue de la Paie, 75000 Paris</address>
</newOrderRequest>
{code}

{code:title=Associated output request}
<newOrderResponse>
<orderNumber>12345</orderNumber>
</newOrderResponse>
{code}

{anchor:associating_userTask}
h4. 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 | * process instance identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}processInstanceId
* task identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}taskId |
| {{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 | * process instance identifier: {{\{http://petals.ow2.org/se/flowable/faults/1.0}processInstanceId}}
* task identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}taskId
* user identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}userId |

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

{code:title=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>
{code}

{code:title=Associated input request}
<validOrderRequest>
<orderId>12345</orderId>
<isValidated>true</isValidated>
<creditCardNumber>1234567890123</customerName>
<userName>Robert Té</userName>
</validOrderRequest>
{code}

{code:title=Associated output request}
<validOrderResponse />
{code}

{anchor:associating_intermediateMessageCatchEvent}
h4. 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}}':
{code:xml}
<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>
{code}

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 active process instance found for the given process instance identifier | 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 | * process instance identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}processInstanceId
* message name: \{http://petals.ow2.org/se/flowable/faults/1.0}messageName |
| {{MessageEventReceivedException}} | The intermediate message event has already been caught on BPMN engine side | * process instance identifier: \{http://petals.ow2.org/se/flowable/faults/1.0}processInstanceId
* message name: \{http://petals.ow2.org/se/flowable/faults/1.0}messageName |

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.

{code:title=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>
{code}

{code:title=Associated input request}
<paymentReceivedRequest>
<orderId>12345</orderId>
<checkNumber>1234567890123</checkNumber>
</paymentReceivedRequest>
{code}

h4. Associating an operation to retrieve process instances

The operation retrieving process instances is identified by the value *{{retrieveProcInst}}* set on the attribute {{action}}:
{code}
<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>
{code}

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 | {color:red}Quel type 'list' est exploitable coté XSL{color} | 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.

h3. 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}}':
{code}
<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>
{code}

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

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:
{code}
<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>
{code}

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.

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

{include:petalscomponents:0 CDK SU Provide Configuration 5.7.0}

{center}{*}Configuration of a Service Unit to provide business process services*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}

|| Parameter || Description || Default || Required ||
| tenant_id | Tenant identifier. As the [multitenancy is supported|http://www.flowable.org/docs/userguide/index.html#advanced.tenancy], 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 |
{table-plus}

h1. 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:
# [petalscomponents:import the service contract of the Petals service provider into your service-unit project|#importing-service-contract],
# [petalscomponents:define the Petals service provider address|#defining-service-provider],
# [petalscomponents:create the associated service task|#creating-service-task],
# [petalscomponents:configure the associated service consumer|#configuring-service-consumer].

{anchor:importing-service-contract}
h2. 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}}.

!import-wsdl-in-su-project.png!

{anchor:defining-service-provider}
h2. 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:
{code:xml}
<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>
{code}

{anchor:creating-service-task}
h2. 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:
# First, import the Petals service provider contract into the Flowable process definition:
{code:xml}
<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>
{code}
# 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):
{code:xml}
<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>
{code}
# The service to call is referenced through the definition of a BPMN interface:
{code:xml}
<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>
{code}
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.
# Next, define mapping of the service request and the service reply
{code:xml}
<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>
{code}

{tip}
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.
{tip}
{tip}
More information about the syntax of expression used in data associations can be found in: [The Java EE 6 Tutorial|http://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html].
{tip}

{anchor:configuring-service-consumer}
h2. 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.

These configurations take place into the JBI desciptor of your Flowable service unit:
{code:xml}
<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>
{code}

If no service consumer configuration is found into the SU JBI descriptor for the invoked operation, the following default parameters are used:
* 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}
_*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:
!long-service-provider-invocation.png!
{note}

h1. 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 |

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

h2. The service "UserService"

The service "UserService" provides following operations:
|| Operation name || Description ||
| {{get}} | Get information about a user. |
| {{search}} | Search users according to criteria. |

h3. The operation "get"

|| Parameter name || Description || Default value ||
| {{id}} | User id. | No default value |

{tip}If no parameter is given, all users are returned.{tip}

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.

h3. The operation "search"

|| Parameter name || Description || Default value ||
| {{group-id}} | Group id for which users returned must be member of. | No default value |

{tip}If no parameter is given, all groups are returned.{tip}

The operation returns identifier of users matching the given criteria.

h2. The service "GroupService"

The service "GroupService" provides following operations:
|| Operation name || Description ||
| {{search}} | Search groups according to criteria. |

h3. 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.

h2. 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. |

h3. 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}}.

h3. 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.

h3. 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.

h2. The service "ExecutionsService"

The service "ExecutionsService" provides following operations:
|| Operation name || Description ||
| {{getExecutions}} | Query executions according to the given criteria. |

h3. 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.

h2. The service "TaskService"

The service "TaskService" provides following operations:
|| Operation name || Description ||
| getTasks | Query tasks according to the given criteria |

h3. 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}}.

h1. 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.

h2. 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.

h3. 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.

h3. File formats

The user file is defined as following:
{code}
#
# Property format:
# <user-id> = <user-password>
#
kermit = kermit
fozzie = fozzie
gonzo = gonzo
{code}

The group file is defined as following:
{code}
#
# 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
{code}

h2. LDAP-based IDM engine

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

h3. 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.

h2. Petals services based IDM engine

{color:red}TODO{color}

h2. 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|https://github.com/petalslink/petals-se-flowable/blob/master/src/main/java/org/ow2/petals/flowable/identity/file/FileIdmEngineConfigurator.java] (the file-based IDM engine), or [here|https://github.com/petalslink/petals-se-flowable/blob/master/src/main/java/org/ow2/petals/flowable/identity/ldap/LdapIdmEngineConfigurator.java] (the LDAP-based IDM engine).

h1. Configuring the component

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

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,

| integration-mode-enable | Enable the mode 'Integration' | {center}true{center} | {center}No{center} | {center}Installation{center} |
| jdbc_url | URL of the database. The default database is an in-memory database | {center}jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc_driver | JDBC driver. Except for the default JDBC driver, it *must* be provided as shared-library. | {center}org.h2.Driver{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc_username | Username used for the database connection. | {center}sa{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc_password | Passwrd used for the database connection. | {center}""{center} | {center}Yes{center} | {center}Installation{center} |
| jdbc_max_active_connections | The number of idle connections that the database connection pool at maximum at any time can contain. | {center}10{center} | {center}No{center} | {center}Installation{center} |
| jdbc_max_idle_connections | The number of active connections that the database connection pool at maximum at any time can contain. | {center}-{center} | {center}No{center} | {center}Installation{center} |
| 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. | {center}20000 (20 seconds){center} | {center}No{center} | {center}Installation{center} |
| 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). | {center}20000 (20 seconds){center} | {center}No{center} | {center}Installation{center} |
| 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}}. | {center}-{center} | {center}No{center} | {center}Installation{center} |
| 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. | {center}true{center} | {center}No{center} | {center}Installation{center} |
| engine-enable-job-executor | Enable or disable the Flowable job executor. See [petalscomponents:Enabling/disabling the Flowable job executor|#job_executor] | {center}true{center} | {center}No{center} | {center}Installation{center} |
| 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. | {center}2{center} | {center}No{center} | {center}Installation{center} |
| 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. | {center}10{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-keep-alive-time | The time, in milliseconds, a thread used for job execution must be kept alive before it is destroyed. | {center}5000{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-queue-size | The size of the queue on which jobs to be executed are placed. | {center}100{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-max-timer-jobs-per-acquisition | The number of timer jobs that are fetched from the database in one query. | {center}1{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-max-async-jobs-due-per-acquisition | The number of asynchronous jobs due that are fetched from the database in one query. | {center}1{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-async-job-acquire-wait-time | The time, in milliseconds, between asynchronous job due queries being executed. | {center}10000{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-timer-job-acquire-wait-time | The time in milliseconds between timer job queries being executed. | {center}10000{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-timer-lock-time | The time, in milliseconds, that a timer job is locked before being retried again. | {center}300000{center} | {center}No{center} | {center}Installation{center} |
| engine-job-executor-async-job-lock-time | The time in milliseconds that an asynchronous job is locked before being retried again. | {center}300000{center} | {center}No{center} | {center}Installation{center} |
| engine-enable-bpmn-validation | Enable or disable the BPMN validation of processes to deploy into the Flowable engine | {center}true{center} | {center}No{center} | {center}Installation{center} |
| engine-default-failed-job-wait-time | The default wait time for a failed job, in seconds | {center}10{center} | {center}No{center} | {center}Installation{center} |
| engine-async-failed-job-wait-time | The default wait time for a async failed job, in seconds | {center}10{center} | {center}No{center} | {center}Installation{center} |
| idm-engine-configurator-class-name | Class name of the identity service to use. | {center}{{org.ow2.petals.flowable.identity.file.FileIdmEngineConfigurator}}{center} | {center}No{center} | {center}Installation{center} |
| idm-engine-configurator-config-file | Configuration file of the identity service used. | {center}The default configuration of the identity service is service dependent. See documentation of the identity service{center} | {center}No{center} | {center}Installation{center} |
| 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}} | {center}true{center} | {center}No{center} | {center}Installation{center} |
| engine-rest-api-port | Listenning port of the REST API of the Flowable engine. | {center}8089{center} | {center}No{center} | {center}Installation{center} |
| 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}}' | {center}0.0.0.0{center} | {center}No{center} | {center}Installation{center} |
| 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}}'| {center}rest-access-api{center} | {center}No{center} | {center}Installation{center} |

{anchor:job_executor}
h3. 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.

h2. 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:
{code:xml}
<intermediateCatchEvent id="waitBeforeGetStatus" name="Wait">
<timerEventDefinition>
<timeDuration>${empty execution.variableInstances.petalsPlaceholders.getValue().signaturePeriod ? "PT1H" : execution.variableInstances.petalsPlaceholders.getValue().signaturePeriod}</timeDuration>
</timerEventDefinition>
</intermediateCatchEvent>
{code}

{note}The dedicated map variable is automatically copied to be accessible as variable of sub-processes.{note}

h1. 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):
{gliffy:name=MONIT trace correlations|size=M|version=6}
* on process instance creation, we have the following MONIT traces ordered:
## 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.
## 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.
## 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:
## 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.
## 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.
## 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:
## 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
## 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.
## 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.
## 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:
## 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.

h2. Flow tracing activation

{include:petalscomponents:0 CDK SE Business Monitoring Flow Tracing Activation 5.8.0}

h2. 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.

h1. 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}}:
{code}
...
org.activiti.level=INFO
org.activiti.engine.impl.level=FINE
...
{code}

h1. Monitoring the component

h2. 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.

h3. Common metrics

{include:petalscomponents:0 CDK Component Monitoring Metrics 5.8.0}

h3. 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 |

h2. 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.

{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}

h3. Common alerts

{include:petalscomponents:0 CDK Component Monitoring Alerts 5.6.0}

h3. 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 |

{anchor:Unit_Testing}
h1. 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}}:
{code:xml}
<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>
{code}

h2. 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':
{code:lang=java}
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") });
}

}
{code}

See the Javadoc for more details on parameters.

h2. Unit-testing your XSLs

The unit test framework contains an assertion '{{assertXslTransformation}}' to verify easily the result of your XSL transformations:
{code:lang=java}
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);
}

}
{code}

See the Javadoc for more details on parameters.

h2. 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|http://docs.alfresco.com/activiti/topics/apiUnitTesting.html].
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:
{code:xml}
<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>
{code}
{tip}Caution to use the same version of the Flowable engine as the one embedded into the Petals SE Flowable{tip}

Next, your database must be linked to the Flowable engine through a Spring configuration located into the file {{src/test/resources/flowable.cfg.xml}} containing something like:
{code:xml}
<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">
<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="" />
</bean>
</beans>
{code}

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:
{code:java}
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);
}
}
{code}

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:
{code:xml}
<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>
{code}

and SoapUI mock services can be automatically started at Maven level with following declaration in the POM file of the service unit:
{code:xml}
<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>
{code}
where SoapUI project files contains mock service definitions.