{section}
{column}

{multi-excerpt-include:Petals-SE-Activiti|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

The version 0.5.0 of the component embeds the BPMN 2.0 engine "Activiti". So, Activiti extensions can be used at the runtime level.

h1. System requirements

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

h1. Using the mode "service"

h2. Creating a service-unit for a process definition

h3. Creating the service contract

The SE Activiti 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 Activiti 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 Activiti is declared using a dedicated binding. The binding "BPMN2" is done adding the element {{\{http://petals.ow2.org/se/bpmn/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 [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 [Associating an operation to the completion of a process instance task|#associating_userTask] for more information on this operation. |

The action is completed with the required attribute *{{actionId}}* that identifies the start event used to create the process instance or the user task to complete in the process definition.

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 {{bpmn:operation}} || Operation executed on the process engine ||
| {{startEvent}} | Expected input parameters are:
* the process identifier,
* the user identifier.
See [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 [Associating an operation to the completion of a process instance task|#associating_userTask] for more information on the declaration of these parameters. |

Variables are identified by the annotation adding the element {{\{http://petals.ow2.org/se/bpmn/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}
<bpmn:variable name="numberOfDays">
/*[local-name()='demande']/*[local-name()='nbJourDde']
</bpmn:variable>
{code}

See operation details to know if variables can be set.
No extra check is done by the SE Activiti 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/bpmn/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/bpmn/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/bpmn/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 the attribute *{{actionId}}*.

This operation accepts variables and requires the following input parameters:
* user identifier, declared using the annotation {{\{http://petals.ow2.org/se/bpmn/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/bpmn/output-params/1.0/special}processInstanceId | String | Identifier of the process instance created |
| \{http://petals.ow2.org/se/bpmn/output-params/1.0/special}userId | String | The user identifier used to create the process instance |
| \{http://petals.ow2.org/se/bpmn/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:bpmn="http://petals.ow2.org/se/bpmn2.0/1.0">
<wsdl:operation name="newOrder" type="...">
<bpmn:operation processDefinitionId="order" action="startEvent" actionId="newOrder"/>
<bpmn:userId>/*[local-name()='newOrderRequest']/*[local-name()='userName']</bpmn:userId>
<bpmn:variable name="address">
/*[local-name()='newOrderRequest']/*[local-name()='address']
</bpmn:variable>
<bpmn:output>newOrderOutput.xsl</bpmn: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/bpmn/annotations/1.0}operation}}. To guarantee that the expected user task is the right one, its identifier is clarified with the attribute *{{actionId}}*.

This operation accepts variables and requires the following input parameters:
* process instance identifier, declared using the annotation {{\{http://petals.ow2.org/se/bpmn/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/bpmn/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/bpmn/output-params/1.0/special}processInstanceId | String | Identifier of the process instance created |
| \{http://petals.ow2.org/se/bpmn/output-params/1.0/special}userId | String | The user identifier used to create the process instance |
| \{http://petals.ow2.org/se/bpmn/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/bpmn/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/bpmn/faults/1.0}processInstanceId
* task identifier: \{http://petals.ow2.org/se/bpmn/faults/1.0}taskId |
| {{ProcessInstanceNotFoundException}} | No active process instance found for the given process instance identifier | process instance identifier: \{http://petals.ow2.org/se/bpmn/faults/1.0}processInstanceId |
| {{UnexpectedUserException}} | The task to complete is assigned to another user identifier | * process instance identifier: {{\{http://petals.ow2.org/se/bpmn/faults/1.0}processInstanceId}}
* task identifier: \{http://petals.ow2.org/se/bpmn/faults/1.0}taskId
* user identifier: \{http://petals.ow2.org/se/bpmn/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:bpmn="http://petals.ow2.org/se/bpmn/annotations/1.0" >
<wsdl:operation name="validOrder">
<bpmn:operation processDefinitionId="order" action="userTask" actionId="validOrder"/>
<bpmn:processId>/*[local-name()='validOrderRequest']/*[local-name()='orderId']</bpmn:processId>
<bpmn:userId>/*[local-name()='validOrderRequest']/*[local-name()='userName']</bpmn:userId>
<bpmn:variable name="validationApproved">
/*[local-name()='validOrderRequest']/*[local-name()='isValidated']
</bpmn:variable>
<bpmn:variable name="creditCardNumber">
/*[local-name()='validOrderRequest']/*[local-name()='creditCardNumber']
</bpmn:variable>
<bpmn:output>validOrderOutput.xsl</bpmn: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}

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:bpmn="http://petals.ow2.org/se/bpmn/annotations/1.0">
<wsdl:operation name="searchOrder" type="...">
<bpmn:operation action="retrieveProcInst" />
<bpmn:input-parameter name="isActive" value="/searchOrderRequest/isInProgress" />
<bpmn:input-parameter name="responsibleUser" value="/searchOrderRequest/responsibleUser" />
<bpmn:input-parameter name="responsibleGroup" value="/searchOrderRequest/responsibleGroup" />
<bpmn:output>searchOrderOutput.xsl</bpmn: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. |

When deploying the service unit on the SE Activiti, the embedded process definition is automatically deployed into the BPMN 2.0 engine, and the associated services are registered.

{note}When a Petals ESB node restarts, all service units previously deployed are redeployed. So if a process definition is already registered in the BPMN 2.0 engine, its registration is skipped without any message.{note}
{tip}To be able to fix a process definition, you must create a new version of the process definition{tip}

h2. Undeploying a service unit

When undeploying a service unit from the SE Activiti, the embedded process definition is deregistered from the BPMN 2.0 engine, and the associated services are unregistered.
{color:red}Que faire si il y a encore de process instances en cours ?{color}

h1. Using the mode "integration"

The mode "integration" provides different services to interact directly with the BPMN 2.0 engine embedded in the SE Activiti. It goes back over the BPMN 2.0 engine API. Available services are:
|| Interface name || Service name || Description ||
| {{ProcessInstances}} | {{ProcessInstancesService}} | To manage process instances |
| {{Task}} | {{TaskService}} | To manage tasks of process instances |

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

h2. The service "ProcessInstanceService"

The service "ProcessInstancesService" provides following operations:
|| Operation name || Description ||
| {{getProcessInstances}} | Query process instances according to the given criteria. |

h3. The operation "getProcessInstances"

The search criteria are given by the following parameters, each criteria operates as a filter:
|| Parameter name || Description || Default value ||
| {{active}} | If "{{true}}", only select process instances which are active, which means that neither the process instance nor the corresponding process definition are suspended | {{true}} |
| {{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 |

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,
* {{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}}.

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. not suspended) | {{true}} |
| {{assignee}} | Only select tasks for which the given user is a candidate. | 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 |

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.

h1. Identity service integration

The Activiti engine requires an entity service 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 entity service implementation, just configure it (the implementation) at component level through the parameters {{engine-identity-service-class-name}} and {{engine-identity-service-config-file}}. By default, the Petals SE Activiti uses a based-file entity service.

Available entity services are:
* file-based entity service where users and groups are stored into files,
* Petals service based entity service invoking Petals services to retrieve users and groups,
* you can also right your own entity service,
* in next versions, new entity services will be added.

h2. File-based entity service

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

h3. Configuration

Parameters of the configuration file of this entity service 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 |

The entity service includes a default configuration used when the entity service configuration file is not set at the component level. This default configuration is inspired of Activiti itself defining users and groups as mentioned as examples below in file formats

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. Petals services based entity service

{color:red}TODO{color}

h2. Right your own entity service

You can right your own entity service. It will be available as a shared library that you will configure to be used by the Petals SE Activiti.

To implement it, just create a class implementing the interface {{org.ow2.petals.activitibpmn.identity.IdentityService}}. You can find an example [here|https://github.com/petalslink/petals-se-activiti/blob/petals-se-activiti-0.5.0/src/main/java/org/ow2/petals/activitibpmn/identity/file/FileIdentityService.java] (the file-based entity service).

h1. 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,
* and *Activiti engine parameters* that are relative to the Activiti engine.

{code:lang=xml}
<jbi:jbi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0"
xmlns:petals-se-activitibpmn="http://petals.ow2.org/components/petals-se-activitibpmn/1.0">

<jbi:component type="service-engine">
<jbi:identification>
<jbi:name>petals-se-activitibpmn</jbi:name>
<jbi:description>Petals SE Activiti</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.activitibpmn.ActivitiSE</jbi:component-class-name>
<jbi:component-class-path>
<jbi:path-element />
</jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.activitibpmn.ActivitiSEBootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path>
<jbi:path-element />
</jbi:bootstrap-class-path>

<!-- CDK specific fields -->
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:acceptor-retry-number />
<petalsCDK:acceptor-retry-wait />
<petalsCDK:acceptor-stop-max-wait />
<petalsCDK:message-processor-max-pool-size />
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:processor-max-pool-size />
<petalsCDK:processor-keep-alive-time />
<petalsCDK:processor-stop-max-wait />
<petalsCDK:time-beetween-async-cleaner-runs />
<petalsCDK:properties-file />
<petalsCDK:jbi-listener-class-name>org.ow2.petals.activitibpmn.incoming.ActivitiJBIListener</petalsCDK:jbi-listener-class-name>

<!-- Component specific configuration -->
<petals-se-activitibpmn:jdbc_driver>org.h2.Driver</petals-se-activitibpmn:jdbc_driver>
<petals-se-activitibpmn:jdbc_url />
<petals-se-activitibpmn:jdbc_username>sa</petals-se-activitibpmn:jdbc_username>
<petals-se-activitibpmn:jdbc_password></petals-se-activitibpmn:jdbc_password>
<petals-se-activitibpmn:jdbc_max_active_connections />
<petals-se-activitibpmn:jdbc_max_idle_connections />
<petals-se-activitibpmn:jdbc_max_checkout_time />
<petals-se-activitibpmn:jdbc_max_wait_time />
<petals-se-activitibpmn:database_type />
<petals-se-activitibpmn:database_schema_update />
<petals-se-activitibpmn:engine-enable-job-executor />
<petals-se-activitibpmn:engine-enable-bpmn-validation />
<petals-se-activitibpmn:engine-identity-service-class-name />
<petals-se-activitibpmn:engine-identity-service-config-file />

</jbi:component>
</jbi:jbi>
{code}

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

{include:0 CDK Component Configuration Table 5.4.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}

h2. Component specific parameters

These parameters drive features proposed by the component and configure the Activiti engine "Activiti 5.18.0-PETALS-0" embedded in the SE:
* activation of the mode 'integration',
* Activiti 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 Activiti highly available,
** asynchronous job executor activiation,
** BPMN validation,
** identity service to use.


{center}*Configuration of the component, Specific parameter part, Database*{center}
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| 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:activiti;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}Runtime{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}Runtime{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}Runtime{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}Runtime{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 Activiti 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 Activiti job executor. See [Activiti job executor configuration|#job_executor] | {center}true{center} | {center}No{center} | {center}Installation{center} |
| engine-enable-bpmn-validation | Enable or disable the BPMN validation of processes to deploy into the Activiti engine | {center}true{center} | {center}No{center} | {center}Installation{center} |
| engine-identity-service-class-name | Class name of the entity service to use. | {center}{{org.ow2.petals.activitibpmn.identity.file.FileIdentityService}}{center} | {center}No{center} | {center}Installation{center} |
| engine-identity-service-config-file | Configuration file of the entity service used. | {center}The default configuration of the entity service is service dependent. See documentation of the entity service{center} | {center}No{center} | {center}Installation{center} |

{anchor:job_executor}
h3. Activiti job executor configuration

Activiti 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 Activiti running with the same database, you can disable the job executor on some Petals SE Activiti. Or even, you can specialized a Petals SE Activiti to process all asynchronous tasks enabling the job executor on only one Petals SE Activiti.

h1. Business monitoring

MONIT traces are logged to each step of the BPMN process interacting with Petals ESB:
* when creating process instances,
* when completing user tasks,
* when executing service task implemented through Petals services,
* when terminating process instances.

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.

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

h1. Logging

The traces of the BPMN 2.0 engine "Activiti" are activated through the logging configuration file of Petals ESB. The root logger for Activiti is {{org.activiti}}:
{code}
...
org.activiti.level=INFO
org.activiti.engine.impl.level=FINE
...
{code}

h1. Monitoring the component

{warning}In this documentation, the term "Allocated threads" must be understood as "Active threads", see [PETALSDISTRIB-37|https://jira.petalslink.com/browse/PETALSDISTRIB-37]. This naming error will be fixed in the next version.{warning}

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:0 CDK Component Monitoring Metrics 5.4.0}

h3. Dedicated metrics

No dedicated metric is available.

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:0 CDK Component Monitoring Alerts 5.4.0}

h3. Dedicated alerts

No dedicated alert is available.

{anchor:Unit_Testing}
h1. Unit testing

The unit testing can occur at several levels in your Activiti 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.

h2. Checking the compliance of the WSDL

The unit test framework contains an assertion '{{assertIsCompliant}}' to verify easily the compliance of your WSDL with the attendees of the mode 'service':
{code:lang=java}
import static org.junit.Assert.assertNotNull;
import static org.ow2.petals.se.bpmn2.unittest.Assert.assertIsCompliant;

import java.io.InputStream;

import org.junit.Test;

public class WSDLComplianceTest {

@Test
public void testWSDLCompliance() {
final InputStream isWsdl = Thread.currentThread().getContextClassLoader()
.getResourceAsStream("myService.wsdl");
assertNotNull("WSDL not found as resource !", isWsdl);
assertIsCompliant("WSDL not compliant with SE Activiti attendes !", isWsdl);
}

}
{code}

h2. Unit-testing your XSLs

{color:red}*TODO*{color}

h2. Unit-testing your process definition

Activiti 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 Activiti JUnit framework but how to integrate it into a service unit project.

First, you must embedd an Activiti 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:
{code}
<dependency>
<groupId>org.ow2.petals.activiti</groupId>
<artifactId>activiti-engine</artifactId>
<version>5.18.0-PETALS-0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>1.4.178</version>
<scope>test</scope>
</dependency>
{code}
{tip}Caution to use the same version of the Activiti engine as the one embedded into the Petals SE Activiti{tip}

Next, your database must be linked to the Activiti engine through a Spring configuration located into the file {{src/test/resources/activiti.cfg.xml}} containing something like:
{code}
<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.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration">
<property name="jdbcUrl" value="jdbc:h2:mem:activiti;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 Activiti JUnit framework:
{code}
public class ProcessDeploymentTest {

@Rule
public final ActivitiRule activitiRule = new ActivitiRule();

@Test
@Deployment(resources = {"jbi/vacationRequest.bpmn20.xml"})
public void theProcessIsDeployableAndInstanciable() {
final ProcessDefinition processDefinition = this.activitiRule.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.activitiRule.getRuntimeService().startProcessInstanceByKey("vacationRequest", variables);
assertNotNull(processInstance);
}
}
{code}

If your process definition includes Petals service invocations, you must use mock for these services. For this first version of the Petals SE Activiti, nothing is available to create these mocks and you will get the following stack trace in log about the service invocation:
{code}
22 mai 2015 17:15:31 org.activiti.engine.impl.webservice.WSOperation safeSend
ATTENTION: Error calling WS http://petals.ow2.org/samples/se-bpmn/notifyVacationService:notifyVacationService
java.lang.RuntimeException: Could not find conduit initiator for address: petals:///{http://petals.ow2.org/samples/se-bpmn/notifyVacationService}notifyVacation and transport: http://schemas.xmlsoap.org/soap/http
at org.apache.cxf.binding.soap.SoapTransportFactory.getConduit(SoapTransportFactory.java:225)
at org.apache.cxf.binding.soap.SoapTransportFactory.getConduit(SoapTransportFactory.java:234)
at org.apache.cxf.endpoint.AbstractConduitSelector.getSelectedConduit(AbstractConduitSelector.java:103)
at org.apache.cxf.endpoint.UpfrontConduitSelector.prepare(UpfrontConduitSelector.java:63)
at org.apache.cxf.endpoint.ClientImpl.prepareConduitSelector(ClientImpl.java:896)
at org.apache.cxf.endpoint.ClientImpl.doInvoke(ClientImpl.java:565)
at org.apache.cxf.endpoint.ClientImpl.invoke(ClientImpl.java:479)
at org.apache.cxf.endpoint.ClientImpl.invoke(ClientImpl.java:382)
at org.apache.cxf.endpoint.ClientImpl.invoke(ClientImpl.java:335)
at org.apache.cxf.endpoint.ClientImpl.invoke(ClientImpl.java:355)
at org.apache.cxf.endpoint.ClientImpl.invoke(ClientImpl.java:341)
at org.activiti.engine.impl.webservice.CxfWebServiceClient.send(CxfWebServiceClient.java:38)
at org.activiti.engine.impl.webservice.WSOperation.safeSend(WSOperation.java:74)
at org.activiti.engine.impl.webservice.WSOperation.sendFor(WSOperation.java:62)
at org.activiti.engine.impl.bpmn.webservice.Operation.sendMessage(Operation.java:50)
at org.activiti.engine.impl.bpmn.behavior.WebServiceActivityBehavior.execute(WebServiceActivityBehavior.java:75)
at org.activiti.engine.impl.pvm.runtime.AtomicOperationActivityExecute.execute(AtomicOperationActivityExecute.java:60)
...
{code}

h1. Annex: Sample WSDL

h2. Abstract part:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:tns="http://petals.ow2.org/se/bpmn2/sample/order"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://petals.ow2.org/se/bpmn2/sample/order">

<!-- Type definitions for input and output parameters for service -->
<wsdl:types>
<xs:schema targetNamespace="http://petals.ow2.org/se/bpmn2/sample/order">
<xs:complexType name="ItemType">
<xs:sequence>
<xs:element name="reference" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="quantity" type="xs:int" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
<xs:element name="newOrderRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="customerName" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="address" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="items">
<xs:complexType>
<xs:sequence>
<xs:element name="item" type="tns:ItemType"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="newOrderResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="orderId" type="xs:string" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="validOrderRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="orderId" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="validationStepId" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="isValidated" type="xs:boolean" minOccurs="1" maxOccurs="1" />
<xs:element name="creditCardNumber" type="xs:string" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="validOrderResponse" type="xs:string" />

<xs:element name="searchOrderRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="orderId" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="isInProgress" type="xs:boolean" minOccurs="0" maxOccurs="1" />
<xs:element name="responsibleUser" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="responsibleGroup" type="xs:string" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="searchOrderResponse" type="xs:string" />
</xs:schema>

<xs:element name="orderUnknownFault">
<xs:complexType>
<xs:sequence>
<xs:element name="orderId" type="xs:string" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="orderAlreadyValidated">
<xs:complexType>
<xs:sequence>
<xs:element name="orderId" type="xs:string" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</wsdl:types>

<!-- Message definitions for input and output -->
<wsdl:message name="newOrderRequest">
<wsdl:part name="newOrderRequest" element="tns:newOrderRequest" />
</wsdl:message>
<wsdl:message name="newOrderResponse">
<wsdl:part name="newOrderResponse" element="tns:newOrderResponse" />
</wsdl:message>
<wsdl:message name="validOrderRequest">
<wsdl:part name="validOrderRequest" element="tns:validOrderRequest" />
</wsdl:message>
<wsdl:message name="validOrderResponse">
<wsdl:part name="validOrderResponse" element="tns:validOrderResponse" />
</wsdl:message>
<wsdl:message name="searchOrderRequest">
<wsdl:part name="searchOrderRequest" element="tns:validOrderRequest" />
</wsdl:message>
<wsdl:message name="searchOrderResponse">
<wsdl:part name="searchOrderResponse" element="tns:searchOrderResponse" />
</wsdl:message>
<wsdl:message name="orderUnknown">
<wsdl:part name="orderUnknown" element="tns:orderUnknownFault" />
</wsdl:message>
<wsdl:message name="orderAlreadyValidated">
<wsdl:part name="orderAlreadyValidated" element="tns:orderAlreadyValidated" />
</wsdl:message>

<!-- Port (interface) definitions -->
<wsdl:portType name="Order">
<wsdl:operation name="newOrder">
<wsdl:input message="tns:newOrderRequest" />
<wsdl:output message="tns:newOrderResponse" />
</wsdl:operation>
<wsdl:operation name="validOrder">
<wsdl:input message="tns:validOrderRequest" />
<wsdl:output message="tns:validOrderResponse" />
<wsdl:fault message="tns:orderUnknown" name="orderUnknown"/>
<wsdl:fault message="tns:orderAlreadyValidated" name="orderAlreadyValidated"/>
</wsdl:operation>
<wsdl:operation name="searchOrder">
<wsdl:input message="tns:searchOrderRequest" />
<wsdl:output message="tns:searchOrderResponse" />
</wsdl:operation>
</wsdl:portType>

</wsdl:definitions>
{code}

h2. Implementation part

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:tns="http://petals.ow2.org/se/bpmn2/sample/order"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:bpmn="http://petals.ow2.org/se/bpmn2/1.0" targetNamespace="http://petals.ow2.org/se/bpmn2/sample/order">

<wsdl:import location="OrderAbstract.wsdl"
namespace="http://petals.ow2.org/se/bpmn2/sample/order" />

<!-- Port bindings to SE Activiti -->
<wsdl:binding name="OrderBinding" type="tns:Order">
<wsdl:operation name="newOrder">
<bpmn:operation processDefinitionId="order" action="startEvent" actionId="newOrder"/>
<bpmn:userId>/*[local-name()='newOrderRequest']/*[local-name()='userName']</bpmn:userId>
<bpmn:variable name="customerName">
/*[local-name()='newOrderRequest']/*[local-name()='customerName']
</bpmn:variable>
<bpmn:variable name="address">
/*[local-name()='newOrderRequest']/*[local-name()='address']
</bpmn:variable>
<bpmn:output>newOrderOutput.xsl</bpmn:output>
<wsdl:input />
<wsdl:output />
</wsdl:operation>
<wsdl:operation name="validOrder">
<bpmn:operation processDefinitionId="order" action="userTask" actionId="validOrder"/>
<bpmn:processId>/*[local-name()='validOrderRequest']/*[local-name()='orderId']</bpmn:processId>
<bpmn:userId>/*[local-name()='validOrderRequest']/*[local-name()='userName']</bpmn:userId>
<bpmn:variable name="validationApproved">
/*[local-name()='validOrderRequest']/*[local-name()='isValidated']
</bpmn:variable>
<bpmn:variable name="creditCardNumber">
/*[local-name()='validOrderRequest']/*[local-name()='creditCardNumber']
</bpmn:variable>
<bpmn:output>validOrderOutput.xsl</bpmn: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:operation name="searchOrder">
<bpmn:operation action="retrieveProcInst" />
<bpmn:input-parameter name="processInstanceId" value="/searchOrderRequest/orderId" />
<bpmn:input-parameter name="isActive" value="/searchOrderRequest/isInProgress" />
<bpmn:input-parameter name="responsibleUser" value="/searchOrderRequest/responsibleUser" />
<bpmn:input-parameter name="responsibleGroup" value="/searchOrderRequest/responsibleGroup" />
<bpmn:output>searchOrderOutput.xsl</bpmn:output>
<wsdl:input />
<wsdl:output />
</wsdl:operation>
</wsdl:binding>

</wsdl:definitions>
{code}