The BPEL Management API exposes management functions related to BPEL processes and their instances.
The Process Management API is defined as a Web service interface. In doing so we can offer SOAP access to the service, and also create Java interfaces for SOAP access and JMX, depending on needs. All messages are defined as XML elements, mapping to WSDL doc/literal.
Complex structures and other data fields are declared as XML elements. However, key fields are declared as XML attributes. This distinction maps to the concept of keys in several languages, e.g. constraints can be applied in XML Schema using key fields, or used as keys in a Java HashMap. Sequences of elements map to ordered collections, which may be accessed by position or key. For example, when returning a list of process instances, the collections is ordered as specified in the request, but in addition the process identifier can be used as a key into the collection.
When data does not easily yield to structuring, we use a textual presentation and BNF to define the syntax. For example, a query statement like "order_id123 and customer_id456" is easier to process in textual form.
The process definition management interface defines six operations: list - Returns information about all, or some process definitions. details - Returns detailed information about the specified process definition. set-properties - Changes properties associated with the process definition. activate - Activates the process definition. * retire - Retires the process definition.
The list operation retrieves and returns information about all, or some process definitions.
The request identifies the process definitions using a filter that can select definitions with a given name, status, deployment date, etc. Without a filter, the operation returns all process definitions. The request also indicates what information to include in the response, and which key fields to use for ordering the results. The request schema has the following structure:
<list> <filter> filter <filter>? <include> includes </include>? <order> keys </order>? </list>
The filter element can be used to narrow down the list of process definitions by applying selection criteria. There are four filters that can be applied: name - Only process definition with this local name. namespace - Only process definition with this namespace URI. status - Only process definition with these status code(s). deployed - Only process definitions deployed relative to this date/time.
The name and namespace filters can do full or partial name matching. Partial matching occurs if either filter ends with an asterisk (). These filters are not case sensitive, for example* namemy_* will match _MyProcess_ and _my-process_. If unspecified, the default filter is _name* namespace=*.
The status filter can be used to filter all process definitions based on two status codes, activated and retired.
The deployed filter can be used to filter all process definitions deployed on or after a particular date or date/time instant. The value of this filter is either an ISO-8601 date or ISO-8601 date/time. For example, to find all process definitions deployed on or after September 1, 2005, use deployed>=20050901.
The include element can be used to request the operation returns additional information in the response, by specifying a space-separated list of keywords. Currently two keywords are supported: properties - Returns process definition properties. instance - Returns aggregate instance information.
By default the response returns process definitions in no particular order. The order element can be used to order the results by specifying a space-separated list of keys. Each key can be prefixed with a plus sign '+' to specify ascending order, or a '-' minus sign to specify descending order. Without a sign the default behavior is to return process definitions in ascending order. The currently supported odering keys are: name - Order based on the local name of the process definition. namespace - Order based on the namespace URI of the process definition. version - Order based on the version number. status - Order based on the status of the process definition (activated followed by retired). * deployed - Order based on the deployment date/time.
For exampe, the following request returns all process definitions that have a name starting with order and are currently in the activated status. The response is ordered by the definition name, definitions with the same name are ordered by descending version number. Aggergate instance information is returned for each process definition that matches the filter.
<list> <filter>name=order* status=activated</filter> <include>instance</include> <order>name -version</order> </list>
The response to the list operation lists all process definitions that match the filters, empty if no process definition matches the filter. The response schema has the following structure:
<list.response> <definition name = ncname namespace = uri version = integer> <deployed> <activated> | <retired> <properties>? <instances>? </definition>* </list.response>
Each process definition is identified by its fully qualified name (name and namespace attributes) and version number. If there are multiple versions of the same process definition, the operation will return information about all of the versions that match the filter.
The deployed element specifies when the process definition was deployed and by which user. It has the following structure:
<deployed> <on> date/time </on> <by> token </by> </deployed>
If the process definition is activated, the activated element specifies when it was activated and by which user. If the process was activated upon deployment, then the information provided by the deployed and activated elements will be identical. If the process definition is retired, the retired element specifies which it was retired and by which user. All three elements use the same structure.
If the operation requested process properties, the properties element will appear in the response. It has the following structure:
<properties> <property name = ncname namespace = uri> <value> mixed </value> </property>* </properties>
Each property is identified by it's fully qualified name (the name and namespace attributes). The value element serves as a wrapper for the property value, which may include mixed content and use elements for different namespaces.
If the operation requested instance aggregates, the instances element will appear in the response. It has the following structure:
<instances> <instance status = token> <count> integer </count> </instance>* </instances>
The instance element returns the number of process instances that have the status specified by the status attribute. The following status codes are used: active - All currently active process instances. completed - All successfully completed process instances. terminated - All terminated process instances. failed - All failed process instances. suspended - All process instances that are currently suspended. error - All process instances currently reporting an error.
During it's execution, a process instance is in the active state. It may be suspended, in which case it is counted as suspended and not active. If an error occurs that does not cause the process to complete, but requires attention, the process is counted in error instead of active. If a process is terminated with the exit activity, or any other mechanism that applies the same semantics, it counts as terminated. If a fault occurs in the global scope, the process counts as failed. Otherwise, the process is counted as completed.
The details operation retrieves and returns detailed information about the specified process definition.
The request identifies the process definition by its fully qualified name, and optionally by version number. If the version number is ommitted, information is returned about the last version of the process definition. The request schema has the following structure:
<details> <definition name = ncname namespace = uri version? = integer> </definition> </details>
The response uses a structure similar to the list operation, with additional information not returned from list. The response includes the requested process definition, and will be empty if that process definition cannot be found in the system. The response schema has the following structure:
<details.response> <definition name = ncname namespace = uri version = integer> <deployed> <activated> | <retired> <properties> <instances> <documents> <extension elements>* </definition>? </details.response>
The response always returns information about instances of the process definition. The response also returns a list of documents associated with the process definition, for example, the BPEL process definition, WSDL service definitions, deployment descriptor, etc. Applications may need to retrieve these documents for further processing, e.g. to monitor service endpoints defined in the process, or interpret data from the process instance.
The documents element has the following structure:
<documents> <document name = ncname? namespace = uri? type = uri src = uri> </document>* </documents>
The name and namespace attributes reference the document name and namespace of definitions in that document, respectively. For example, if the document is a BPEL process definition, the name attribute specifies the process definition, and the namespace attribute specifies the target namespace of the process definition. These attributes are optional, as not all documents specify that information.
An implementation must return a name and namespace attribute for every BPEL, WSDL and XSD documents that specify a name and/or namespace for their target definitions.
The type attribute uses a URI to identify the document type. For BPEL, WSDL and XSD, this attribute uses the namespace URI of the relevant specification, e.g. (TODO: WSDL 1.1 namespace) for a WSDL 1.1 document.
The src attribute provides a URL that can be used to access the definition.
The details response may return additional information not covered here using extension elements. Extension elements must use a different namespace. Applications do not need to understand or process extension elements.
The set-properties allows changes to properties associated with the process definition.
The request identifies the process definition by its fully qualified name and version number, and specifies the updates to perform on that process definition. The request schema has the following structure:
<set-properties> <definition name = ncname namespace = uri version = integer> <properties> <property name = ncname namespace = uri> <value> mixed </value>? </property>* </properties> </definition> </set-properties>
A property can be changed or added by specifying the property by name and providing a value. A property is removed if the property name is specified but the value element is absent.
The response uses a structure similar to the details operation, returning the state of the process definition after the state change. If the process could not be found, an empty response is returned. The response schema has the following structure:
<set-properties.response> <definition name = ncname namespace = uri version = integer> <deployed> <activated> | <retired> <properties> <instances> <documents> <extension elements>* </definition>? </set-properties.response>
The activate and retire operations are used to change the process definition status to activated and retired.
The request identifies the process definition by its fully qualified name and version number, and specifies the updates to perform on that process definition. The request schema has the following structure:
<activate> <definition name = ncname namespace = uri version = integer> </activate> <retire> <definition name = ncname namespace = uri version = integer> </retire>
The response uses a structure similar to the details operation, returning the state of the process definition after the state change. If the process could not be found, an empty response is returned.
The operations in this interface may throw onw of two faults: invalid-request - The request message is missing mandatory information, contains invalid information, or contains elements/attributes that are not supported by the operation. processing-error - The operation failed to process the request. The application may try the operation at a later time.
By design the operations return invalid-request only if the request message is invalid. If the request does not identify any deployed process definition, the operation returns a response that contains no process definition.
The process instance management interface defines four operations: list - Returns information about all, or some process instances. detail - Returns detailed information about the specified process instance. suspend - Suspends the process instance. resume - Resumes the process instance. terminate - Terminates the process instance. fault - Faults the process instance. * delete - Deletes all or some completed process instances.
The list operation retrieves and returns information about all, or some process instances.
The request identifies the process instances using a filter that can select instances with a given name, status, property values, etc. Without a filter, the operation returns all process instances up to a specified limit. The request also indicates which key fields to use for ordering the results. The request schema has the following structure:
<list> <filter> filter <filter>? <order> keys </order>? <limit> integer </limit> <properties> names </properties> </list>
The filter element can be used to narrow down the list of process definitions by applying selection criteria. There are six filters that can be applied: name - Only process instances with this local name. namespace - Only process instances with this namespace URI. status - Only process instances with these status code(s). started - Only process instances started relative to this date/time. last-active - Only process instances last active relative to this date/time. $property - Only process instances with a correlation property equal to the specified value.
The name and namespace filters can do full or partial name matching. Partial matching occurs if either filter ends with an asterisk (). These filters are not case sensitive, for example* namemy_* will match _MyProcess_ and _my-process_. If unspecified, the default filter is _name* namespace=*.
The status filter can be used to filter all process definitions based on six status codes: active - All currently active process instances (excludes instances in any other state). suspended - All process instances that have not completed, but are currently suspended. error - All process instances that have not completed, but are currently indicate an error condition. completed - All successfully completed process instances (excludes instances in any other state). terminated - All process instances that were terminated. faulted - All process instances that encountered a fault (in the global scope).
The started filter can be used to filter all process instances started on or after a particular date or date/time instant. The value of this filter is either an ISO-8601 date or ISO-8601 date/time. For example, to find all process instances started on or after September 1, 2005, use started>=20050901. Similarly, the last-active filter can be used to filter all process instances based on their last active time. The last active time records when the process last completed performing work, and either completed or is now waiting to receive a message, a timeout or some other event.
Each process instance has one or more properties that are set its instantiation, that can be used to distinguish it from other process instances. In this version of the specification, we only support properties instantiated as part of correlation sets defined in the global scope of the process. For example, if a process instantiates a correlation set that uses the property order-id, it is possible to filter that process instance based on the value of that property.
The property name is identified by the prefix $. If the property name is an NCName, the filter will match all properties with that local name. If the property name is
{namespace}\ local, the filter will match all properties with the specified namespace URI and local name. For example, to retrieve a list of all active process instances with a property order-id that has the value 456, use statusactive $order-id456.
By default the response returns process instances in no particular order. The order element can be used to order the results by specifying a space-separated list of keys. Each key can be prefixed with a plus sign '+' to specify ascending order, or a '-' minus sign to specify descending order. Without a sign the default behavior is to return process instances in ascending order. The currently supported odering keys are: pid - Order based on the process identifier. name - Order based on the local name of the process instance. namespace - Order based on the namespace URI of the process instance. version - Order based on the version number. status - Order based on the status of the process instance. started - Order based on the process instance start date/time. * last-active - Order based on the process instance last active date/time.
The properties element is used to request the value of one or more properties, for each of the returned process instances. The value of this element is a list of names, each an NCName. Properties specified in this element do not have to overlap with properties specified in the filter.
TBD: describe limit.
The response to the list operation lists all process instances that match the filters, empty if no process instance matches the filter. The response schema has the following structure:
<list.response> <instance pid = string> <defintion name = ncname namespace = uri version = integer> </definition> <started> date/time </started> <last-active> date/time </last-active> <status> status </status> <error-ts> date/time </error-ts>? <properties> <property name = ncname namespace = uri> value </property>* </properties> <fault> TBD </fault>? </instance>* </list.response>
Each process is identified by the unique process instance identifier (pid). In addition, the process's definition is identified by its fully qualified name and version number.
The started element indicates when the process instance was started, while last-active indicates when the process instance was last active. If the process instance has completed (successfully or not), this element provides the actual completion date/time. The status code indicates whether the process is active, completed successfully, or any of the six states described for the filter.
The properties element lists one or more properties and their values. The name of the property is specified using the name and namespace attributes, the value is contained within the property element. Note that an instance may have multiple different values for the same property, in which case the property element will appear multiple times with the same name and different values.
TBD: error-ts and fault elements.
The details operation retrieves and returns detailed information about the specified process instance.
The request identifies the process instance using the process identifier. The request schema has the following structure:
<details> <instance pid = token> </instance> </details>
The response uses a structure similar to the list operation, with additional information not returned from list. The response includes the requested process instance, and will be empty if that process instance cannot be found in the system. The response schema has the following structure:
<details.response> <instance pid = string> <defintion name = ncname namespace = uri version = integer> </definition> <started> date/time </started> <last-active> date/time </last-active> <status> status </status> <error-ts> date/time </error-ts>? <properties> <property name = ncname namespace = uri> value </property>* </properties> <fault> TBD </fault>? <extension elements>* </instance>? </details.response>
TBD: Structure for returning state information about the process instance.
The details response may return additional information not covered here using extension elements. Extension elements must use a different namespace. Applications do not need to understand or process extension elements.
These operations are used to suspend/resume the process instance, or to forcefully complete the process instance, with and without recovery.
The request identifies the process instance using the process identifier. The request schema has the following structure:
<suspend> <instance pid = token/>+ </suspend> <resume> <instance pid = token/>+ </resume> <terminate> <instance pid = token/>+ </terminate> <fault> <instance pid = token> </instance> TBD: fault information </fault>
The suspend operation changes the process state from active to suspended. It only affects process instances that are in the active or error states. Likewise, the resume operation changes the process state from suspended to active. It only affects process instances that are in the suspended state.
The terminate operation causes the process instance to terminate immediately, without a chance to perform any fault handling or compensation. The process transitions to the terminated state. It only affects process instances that are in the active, suspended or error states.
The fault_operation causes the process instance to complete unsuccessfully by throwing the specified fault in the global scope. The process is able to perform recovery using a fault handler in the global scope, through termination handlers in nested scopes and by invoking installed compensation handlers. The process will transition to the _faulted state.
The suspend, resume and terminate operations can be used with multiple process instances at the same time, by specifying a list of instance elements.
TBD: specifying which fault to throw and providing details.
The response uses a structure similar to the detail operation. The response includes the requested process instance, and will be empty if that process instance cannot be found in the system. The response reflects the process instance state available on return. Some state changes take significant time to process, e.g. when throwing a fault in the process, and may not be reflected in the response message.
The delete operation delete all, or some completed process instances.
The request identifies the process instances using a filter that can select instances with a given name, status, property values, etc. Alternatively, the instance element can be used to specify a particular process instance to delete. The instance element can be repeated to delete multiple process instances in the same operation. At least one of these elements is required. The request schema has the following structure:
<delete> <filter> filter <filter> | <instance pid = token/>+ </delete>
This operation uses the same filters as the list operation, with the exception that the only meaningful status codes are completed, terminated and faulted. A process instance that is in the active, suspended or error state cannot be deleted. Similarly, specifying a process instance has no affect if that instance is not in the completed, terminated or faulted state.
The operation returns a message listing all the deleted process instances:
<delete.response> <instance pid = token/>* </delete.response>