Title: BPEL Management API Specification
Category: documentation

<a name="BPELManagementAPISpecification-BPELManagementAPISpecification"></a>
# BPEL Management API Specification
The BPEL Management API exposes management functions related to BPEL processes and their instances.

<a name="BPELManagementAPISpecification-GeneralDesignPrinciples"></a>
## General Design Principles
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_id`123 and customer_id`456" is easier to process in textual form.

<a name="BPELManagementAPISpecification-TheProcessDefinitionManagementInterface"></a>
## The Process Definition Management Interface
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.

<a name="BPELManagementAPISpecification-ListProcessDefinitions"></a>
### List Process Definitions
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\* *_name`my_* 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_.

<a name="BPELManagementAPISpecification-GetProcessDefinitionDetails"></a>
### Get Process Definition Details
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.

<a name="BPELManagementAPISpecification-SetProcessDefinitionProperties"></a>
### Set Process Definition Properties
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>


<a name="BPELManagementAPISpecification-Activate/RetireProcessDefinition"></a>
### Activate/Retire Process Definition
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.

<a name="BPELManagementAPISpecification-Faults"></a>
### Faults
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.

<a name="BPELManagementAPISpecification-TheProcessInstanceManagementInterface"></a>
## The Process Instance Management Interface
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.

<a name="BPELManagementAPISpecification-ListProcessInstances"></a>
### List 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\* *_name`my_* 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 _status`active $order-id`456_.

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.

<a name="BPELManagementAPISpecification-GetProcessInstanceDetails"></a>
### Get Process Instance Details
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.

<a name="BPELManagementAPISpecification-Suspend/Resumse/Terminate/FaultProcessInstance"></a>
### Suspend/Resumse/Terminate/Fault Process Instance
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.

<a name="BPELManagementAPISpecification-DeleteProcessInstances"></a>
### Delete Process Instances
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>