FeaturesThe component SE Activiti includes a BPMN 2.0 engine and provides two operational mode:
Integration modeThe mode "Integration" of the SE Activiti permits to interact directly with the BPMN 2.0 engine (Activiti) through a service-based API. Several services are provided by the component to interact directly with the BPMN 2.0 engine. This mode is activated at the component level. Concurrency Several instance of the component can be deployed concurrently on Petals ESB. A sequence of service-based API invocations can be exploded on each component instances Service modeThe mode "Service" of the SE Activiti permits to implement your services using orchestration and/or process capabilities of BPMN 2.0. This mode is available through the deployment of a service unit including the process definition. Orchestration An orchestration is sequence of automatic service invocations, and can be modeled as a sequence of service tasks in a BPMN2 description. Creating an instance of such a process will start automatically the sequence of service invocations. With BPMN2 it is possible to implement your orchestration as a process containing only service tasks. For example, the following orchestration can be an implementation of a service processing a "New Order": Process A process or workflow can be "servicized" at different levels:
For example, the previous sample can be reworked replacing two service tasks by human tasks with such a process:
Concurrency Several instance of the component can be deployed concurrently on Petals ESB. So, you are able to deploy each process definitions on several component instances to get high availability. |
Table of contents
Contributors
No contributors found for: authors on selected page(s)
|
Introduction
The version 1.1.0+ of the component embeds the BPMN 2.0 engine "Activiti" v5.22.0-PETALS-0 (official v5.22.0 completed with few contributions of Petals team). So, Activiti extensions can be used at the runtime level.
System requirements
The Petals SE Activiti MUST be deployed on a container running with a Java Development Kit (JDK), not a Java Runtime Environment !!
Using the mode "service"
Creating a service-unit for a process definition
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.
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". |
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 for more information on this operation. |
userTask | Complete a user task. See Associating an operation to the completion of a process instance task 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:
|
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. |
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:
|
userTask | Expected input parameters are:
|
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.
<bpmn:variable name="numberOfDays">
/*[local-name()='demande']/*[local-name()='nbJourDde']
</bpmn:variable>
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.
TODO. Les types ?; les arborescences
Identifying output parameters of operations
Output parameters of the BPMN 2.0 engine API operation can not be mapped to the output reply of the service operation using a simple XPath expression as for input parameters. An XSL style-sheet is required to generated the full output reply. It is identified using the annotation adding the element {http://petals.ow2.org/se/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.
For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "Unit testing". |
Identifying faults of operations
When an error occurs on the BPMN engine side, this error can be returned as business fault or technical error. The business faults are declared into the WSDL of the service.
The mapping of an error of the BPMN engine to a business fault is defined using the annotation {http://petals.ow2.org/se/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.
For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "Unit testing". |
Associating an operation to the creation of an process instance
The operation creating instances of process definition is identified by the value startEvent set on the attribute action of the annotation {http://petals.ow2.org/se/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 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/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.
<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" start-event-message-name="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>
<newOrderRequest> <userName>Jean Zé</userName> <customerName>Mr Dupont Martin</customerName> <address>23, rue de la Paie, 75000 Paris</address> </newOrderRequest>
<newOrderResponse> <orderNumber>12345</orderNumber> </newOrderResponse>
Associating an operation to the completion of a process instance task
The operation completing a task of a process instance is identified by the value userTask set on the attribute action of the annotation {http://petals.ow2.org/se/bpmn/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/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 |
|
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 |
|
A such operation is defined for each task of the process definition to complete. C'est le cas d'un service par tache à terminer. Essayer de mieux expliquer..
<wsdl:binding name="Order" xmlns:bpmn="http://petals.ow2.org/se/bpmn/annotations/1.0" > <wsdl:operation name="validOrder"> <bpmn:operation processDefinitionId="order" action="userTask" user-task-id="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>
<validOrderRequest>
<orderId>12345</orderId>
<isValidated>true</isValidated>
<creditCardNumber>1234567890123</customerName>
<userName>Robert Té</userName>
</validOrderRequest>
<validOrderResponse />
Associating an operation to retrieve process instances
The operation retrieving process instances is identified by the value retrieveProcInst set on the attribute action:
<wsdl:binding name="Order" xmlns: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>
This operation requires the following input parameters:
Input parameter name | Type | Description | Required |
---|---|---|---|
isActive | Boolean | Only active task are returned. | No |
responsibleUser | String | Only select tasks for which the given user is a candidate are returned. | No |
responsibleGroup | String | Only select tasks for which users in the given group are candidates are returned. | No |
It does not use variables.
The process instances returned by the component are all associated to the current process definition (the process definition packaged in the service unit).
The XSL parameters available to generate the service output reply are:
XSL parameter name | Type | Description |
---|---|---|
processInstances | Quel type 'list' est exploitable coté XSL | The list of process instance identifier matching criteria. |
It is possible to map several operations of the WSDL to search process instance, for example with different search criteria.
Creating the service unit
All services provided by a business process are defined into the JBI descriptor of a service unit as a section 'provides':
<jbi:provides interface-name="process:vacation" service-name="process:vacationService" endpoint-name="autogenerate"> <petalsCDK:wsdl>vacationService.wsdl</petalsCDK:wsdl> <petals-se-activitibpmn:tenant_id>my-tenant</petals-se-activitibpmn:tenant_id> <petals-se-activitibpmn:category_id>samples</petals-se-activitibpmn:category_id> <petals-se-activitibpmn:process_file1>vacationRequest.bpmn20.xml</petals-se-activitibpmn:process_file1> <petals-se-activitibpmn:version1>1</petals-se-activitibpmn:version1> </jbi:provides>
Only one section 'provides' is accepted by the Petals SE Activiti. |
If your business process includes service tasks to invoke service providers, you can add a section 'consumes' for each one to drive more precisely the invocation:
<jbi:provides ...> ... <petals-se-activitibpmn:process_file1>vacationRequest.bpmn20.xml</petals-se-activitibpmn:process_file1> <petals-se-activitibpmn:version1>1</petals-se-activitibpmn:version1> </jbi:provides> <jbi:consumes interface-name="archiveService:archive" service-name="archiveService:archiveService"> <petalsCDK:timeout>15000</petalsCDK:timeout> </jbi:consumes>
Supported parameters of the section 'consumes' are:
- timeout, to set on the message exchange used for the service provider invocation,
- mep, that define the message exchange pattern to use. If not set, the pattern InOut will be used as default,
- operation, is not used because the operation to invoke is already define into the process definition. A warning will appear in log traces if this field is set.
- exchange-properties, the properties to set on the message exchange used to invoke the service provider,
- message-properties, the properties to set on the message of message exchange used to invoke the service provider.
If you want specify a specific endpoint to invoke a service provider, just define it in the section 'consume':
<jbi:consumes interface-name="archiveService:archive" service-name="archiveService:archiveService" endpoint-name="mySpecificEndpointName"> <petalsCDK:timeout>15000</petalsCDK:timeout> </jbi:consumes> |
Parameter | Description |
Default |
Required |
---|---|---|---|
provides | Describe the JBI service that will be exposed into the JBI bus. Interface (QName), Service (QName) and Endpoint (String) attributes are required. | - | Yes |
Parameter | Description | Default | Required |
---|---|---|---|
tenant_id | Tenant identifier. As the multitenancy is supported], such an identifier is required. | myTenant | No |
category_id | Deployment category identifier. For example to group business processes. | myCategory | No |
process_file | Name of the process definition file into the service unit (relative to the root of the service unit). To deploy several process definition files use process_file<X> where <X> is a number starting to 1. process_file<X> must have its own version<X>. |
Yes | |
version | Version of the process definition. | Yes |
Deploying a service unit
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.
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. |
To be able to fix a process definition, you must create a new version of the process definition |
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.
Que faire si il y a encore de process instances en cours ?
Invoking Petals service providers from Activiti process
The Petals service providers can be invoked natively from Activiti process using a 'ServiceTask' into your process definition through three steps:
- import the service contract of the Petals service provider into your service-unit project,
- define the Petals service provider address,
- create the associated service task.
Importing the service contract of the Petals service provider
The service contract of the Petals service provider (ie. its WSDL file) must be added to the service unit project. We recommend you to import the WSDL file in the same directory than the process definition file (ie. src/main/resources/jbi.
Defining the Petals service provider address
The address of the Petals service provider (ie. interface name, service name and/or endpoint) must be defined into the service contract previously imported, as a basic service endpoint in XML tag '/wsdl:service/wsdl:port/soap:address/@location'. The address is defined with an URL matching the following pattern: petals:///interfacename[:servicename[:endpointname]].
Example:
<wsdl:definitions ...> ... <wsdl:service name="notifyVacationService"> <wsdl:port name="autogenerate" binding="notifyService:notifyVacationBinding"> <soap:address location="petals:///{http://petals.ow2.org/samples/se-bpmn/notifyVacationService}notifyVacation" /> </wsdl:port> </wsdl:service> </wsdl:definitions>
Creating the associated service task
Once a 'ServiceTask' has been added to your process, you will configure it as following to invoke the right Petals service provider:
- First, import the Petals service provider contract into the Activiti process definition:
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...> <import location="CommunicationService.wsdl" namespace="http://org.ow2.petals.samples.rld.service.technical.communication/1.0/" importType="http://schemas.xmlsoap.org/wsdl/" /> <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true"> ... </process> </definitions>
- Next, at your service task level, select the service task implementation '##WebService' and identify the reference of the service to call (ie. the operation of a web-service):
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...> ... <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true"> ... <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager" implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp"> ... </serviceTask> ... </process> </definitions>
- The service to call is referenced through the definition of a BPMN interface:
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...> ... <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true"> ... <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager" implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp"> ... </serviceTask> <interface name="User base service" implementationRef="userbaseService:userBase"> <operation id="getHumanResourceManagerOp" name="Get HR manager" implementationRef="userbaseService:humanResourceManager"> <inMessageRef>rldProcess:getHumanResourceManagerRequestMessage</inMessageRef> <outMessageRef>rldProcess:getHumanResourceManagerResponseMessage</outMessageRef> </operation> </interface> <message id="getHumanResourceManagerRequestMessage" itemRef="rldProcess:getHumanResourceManagerRequestItem" /> <message id="getHumanResourceManagerResponseMessage" itemRef="rldProcess:getHumanResourceManagerResponseItem" /> <itemDefinition id="getHumanResourceManagerRequestItem" structureRef="userbaseService:humanResourceManager" /> <itemDefinition id="getHumanResourceManagerResponseItem" structureRef="userbaseService:humanResourceManagerResponse" /> ... </process> </definitions>
where 'implementationRef' is the port name of the service, and 'structureRef' is the type of messages exchanged with the service. These both references are defined in the imported WSDL.
- Next, define mapping of the service request and the service reply
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...> ... <process id="shifting-summary-sending" name="Shifting summary sending process" isExecutable="true"> ... <serviceTask id="getHRManagerEmail" name="Retrieve email of the human resource manager" implementation="##WebService" operationRef="rldProcess:getHumanResourceManagerOp"> <ioSpecification> <dataInput itemSubjectRef="rldProcess:getHumanResourceManagerRequestItem" id="getHRManagerEmailTaskInput" /> <dataOutput itemSubjectRef="rldProcess:getHumanResourceManagerResponseItem" id="getHRManagerEmailTaskOutput" /> <inputSet> <dataInputRefs>getHRManagerEmailTaskInput</dataInputRefs> </inputSet> <outputSet> <dataOutputRefs>getHRManagerEmailTaskOutput</dataOutputRefs> </outputSet> </ioSpecification> <dataInputAssociation> <targetRef>getHRManagerEmailTaskInput</targetRef> <assignment> <from>${employeeId}</from> <to>${getHRManagerEmailTaskInput.userId}</to> </assignment> </dataInputAssociation> <dataOutputAssociation> <targetRef>hrManagerEmail</targetRef> <transformation>${getHRManagerEmailTaskOutput.email}</transformation> </dataOutputAssociation> </serviceTask> ... </process> </definitions>
Dash ('-') included in XML tag of service request/reply are removed. In BPMN assignment you must use the standard naming convention. Example: the XML tag 'user-id' must be used as '{{userId}' in assignments. |
More information about the syntax of expression used in data associations can be found in: The Java EE 6 Tutorial. |
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 |
The namespace of interface name and service name is http://petals.ow2.org/components/activiti/generic/1.0 |
The service "ProcessInstanceService"
The service "ProcessInstancesService" provides following operations:
Operation name | Description |
---|---|
getProcessInstances | Query process instances according to the given criteria. |
suspendProcessInstances | Suspend a process instance list. |
activateProcessInstances | Activate a process instance list. |
The operation "getProcessInstances"
The search criteria are given by the following parameters, each criteria operates as a filter:
Parameter name | Description | Default value |
---|---|---|
state | Process instances returned must match this state. Possible values are:
|
active |
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.
The operation "suspendProcessInstances"
For each process instance identifier of the given list, the process instance will be suspended.
The response returns by this operation is an execution report, where the adjournment result is given for each process instance identifier:
- 'suspended', the adjournment succeeds and the process instance is now suspended,
- 'not-found', no process instance found for the given process instance identifier,
- 'already-suspended', the process instance is already suspended.
The operation "activateProcessInstances"
For each process instance identifier of the given list, the suspended process instance will be activated.
The response returns by this operation is an execution report, where the activation result is given for each process instance identifier:
- 'activated', the activation succeeds and the process instance is now active,
- 'not-found', no process instance found for the given process instance identifier,
- 'already-activated', the process instance is already activated.
The service "TaskService"
The service "TaskService" provides following operations:
Operation name | Description |
---|---|
getTasks | Query tasks according to the given criteria |
The operation "getTasks"
The search criteria are given by the following parameters, each criteria operates as a filter:
Parameter name | Description | Default value |
---|---|---|
active | If "true", only selects tasks which are active (ie. for which the process instance is not suspended) | true |
assignee | Only select tasks for which the given user is a candidate. | 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.
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 write your own entity service,
- in next versions, new entity services will be added.
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.
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
File formats
The user file is defined as following:
# # Property format: # <user-id> = <user-password> # kermit = kermit fozzie = fozzie gonzo = gonzo
The group file is defined as following:
# # Property format: # <group-id> = <user-id-1> <user-id-2> ... <user-id-n> # admin = kermit manager = kermit gonzo management = kermit gonzo accountancy = kermit fozzie gonzo engineering = kermit sales = kermit gonzo user = fozzie
Petals services based entity service
TODO
Write your own entity service
You can write 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 (the file-based entity service).
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.
<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-job-executor-core-pool-size /> <petals-se-activitibpmn:engine-job-executor-max-pool-size /> <petals-se-activitibpmn:engine-job-executor-keep-alive-time /> <petals-se-activitibpmn:engine-job-executor-queue-size /> <petals-se-activitibpmn:engine-job-executor-max-timer-jobs-per-acquisition /> <petals-se-activitibpmn:engine-job-executor-max-async-jobs-due-per-acquisition /> <petals-se-activitibpmn:engine-job-executor-async-job-acquire-wait-time /> <petals-se-activitibpmn:engine-job-executor-timer-job-acquire-wait-time /> <petals-se-activitibpmn:engine-job-executor-timer-lock-time /> <petals-se-activitibpmn:engine-job-executor-async-job-lock-time /> <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>
CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
Parameter | Description | Default | Scope |
---|---|---|---|
acceptor-pool-size | The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread. | 1 |
Runtime |
acceptor-retry-number | Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed. | 40 |
Installation |
acceptor-retry-wait | Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one plus this base duration. | 250 |
Installation |
acceptor-stop-max-wait | The max duration (in milliseconds) before, on component stop, each acceptor is stopped by force. | 500 |
Runtime |
processor-pool-size | The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool. | 10 | Runtime |
processor-max-pool-size | The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time. |
50 |
Runtime |
processor-keep-alive-time | When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds. |
300 |
Runtime |
processor-stop-max-wait | The max duration (in milliseconds) of message exchange processing on stop phase (for all processors). |
15000 |
Runtime |
time-beetween-async-cleaner-runs | The time (in milliseconds) between two runs of the asynchronous message exchange cleaner. |
2000 |
Installation |
properties-file | Name of the file containing properties used as reference by other parameters. Parameters reference the property name using a placeholder in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property. The properties file can be reloaded using the JMX API of the component. The runtime configuration MBean provides an operation to reload these place holders. Check the service unit parameters that support this reloading. The value of this parameter is :
|
- | Installation |
monitoring-sampling-period | Period, in seconds, of a sample used by response time probes of the monitoring feature. |
300 |
Installation |
Definition of CDK parameter scope :
- Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
- Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.
Interceptor
Interceptors can be defined to inject some post or pre processing in the component during service processing.
Using interceptor is very sensitive and must be manipulate only by power users. An non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <!--...--> <petalsCDK:component-interceptors> <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:component-interceptors> <!--...-->
Interceptors configuration for Component (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
interceptor - class | Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. | - | Yes |
interceptor - name | Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. | - | Yes |
interceptor - active | If true, the Interceptor instance is activated for every SU deployed on the component. If false, the Interceptor can be activated: -by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU. -by a SU configuration |
- | Yes |
param[] - name | The name of the parameter to use for the interceptor. | - | No |
param[] | The value of the parameter to use for the interceptor. | - | No |
Component specific parameters
These parameters drive features proposed by the component and configure the 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 activation and configuration,
- BPMN validation,
- identity service to use.
Parameter | Description | Default | Required | Scope |
---|---|---|---|---|
integration-mode-enable | Enable the mode 'Integration' | true
|
No
|
Installation
|
jdbc_url | URL of the database. The default database is an in-memory database | jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000
|
Yes
|
Installation
|
jdbc_driver | JDBC driver. Except for the default JDBC driver, it must be provided as shared-library. | org.h2.Driver
|
Yes
|
Installation
|
jdbc_username | Username used for the database connection. | sa
|
Yes
|
Installation
|
jdbc_password | Passwrd used for the database connection. | ""
|
Yes
|
Installation
|
jdbc_max_active_connections | The number of idle connections that the database connection pool at maximum at any time can contain. | 10
|
No
|
Installation
|
jdbc_max_idle_connections | The number of active connections that the database connection pool at maximum at any time can contain. | -
|
No
|
Installation
|
jdbc_max_checkout_time | The amount of time in milliseconds a connection can be 'checked out' from the connection pool before it is forcefully returned. | 20000 (20 seconds)
|
No
|
Installation
|
jdbc_max_wait_time | This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured). | 20000 (20 seconds)
|
No
|
Installation
|
database_type | The database type: it's normally not necessary to specify this property it is automatically analyzed from the database connection meta data. Should only be specified in case automatic detection fails on Activiti engine side. Possible values: h2, mysql, oracle, postgres, mssql, db2. | -
|
No
|
Installation
|
database_schema_update | The database schema update: allows to set the strategy to handle the database schema on process engine boot and shutdown:
|
true
|
No
|
Installation
|
engine-enable-job-executor | Enable or disable the Activiti job executor. See Enabling/disabling the Activiti job executor | true
|
No
|
Installation
|
engine-job-executor-core-pool-size | The minimal number of threads that are kept alive in the thread pool for job execution of the Activiti engine job executor. | 2
|
No
|
Installation
|
engine-job-executor-max-pool-size | The maximum number of threads that are kept alive in the thread pool for job execution of the Activiti engine job executor. | 10
|
No
|
Installation
|
engine-job-executor-keep-alive-time | The time, in milliseconds, a thread used for job execution must be kept alive before it is destroyed. | 5000
|
No
|
Installation
|
engine-job-executor-queue-size | The size of the queue on which jobs to be executed are placed. | 100
|
No
|
Installation
|
engine-job-executor-max-timer-jobs-per-acquisition | The number of timer jobs that are fetched from the database in one query. | 1
|
No
|
Installation
|
engine-job-executor-max-async-jobs-due-per-acquisition | The number of asynchronous jobs due that are fetched from the database in one query. | 1
|
No
|
Installation
|
engine-job-executor-async-job-acquire-wait-time | The time, in milliseconds, between asynchronous job due queries being executed. | 10000
|
No
|
Installation
|
engine-job-executor-timer-job-acquire-wait-time | The time in milliseconds between timer job queries being executed. | 10000
|
No
|
Installation
|
engine-job-executor-timer-lock-time | The time, in milliseconds, that a timer job is locked before being retried again. | 300000
|
No
|
Installation
|
engine-job-executor-async-job-lock-time | The time in milliseconds that an asynchronous job is locked before being retried again. | 300000
|
No
|
Installation
|
engine-enable-bpmn-validation | Enable or disable the BPMN validation of processes to deploy into the Activiti engine | true
|
No
|
Installation
|
engine-identity-service-class-name | Class name of the entity service to use. | org.ow2.petals.activitibpmn.identity.file.FileIdentityService
|
No
|
Installation
|
engine-identity-service-config-file | Configuration file of the entity service used. | The default configuration of the entity service is service dependent. See documentation of the entity service
|
No
|
Installation
|
Enabling/disabling the Activiti job executor
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.
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):
|
- 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.
- a MONIT trace associated to the start of the interaction request creating the process instance, with following attributes:
- 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.
- a MONIT trace associated to the start of the interaction request completing the user task, with following attributes:
- 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.
- a MONIT trace associated to the end of the process instance, with following attributes:
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.
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:
... org.activiti.level=INFO org.activiti.engine.impl.level=FINE ...
Monitoring the component
Using metrics
Several probes providing metrics are included in the component, and are available through the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.
Common metrics
The following metrics are provided through the Petals CDK, and are common to all components:
Metrics, as MBean attribute | Description | Detail of the value | Configurable |
---|---|---|---|
MessageExchangeAcceptorThreadPoolMaxSize | The maximum number of threads of the message exchange acceptor thread pool | integer value, since the last startup of the component | yes, through acceptor-pool-size |
MessageExchangeAcceptorThreadPoolCurrentSize | The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. | instant integer value | no |
MessageExchangeAcceptorCurrentWorking | The current number of working message exchange acceptors. | instant long value | no |
MessageExchangeAcceptorMaxWorking | The max number of working message exchange acceptors. | long value, since the last startup of the component | no |
MessageExchangeAcceptorAbsoluteDurations | The aggregated durations of the working message exchange acceptors since the last startup of the component. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeAcceptorRelativeDurations | The aggregated durations of the working message exchange acceptors on the last sample. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeProcessorAbsoluteDurations | The aggregated durations of the working message exchange processor since the last startup of the component. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorRelativeDurations | The aggregated durations of the working message exchange processor on the last sample. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorThreadPoolActiveThreadsCurrent | The current number of active threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolActiveThreadsMax | The maximum number of threads of the message exchange processor thread pool that was active | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolIdleThreadsCurrent | The current number of idle threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolIdleThreadsMax | The maximum number of threads of the message exchange processor thread pool that was idle | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolMaxSize | The maximum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-max |
MessageExchangeProcessorThreadPoolMinSize | The minimum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-min |
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent | The current number of enqueued requests waiting to be processed by the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolQueuedRequestsMax | The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component | instant integer value | no |
ServiceProviderInvocations | The number of service provider invocations grouped by:
|
integer counter value since the last startup of the component | no |
ServiceProviderInvocationsResponseTimeAbs | The aggregated response times of the service provider invocations since the last startup of the component grouped by:
|
n-tuple value containing, in millisecond:
|
no |
ServiceProviderInvocationsResponseTimeRel | The aggregated response times of the service provider invocations on the last sample, grouped by:
|
n-tuple value containing, in millisecond:
|
no |
Dedicated metrics
Moreover the common metrics, some dedicated probes are include on the component:
Metrics, as MBean attribute | Description | Detail of the value | Configurable |
---|---|---|---|
ProcessDefinitions | List current process definitions deployed with some metrics on process instances | n-tuple value containing:
|
no |
AsyncExecutorThreadPoolActiveThreadsCurrent | The current number of active threads of the message exchange processor thread pool | instant integer value | no |
AsyncExecutorThreadPoolActiveThreadsMax | The maximum number of threads of the message exchange processor thread pool that was active | integer value, since the last startup of the component | no |
AsyncExecutorThreadPoolIdleThreadsCurrent | The current number of idle threads of the message exchange processor thread pool | instant integer value | no |
AsyncExecutorThreadPoolIdleThreadsMax | The maximum number of threads of the message exchange processor thread pool that was idle | integer value, since the last startup of the component | no |
AsyncExecutorThreadPoolMaxSize | The maximum size, in threads, of the message exchange processor thread pool | instant integer value | no |
AsyncExecutorThreadPoolMinSize | The minimum size, in threads, of the message exchange processor thread pool | instant integer value | no |
AsyncExecutorThreadPoolQueuedRequestsCurrent | The current number of enqueued requests waiting to be processed by the message exchange processor thread pool | instant integer value | no |
AsyncExecutorThreadPoolQueuedRequestsMax | The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component | instant integer value | no |
DatabaseConnectionPoolActiveConnectionsCurrent | The current number of active connections of the database connection pool | instant integer value | no |
DatabaseConnectionPoolActiveConnectionsMax | The maximum number of connections of the database connection pool that was active | integer value, since the last startup of the component | no |
DatabaseConnectionPoolIdleConnectionsCurrent | The current number of idle connections of the database connection pool | instant integer value | no |
DatabaseConnectionPoolIdleConnectionsMax | The maximum number of connections of the database pool that was idle | integer value, since the last startup of the component | no |
DatabaseConnectionPoolMaxActiveSize | The maximum number of active connections in the database connection pool | instant integer value | no |
DatabaseConnectionPoolMaxIdleSize | The maximum number of idle connections in the database connection pool | instant integer value | no |
Receiving alerts
Several alerts are notified by the component through notification of the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.
To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios. |
Common alerts
Defect | JMX Notification |
---|---|
A message exchange acceptor thread is dead |
|
No more thread is available in the message exchange acceptor thread pool |
|
No more thread is available to run a message exchange processor |
|
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 |
|
No more connection is available in the database pool |
|
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.
This dedicated framework is provided by the Maven artifact org.ow2.petals:petals-se-activiti-junit:
<project> ... <dependencies> ... <dependency> <groupId>org.ow2.petals</groupId> <artifactId>petals-se-activiti-junit</artifactId> <version>1.0.0</version> <scope>test</scope> </dependency> ... </dependencies> ... </project>
The version 1.0.0+ of the framework is compliant with the Petals SE Activiti 1.1.0+. |
Checking the compliance of the WSDL
The unit test framework contains an assertion 'assertWsdlCompliance' to verify easily the compliance of your WSDL with the attendees of the mode 'service':
import static org.ow2.petals.activitibpmn.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-bpmn/vacationService", "new"), new QName("http://petals.ow2.org/samples/se-bpmn/vacationService", "validate"), new QName("http://petals.ow2.org/samples/se-bpmn/vacationService", "update") }); } }
See the Javadoc for more details on parameters.
Unit-testing your XSLs
The unit test framework contains an assertion 'assertXslTransformation' to verify easily the result of your XSL transformations:
import static org.ow2.petals.activitibpmn.junit.Assert.assertXslTransformation; import ... import org.junit.Test; public class XslTest { @Test public void newVacationRequestResponse_Nominal() throws IOException, TransformerException, SAXException { assertXslTransformation(NEW_VACATION_RESULT_DIR + "nominal.xml", XSL_NEW_VACATION, "AZE123", null, null, false); } }
See the Javadoc for more details on parameters.
Unit-testing your process definition
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.
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:
<project> ... <dependencies> ... <dependency> <groupId>org.ow2.petals.activiti</groupId> <artifactId>activiti-engine</artifactId> <version>5.22.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> ... </dependencies> ... </project>
Caution to use the same version of the Activiti engine as the one embedded into the Petals SE Activiti |
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:
<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>
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:
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); } }
If your process definition includes Petals service invocations, you must use mocks for these services. These mocks can be SoapUI mock services invoked as standard web-services, using HTTP/SOAP. The URLs of these mock services must be mapped on the endpoint names define in service provider WSDLs used in the process definition. The mapping is declared in the Spring configuration file as following:
<bean id="archiveEndpoint" class="javax.xml.namespace.QName"> <constructor-arg index="0" value="http://petals.ow2.org/samples/se-bpmn/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-bpmn/notifyVacationService" /> <constructor-arg index="1" value="autogenerate" /> </bean> <bean id="wsOverridenEndpointAddresses" class="java.util.concurrent.ConcurrentHashMap"> <constructor-arg index="0"> <map> <entry> <key> <ref bean="archiveEndpoint" /> </key> <value type="java.net.URL">http://localhost:8188/mockarchiveSoapBinding</value> </entry> <entry> <key> <ref bean="notifyEndpoint" /> </key> <value type="java.net.URL">http://localhost:8188/mocknotifyVacationBinding</value> </entry> </map> </constructor-arg> </bean> <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration"> ... <property name="wsOverridenEndpointAddresses"> <ref bean="wsOverridenEndpointAddresses" /> </property> </bean>
and SoapUI mock services can be automatically started at Maven level with following declaration in the POM file of the service unit:
<project> ... <pluginRepositories> <pluginRepository> <id>smartbear-sweden-plugin-repository</id> <url>http://www.soapui.org/repository/maven2/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> <build> <plugins> ... <plugin> <groupId>com.smartbear.soapui</groupId> <artifactId>soapui-maven-plugin</artifactId> <version>5.2.1</version> <executions> <execution> <id>startup-mock-archive</id> <configuration> <projectFile>${basedir}/src/test/soapui/su-activiti-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-activiti-vacationService-provide-soapui-project.xml</projectFile> <mockService>notifyVacationBinding MockService</mockService> <noBlock>true</noBlock> </configuration> <goals> <goal>mock</goal> </goals> <phase>process-test-classes</phase> </execution> </executions> </plugin> ... </plugins> </build> ... </project>
where SoapUI project files contains mock service definitions.
Annex: Sample WSDL
Abstract part:
<?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>
Implementation part
<?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" start-event-message-name="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" user-task-id="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>