The Workflow Management Coalition Specification
Workflow Management Coalition
Workflow Client Application (Interface 2)
Application Programming Interface
(WAPI)
Specification
Document Number WFMC-TC-1009
01-October-96
Version 1.2
Workflow Management Coalition
Avenue Marcel Thiry 204
1200 Brussels
Belgium
Tel: +32 2 774 96 33
Fax: +32 2 774 96 90
Email: 100113.1555@compuserve.com
or WfMC@eyam.be
www: http://www.aiai.ed.ac.uk/wfmc
or http://www.arms.ohio-state.edu/wfmc
The "WfMC" logo and "Workflow Management Coalition" name are service marks of
the Workflow Management Coalition.
Neither the Workflow Management Coalition nor any of its members make any
warranty of any kind whatsoever, express or implied, with respect to the
Specification, including as to non-infringement, merchantability or fitness for
a particular purpose. This Specification is provided "as is".
First printing, November 1995
Second printing, version 1.1, May 1996
Third printing, version 1.2, November 1996
1. Purpose
· Intitial version
Version 1.1
· Consistent handling of output parameters as pointers
· Added attributes for WMTProcessDefinition
· Editorial enhancements
Version 1.2
· Added OLE binding
· Added OMG IDL binding
2.
Purpose
The purpose of this document is to specify standard workflow management Application Programming Interfaces (API) which can be supported by WFM products. These API calls provide for a consistent method of access to WFM functions in cross-product WFM Engines. The API set is named Workflow Application Programming Interfaces (WAPI).
This document defines the API specifications of the Workflow Management Coalition for building workflow-enabled applications (Interface 2 in the Workflow Reference Model).
This document is directly associated to the documents:
· Workflow Management Coalition Glossary
· Workflow Management Coalition Interface 2 WAPI Naming Conventions
The three documents constitute the complete specification.
3.
Audience
The intended audience of this document includes all participants in the
workflow industry. Comments should be addressed to the Workflow Management
Coalition.
4.
Overview
The support of these interfaces in WFM products allow the implementation of
front-end applications which need to access WFM Engine functions (Workflow
services). Such implementations might be written by WFM exploiters or ISVs.
Implementation of these API calls are also intended to allow the workflow
applications to be adjusted to operate with different WFM Engines using this
common API interface.
These API calls should allow a WFM exploiter to have a single end user interface and functions set regardless of the number of WFM products existing in an installation. WAPI calls may be implemented in a number of languages. The first Coalition specification will be for the `C' language. The API operates as CALLS. No assumption is may regarding the underlying implementation of the CALLS in a particular WFM product implementation. The WAPI calls are for use at run-time. That is, when processes are executing or are to be executed. They would normally be used by workflow applications (e.g. worklist handlers, cooperating applications) but may also be used by a WFM Engine when it wishes to interact with another WFM product within the context of the API functions.
Through its set of functions, the WAPI provides a set of workflow services that a Workflow Enactment Service provides. The WAPI does not assume any specific user interface, but rather it specifically assumes that the user interface of the workflow enabled application, that uses these services, provides its own user interface, that depends solely on the application development environment facilities where it is implemented.
The WFM Engine functions can broadly be classified in the following areas:
· WAPI Connection Functions
· WAPI Process Control Functions
· WAPI Activity Control Functions
· WAPI Process Status Functions
· WAPI Activity Status Functions
· WAPI Worklist Functions
· WAPI Administration Functions
4.1
Design Philosophy
There are a number of design assumptions and constraints that provide a
framework or philosophy for the definition of this specification.
4.2
Design Assumptions
Incremental Set of Functions. It is assumed that as
the WFM technology evolves, likewise the specifications defined in this
document will evolve and will have additions in subsequent versions of this
document.
Strings are defined with buffer sizes allocated in bytes. Strings are assumed to be zero terminated.
The workflow engine may have security restrictions that may cause an error to be returned to a user for some of the API calls.
The specific calls to change state have to be supported by all vendors. The generic state changes are reserved for vendor specific states. In the future, it is expected that a common set of states will evolve.
Each process definition must have a unique ID within an administrative scope.
Each process instance must have a unique ID within an administrative scope.
Each activity instance must have a unique ID within a process instance.
Each work item must have a unique ID within a process instance.
Process Instance ID is unique to the workflow engines from which it is available. It is the responsibility of the workflow engine to ensure a unique identifier within this scope.
4.3
Design Objectives
Ease of Implementation. The API specification must
be easy to implement by a wide range of vendors. This also implies that the
specification will be able to be implemented by multiple vendors in a
reasonably short period of time.
4.4
Defined Terms and Abbreviations
The terms used in this document are defined in the WFM Coalition Glossary.
4.5
Reference Documents
The following documents are associated with this document and should be used as
a reference.
· · WFM Coalition Reference Model
· · WFM Coalition Glossary
· · WFM Coalition WAPI Naming Conventions
4.6
Conformance
A vendor can not claim conformance to this or any other WfMC specification
unless specifically authorized to make that claim by the WfMC. The WfMC grants
this permission only upon the verification of the particular vendor's
implementation of the published specification, according to the conformance
requirements and applicable test procedures defined by the WfMC.
4.7
WAPI Naming Conventions
The Working group has proposed a set of standards for handling the naming
conventions of the different implementation of the Workflow API. These naming
conventions standards are described in the document Workflow Management
Coalition Interface 2 WAPI Naming Conventions (Document Number WFMC-TC-1013).
5.
WAPI Data Types
This section describes the WAPI data types. These data types are used in the
WAPI calls as input and output parameters.
5.1
Basic WAPI Data Types
This subsection contains definitions of the basic Workflow Management types
that are operating system or platform dependent.
typedef char WMTInt8;
typedef short WMTInt16;
typedef long WMTInt32;
typedef unsigned char WMTUInt8;
typedef unsigned short WMTUInt16;
typedef unsigned long WMTUInt32;
typedef WMTInt8 WMTText;
typedef WMTText *WMTPText;
typedef WMTInt8 *WMTPInt8;
typedef WMTInt16 *WMTPInt16;
typedef WMTInt32 *WMTPInt32;
typedef WMTInt8 WMTBoolean;
typedef WMTUInt8 *WMTPointer;
typedef WMTText *WMTPPrivate;
#define WMNULL ((WMTPointer)0)
#define WMFalse 0
#define WMTrue (!WMFalse)
5.2
Other WAPI Data Types
This subsection contains definitions of the Workflow Management types that are
specific to the structures and objects defined in this specification.
Strings in this specification, are assumed to be zero terminated. The maximum string length for names, keywords and identifiers in this specification is 63 characters hosted in a 64 byte text array. The following macro definition specifies this typical size:
#define NAME_STRING_SIZE 64
All strings in this specification are defined as text arrays, such as:
WMTText user_identification[NAME_STRING_SIZE];
Given this, in the example above the string can include up to a maximum of 63 real characters.
In some other cases, the fixed size structures for data reference and unique ids are also defined through the following macro definitions:
#define UNIQUE_ID_SIZE 64
All WAPI function calls have a uniform error return datatype:
typedef struct
{
WMTInt16 main_code;
WMTInt16 sub_code;
} WMTErrRetType;
This data type is shared among all API calls. All other data types are shown along with the WAPI description for each individual call.
This error return datatype is a Int32 word that has two Int16 elements for error returns. The main_code element contains the main error return code, while the sub_code element contains a code that further specifies the nature of the error. For example, the main_code error code WM_INVALID_PROCESS_INSTANCE (see Error Return Codes below), would include in its sub_code set of codes a further, more detailed reason why the process instance is invalid.
This specification assumes that the Coalition will specify a subset of the main_code codes, leaving for vendor specific implementation the remaining main_code codes and the set of sub_code codes to provide extensibility and specialization of error codes.
typedef struct
{
WMTText user_identification[NAME_STRING_SIZE];
// The identification of the workflow participant on whose behalf the Workflow Application will be operating. The value specified may represent a human, a device, etc. This identification is normally used for security checking, accounting, etc.
WMTText password[NAME_STRING_SIZE];
WMTText engine_name[NAME_STRING_SIZE];
// The identification of the WFM Engine to whom the subsequent API calls are to be directed. This information would not be required for some WFM products in the normal case. However, it is required for those Workflow Applications which interact with multiple WFM Engines. This would be a symbolic name which is resolved through a lookup facility.
WMTText scope[NAME_STRING_SIZE];
// Identification of scope for the application. If scope is not relevant, then this field would be empty and ignored.
}WMTConnectInfo;
typedef WMTConnectInfo *WMTPConnectInfo;
typedef struct
{
WMTUInt32 session_id; // locally unique ID for the session
WMTPPrivate pprivate; // pointer to a private structure containing vendor specific information.
}WMTSessionHandle;
typedef WMTSessionHandle *WMTPSessionHandle;
typedef struct
{
WMTInt32 filter_type; // Includes basic types and SQL String
WMTInt32 filter_length; // Length (in bytes) of value
WMTText attribute_name [NAME_STRING_SIZE]
WMTUInt32 comparison; // one of: <, >, =, !=, <=, <=
WMTPText filter_string;
}WMTFilter;
typedef WMTFilter *WMTPFilter;
// The first 255 filter types will be reserved. These will be used for filtering on attributes of process control data and process relevant data. The specific code values for these codes are included in the WFM Coalition Interface 2 WAPI Naming Conventions specification document.
// In this specification there are two types of filters. One type is useful for comparisons with and between attribute values. In this case, the filter_string includes the attribute value that the attribute is compared against. The second type is a more general mechanism in which the filter_string represents the whole argument (typically a full SQL argument). If filter_type is a SQL string, the filter_string will point to a SQL clause with the syntax of a WHERE clause in the SQL 92 standard language specification.
typedef struct
{
WMTUInt32 query_handle;
}WMTQueryHandle;
typedef WMTQueryHandle *WMTPQueryHandle;
typedef struct
{
WMTText wf_participant[NAME_STRING_SIZE];
}WMTWflParticipant;
typedef WMTWflParticipant *WMTPWflParticipant;
typedef struct
{
WMTText proc_def_id[UNIQUE_ID_SIZE];
}WMTProcDefID;
typedef WMTProcDefID *WMTPProcDefID;
typedef struct
{
WMTText activity_id[NAME_STRING_SIZE];
}WMTActivityID;
typedef WMTActivityID *WMTPActivityID;
typedef struct
{
WMTText proc_def_state[NAME_STRING_SIZE];
} WMTProcDefState;
typedef WMTProcDefState *WMTPProcDefState; // pointer to a 63-byte string
typedef struct
{
// This is the minimum list of elements at this time. Future versions to provide extensibility for this structure.
WMTText process_name[NAME_STRING_SIZE];
WMTProcDefID proc_def_id;
WMTProcDefState state;
} WMTProcDef;
typedef WMTProcDef *WMTPProcDef;
typedef struct
{
WMTText proc_inst_id[UNIQUE_ID_SIZE];
}WMTProcInstID;
typedef WMTProcInstID *WMTPProcInstID;
typedef struct
{
WMTText proc_inst_state[NAME_STRING_SIZE];
} WMTProcInstState;
typedef WMTProcInstState *WMTPProcInstState; // pointer to a 63-byte string
typedef struct
{
// This is the minimum list of elements at this time. Future versions to provide extensibility for this structure.
WMTText process_name[NAME_STRING_SIZE];
WMTProcInstID proc_inst_id;
WMTProcDefID proc_def_id;
WMTProcInstState state;
WMTInt32 priority;
WMTWflParticipant proc_participants[20];
//up to 20 63 character long participant identifiers
} WMTProcInst;
typedef WMTProcInst *WMTPProcInst;
typedef struct
{
WMTText activity_inst_id[UNIQUE_ID_SIZE];
}WMTActivityInstID;
typedef WMTActivityInstID *WMTPActivityInstID;
typedef struct
{
WMTText activity_inst_state[NAME_STRING_SIZE];
} WMTActivityInstState;
typedef WMTActivityInstState *WMTPActivityInstState;
typedef struct
{
// This is the minimum list of elements at this time. Future versions to provide extensibility for this structure.
WMTText activity_name[NAME_STRING_SIZE];
WMTActivityInstID activity_inst_id;
WMTProcInstID proc_inst_id;
WMTActivityInstState state;
WMTInt32 priority;
WMTWflParticipant activity_participants[10];
//up to 10 63 character long participant identifiers
} WMTActivityInst;
typedef WMTActivityInst *WMTPActivityInst;
typedef struct
{
WMTText work_item_id[UNIQUE_ID_SIZE];
}WMTWorkItemID;
typedef WMTWorkItemID *WMTPWorkItemID;
typedef struct
{
// This is the minimum list of elements at this time. Future versions to provide extensibility for this structure.
WMTText workitem_name[NAME_STRING_SIZE];
WMTWorkItemID workitem_id;
WMTActivityInstID activity_inst_id;
WMTProcInstID proc_inst_id;
WMTInt32 priority;
WMTWflParticipant participant;
} WMTWorkItem;
typedef WMTWorkItem *WMTPWorkItem;
5.3
Attributes
This specification does not make any assumption about the binding that workflow
applications will make of retrieved attributes and their values. It is up to
the specific application to manage this binding. The API manages attributes as
a set of four elements:
WMTText attribute_name[NAME_STRING_SIZE];
WMTInt32 attribute_type; // type of the attribute
WMTInt32 attribute_length; // length of the attribute value
WMTPText pattribute_value; // pointer to the attribute value
All API calls in this specification that deal with attributes, take each individual element as separate parameter for the call.
The following type definitions are used for attribute name:
typedef WMTText WMTAttrName[NAME_STRING_SIZE];
typedef WMTAttrName *WMTPAttrName;
These attributes are of the kind called Process Control and Process Relevant Data. Some attributes of process instances, activity instances and work items could be: priority, state, start_time, description, instance_name, workflow_participant.
6.
WAPI Error Return Codes
This section describes the minimal set of WAPI error return codes. These error
codes correspond to the main_code element of the WMTErrRetType datatype defined
above. The specific code values for these codes are included in the WFM
Coalition WAPI Naming Conventions specification document.
The minimal set of main_code error return codes are:
WM_SUCCESS
Indicates that the API call completed successfully.
WM_CONNECT_FAILED
Indicates that the WMConnect call failed.
WM_INVALID_PROCESS_DEFINITION
Indicates that the process definition ID that was passed as parameter to an API call was not valid, or it was not recognized by the servicing workflow engine.
WM_INVALID_ACTIVITY_NAME
Indicates that the activity name that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_PROCESS_INSTANCE
Indicates that the process instance ID that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_ACTIVITY_INSTANCE
Indicates that the process instance ID that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_WORKITEM
Indicates that the work item ID that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_ATTRIBUTE
Indicates that the attribute that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_ATTRIBUTE_ASSIGNMENT_FAILED
Indicates that the workflow engine was not able to complete the attribute assignment requested.
WM_INVALID_STATE
Indicates that a state was not valid, or was not recognized by the servicing workflow engine.
WM_TRANSITION_NOT_ALLOWED
Indicates that the state transition requested was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_SESSION_HANDLE
Indicates that the session ID that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_QUERY_HANDLE
Indicates that the query handle ID that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_SOURCE_USER
Indicates that the participant "source user" that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_TARGET_USER
Indicates that the participant "target user" that was passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_INVALID_FILTER
Indicates that the filter structure or values that were passed as parameter to an API call was not valid, or was not recognized by the servicing workflow engine.
WM_LOCKED
Reserved for situations in which the servicing workflow engine implements "locking" of workflow entities (process definitions, process instances, activities, work items, etc.) to indicate that the entity is locked at the moment in which its access is requested.
WM_NOT_LOCKED
Reserved for situations in which the servicing workflow engine implements "locking" of workflow entities (process definitions, process instances, activities, work items, etc.) to indicate that the entity is not locked at the moment in which its access is requested.
WM_NO_MORE_DATA
Indicates that a fetch query call has reached the end of the list of valid entities to be returned. This error return code is used to implement queries of lists of workflow entities, it indicates that all the entities of the list that matched the selection criterion have already been returned.
WM_INSUFFICIENT_BUFFER_SIZE
Indicates that the buffer size that was passed to an API call is insufficient to hold the data that it is supposed to receive.
7.
WAPI Descriptions
This section describes the WAPI calls. They are grouped as follows:
· WAPI Connection Functions
· WAPI Process Control Functions
· WAPI Activity Control Functions
· WAPI Process Status Functions
· WAPI Activity Status Functions
· WAPI Worklist Functions
· WAPI Administration Functions
The specification of the WAPI calls that follows includes a specification of parameters with indications of the direction of data passing:
in for parameters with data being passed to the API from the calling application
out for parameters with data being passed from the API to the calling application.
It should be noted, that in the "C" language interface, parameters that are specified as out require a pointer to be passed from the calling application to the API. The API in turn will return the appropriate data in the space pointed to by the pointer. The specification of these in and out parameters is provided to clarify the specific purpose of these parameters in the calls.
The Coalition WMConnect /WMDisconnect API commands are intended to bound a set of related work by the application using them. When issued, the WMConnect returns a handle whose value is used on all other Coalition API calls. The handle value is unique and relates API calls which are issued between a WMConnect /WMDisconnect pair instance. The WMConnect command allows information to be supplied once and to remain valid until a WMDisconnect occurs.
Information supplied during the WMConnect (see the ConnectInfo structure in the WMConnect call) includes identification information relating to who/what is requesting services from the WFM Engine for use by an authentication service. The structure of the session handle that is returned by the WMConnect call is a pointer to a structure that contains a session ID and another structure pointer containing vendor specific information. (See the Session Handle structure in the WMConnect call.)
For those workflow servers that establish a connection, the session ID and the pointer to the vendor specific information would be returned by the workflow engine. For those workflow servers that do not establish a connection, the session ID would be set to 0, and a pointer to the connection information that was passed in by the user will be stored in the private structure contained in the session handle structure.
Operation between the API and the Engine
The construction of the Coalition API calls are intended to have little impact on the operational structure of how a WFM product supports them. The API calls are considered to be protocol neutral in that once the API boundary is crossed, different types of mechanisms may be employed to deliver the request to the WFM engine. A particular WFM product's method of interacting between the API calls and the WFM Engine functions may be RPC, conversational, messaging (connectedless) or others.
If a messaging mechanism is used by a WFM product, the receipt of a WMConnect may result in the determination of what messaging queue is to be used for interaction between its API support and the WFM engine functions, plus establishing control information to link that queue to subsequent API calls which use a particular handle. If the WFM engine is remote, it may also send a setup type of message to the engine.
If a conversational mechanism is used by a WFM product, and the WFM engine is remote, the receipt of a WMConnect may result in the establishment of a communications session between the code supporting the API calls and the WFM engine.
If a data base is being used, one of the results of the WMConnect may be the establishment of a connection to the appropriate data store facility.
A particular WFM product may choose to accept the WMConnect command, return a handle, and ignore the fact that it occurred.
The above are examples of possible operations performed by different WFM products in support of a WMConnect command. Obviously, more are possible.
In some cases, a product will be required to connect a single workstation to multiple WFM engines. It is possible that multiple WMConnect commands are active concurrently and the subsequent API commands be directed to the correct WFM engine. The WMConnect command may be used to designate a particular engine. The handle returned from the WMConnect command may be used on subsequent API calls to link those which relate to a engine.
The results of a WMDisconnect command is may vary, again depending upon a particular WFM product implementation. Its purpose is to indicate that the application issuing the preceding API calls will no longer be accessing the WFM engine functions within the previous context. In some products, upon receipt of a WMDisconnect command, communications and other resource types may be released.
Application Operation when using the API calls
The operational structure of an application as it relates to the use of the Coalition API calls is affected by the way the API calls are constructed. The current construction of the Coalition API calls result in the code segment of the application making the API call to run in blocked mode. That is, the application will issue an API command and 'wait' for a response from what it perceives as the WFM engine. When making the API call, the application code segment gives up control to the API and does not regain control until the API command is satisfied.
Much of the time, the API commands will be issued due to a workflow participant's direction via the application's End User Interface (EUI). Most of the current API commands are not such that a workflow participant would be interested in making the request, doing something else, and then sometime later (via a process/queue/whatever) viewing the real response to the request. With the request types supported by the API set, it would normally be the case that a workflow participant would want to see the response to the request as soon as possible.
The API calls could be constructed in such a way to allow the application code segment making the API call to run in unblocked mode. That is, to make the API call 'immediate return' rather than waiting for the actual response to the requested action. If this were done, the Coalition would need to define additional functions to support connectedless mode of operation (in some manner, get the asynchronous response when it did arrive and get it to the workflow participant).
The WMConnect / WMDisconnect API commands themselves have nothing to do with the ability of an application to run connected or connectedless as they are now defined.
Synchronous vs Asynchronous Calls
Most API calls in the WAPI call set are synchronous calls. In particular all
the query related API calls are synchronous. Other calls may have some
asynchronous behavior in that the call itself will return synchronously to the
caller program, but the work specified by the call may be executed by the
Workflow Engine at a later time, letting the application proceed. This set of
API calls will not include any Call-Back mechanism to synchronize asynchronous
calls.
7.1.1
WMConnect
WMTErrRetType WMConnect (
in WMTPConnectInfo pconnect_info,
out WMTPSessionHandle psession_handle)
Argument Description
pconnect_info Pointer to structure containing the information required to
create a connection.
psession_handle Pointer to a structure containing information which can be
passed to the WFM Engine on all subsequent API calls which
would identify interactions within the WMConnect /
WMDisconnect bounds, that define a participant's session
interaction with the Engine. These handles are opaque so
that in connectedless environments the handles include
participants identities and passwords rather than session
identification. There will be a special value for a handle
to indicate failure of the function.
ERROR RETURN VALUE
WM_SUCCESS
WM_CONNECT_FAILED
WMTErrRetType WMDisconnect (
in WMTPSessionHandle psession_handle)
WM_INVALID_SESSION_HANDLE
7.2.1
WMOpenProcessDefinitionsList
This command will return a query handle for a list of process definitions that match the specified value for the attribute. The command will also return, optionally, the total count of definitions available. If the count is requested and the implementation does not support it, the command will return a pcount value of -1. If pproc_def_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL process definitions.
(Note: This API does not change the state of process or activity instances per the definition above of Process Control Functions. It is included in this section because it might normally lead to the execution of other API calls which would cause operational state changes.)
WMTErrRetType WMOpenProcessDefinitionsList (
in WMTPSessionHandle psession_handle,
in WMTPFilter pproc_def_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_filter Filter associated with the process definition.
count_flag Boolean flag that indicates if the total count of
definitions should be returned.
pquery_handle Pointer to a structure containing a unique query information.
pcount Total number of process definitions that fulfill the filter
condition.
WM_INVALID_SESSION_HANDLE
WM_INVALID_FILTER
No requirements are assumed to exist with regard to how workflow participant's are identified within the WFM Engine.
WMTErrRetType WMFetchProcessDefinition (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPProcDef pproc_def_buf_ptr)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by the
WMOpenProcessDefinitionsList query command.
pproc_def_buf_ptr Pointer to a buffer area provided by the client application
where the process definition structure will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.2.3
WMCloseProcessDefinitionsList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessDefinitionsList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.2.4
WMOpenProcessDefinitionStatesList
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available states of the process definition that match the filter criterion, in order to offer this list to the application user. For example, process definitions can be in states such as disabled (thus disallowing temporarily the creation of new process definitions), or enabled (thus allowing again the creation of new process definitions based on the named definition). If pproc_def_state_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL states available for the definition.
WMTErrRetType WMOpenProcessDefinitionStatesList (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPFilter pproc_def_state_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTUInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing the unique process
definition ID.
pproc_def_state_filt Filter associated with the process definition state.
er
count_flag Boolean flag that indicates if the total count of
process definition states should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of states for this process definition.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
7.2.5
WMFetchProcessDefinitionState
WMTErrRetType WMFetchProcessDefinitionState (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPProcDefState pproc_def_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by the
WMOpenProcessDefinitionStatesList query command.
pproc_def_state Pointer to a buffer area provided by the client application
where the state name will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.2.6
WMCloseProcessDefinitionStatesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessDefinitionStatesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.2.7
WMChangeProcessDefinitionState
WMTErrRetType WMChangeProcessDefinitionState (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPProcDefState pproc_def_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing a unique process
definition ID.
pproc_def_state Pointer to a structure that contains the name of the
state to change the process definition to.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_STATE
WM_TRANSITION_NOT_ALLOWED
To assign attributes to the process instance, you will make multiple calls to WMAssignProcessInstanceAttribute.
The process instance ID returned by this call is valid and reliable until WMStartProcess is called, at which time it may be reassigned to a new value.
WMTErrRetType WMCreateProcessInstance (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPText pproc_inst_name,
out WMTPProcInstID pproc_inst_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing a unique process
definition ID.
pproc_inst_name Pointer to the name for the process instance created by
this call.
pproc_inst_id Pointer to a structure containing the process instance ID
created by this call.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
Note: The programmer needs to maintain the association between the new process instance ID and the session in order to identify which session they need to connect to for future calls.
WMTErrRetType WMStartProcess (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
out WMTPProcInstID pnew_proc_inst_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the process instance ID
returned by the WMCreateProcessInstance call.
pnew_proc_inst_id Pointer to a structure containing the process instance ID
created by this call. This ID will be valid for the life
of the process instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ATTRIBUTE
No requirements exist with regard to process model type.
WMTErrRetType WMTerminateProcessInstance (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id A pointer to a structure that indicates the process
instance that you want to terminate.
WM_SUCCESS
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
RATIONALE FOR API
To allow a process instances to be terminated.
7.2.11
WMOpenProcessInstanceStatesList
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available states of the process instance that match the filter criterion, in order to offer this list to the application user. If pproc_inst_state_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL states available for the process instance.
WMTErrRetType WMOpenProcessInstanceStatesList (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPFilter pproc_inst_state_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pproc_inst_state_filt Filter associated with the process instance state.
er
count_flag Boolean flag that indicates if the total count of
process instance states should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of states for this process instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
7.2.12
WMFetchProcessInstanceState
WMTErrRetType WMFetchProcessInstanceState (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPProcInstState pproc_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstanceStatesList query command.
pproc_inst_state Pointer to a buffer area provided by the client
application where the state name will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.2.13
WMCloseProcessInstanceStatesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstanceStatesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.2.14
WMChangeProcessInstanceState
Execution of this command will cause the single process instance that is named to be transitioned to a new state. In this case, the meaning of all states is dependent upon the particular WFM Engine implementation. This command will set the state attribute of the process instance to a state such as suspended or in-progress.
WMTErrRetType WMChangeProcessInstanceState (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPProcInstState pproc_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing a unique process
instance ID.
pproc_inst_state Pointer to a structure that contains the name of the
process state that you want to change the instance to.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_STATE
WM_TRANSITION_NOT_ALLOWED
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available attributes that can be assigned to the process instance, in order to offer this list to the application user. Attribute values can be obtained as well provided that a buffer of enough size is passed in the fetch call. Individual attribute values can also be retrieved with the WMGetProcessInstanceAttributeValue call. If pproc_inst_attr_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL attributes available for the process instance.
WMTErrRetType WMOpenProcessInstanceAttributesList (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPFilter pproc_inst_attr_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pproc_inst_attr_filt Filter associated with the process instance attributes.
er
count_flag Boolean flag that indicates if the total count of
process instance attributes should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of attributes for this process instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
7.2.16
WMFetchProcessInstanceAttribute
WMTErrRetType WMFetchProcessInstanceAttribute (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstanceAttributesList query command.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.2.17
WMCloseProcessInstanceAttributesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstanceAttributesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.2.18
WMGetProcessInstanceAttributeValue
WMTErrRetType WMGetProcessInstanceAttributeValue (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer to be filled.
WM_INVALID_SESSION_HANDLE
WM_INVALID_ATTRIBUTE
WM_INSUFFICIENT_BUFFER_SIZE
7.2.19
WMAssignProcessInstanceAttribute
This command changes the value of an attribute of a process instance. Attributes of process instances are of the kind called Process Control and Process Relevant Data. These attributes are specified as quadruplets of name, type, length and value.
WMTErrRetType WMAssignProcessInstanceAttribute (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPAttrName pattribute_name,
in WMTInt32 attribute_type,
in WMTInt32 attribute_length,
in WMTPText pattribute_value)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the process instance
ID that indicates the process for which the attribute
will be assigned.
pattribute_name Pointer to the name of the attribute.
attribute_type Type of the attribute.
attribute_length Length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ATTRIBUTE
WM_ATTRIBUTE_ASSIGNMENT_FAILED
RATIONALE FOR API
For various business reasons, certain pieces of work are required to be handled
with particular attributes (e.g. priority) relative to other pieces of like
work. This command allows attributes to be set on those pieces of work. In
some cases, these attributes are determined by the WFM product based upon data
values existing during process execution. The setting of these attributes
through the use of this API is provided to cover the cases where applications
set them upon requests from users.
7.3
WAPI Activity Control Functions
Activity Control Functions can be defined as those which change the operational
state of one or more activity instances. These API calls are intended for use
by the WFM end user. However, some of the API calls, or parameters within some
of the API calls, may affect multiple users and would normally be restricted to
the use of a process administrator.
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available states of the activity instance that match the filter criterion, in order to offer this list to the application user. If pact_inst_state_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL states available for the activity instance.
WMTErrRetType WMOpenActivityInstanceStatesList (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPActivityInstID pactivity_inst_id,
in WMTPFilter pact_inst_state_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pproc_inst_id Pointer to a structure containing a unique process
instance ID.
pactivity_inst_id Pointer to a structure containing the unique activity
instance ID.
pact_inst_state_filte Filter associated with the activity instance state.
r
count_flag Boolean flag that indicates if the total count of
activity instance states should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of states for this activity instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ACTIVITY_INSTANCE
7.3.2
WMFetchActivityInstanceState
WMTErrRetType WMFetchActivityInstanceState (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPActivityInstState pactivity_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pquery_handle Identification of the specific query handle returned
by the WMOpenActivityInstanceStatesList query command.
pactivity_inst_state Pointer to a buffer area provided by the client
application where the state name will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.3.3
WMCloseActivityInstanceStatesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenActivityInstanceStatesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.3.4
WMChangeActivityInstanceState
For example, this command will be used to change the state of an activity instance to suspended. This command can be used afterwards to change the state of the activity instance back to in-progress. The implementation documentation will provide the names and semantics of the supported activity states for a particular implementation.
WMTErrRetType WMChangeActivityInstanceState (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPActivityInstID pactivity_inst_id,
in WMTPActivityInstState pactivity_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pproc_inst_id Pointer to a structure containing a unique process
instance ID.
pactivity_inst_id Pointer to structure containing the activity instance
ID of the activity whose state to change.
pactivity_inst_stat Pointer to a structure that contains the name of the
e activity instance state that you want to change to.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ACTIVITY_INSTANCE
WM_INVALID_STATE
WM_TRANSITION_NOT_ALLOWED
Each activity instance must have a unique ID within a process instance.
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available attributes that can be assigned to the activity instance, in order to offer this list to the application user. Attribute values can be obtained as well provided that a buffer of enough size is passed in the fetch call. Individual attribute values can also be retrieved with the WMGetActivityInstanceAttributeValue call. If pact_inst_attr_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL attributes available for the activity instance.
WMTErrRetType WMOpenActivityInstanceAttributesList (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPActivityInstID pactivity_inst_id,
in WMTPFilter pact_inst_attr_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about
the context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pactivity_inst_id Pointer to a structure containing the unique activity
instance ID.
pact_inst_attr_filt Filter associated with the activity instance
er attributes.
count_flag Boolean flag that indicates if the total count of
activity instance attributes should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of attributes for this activity instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ACTIVITY_INSTANCE
7.3.6
WMFetchActivityInstanceAttribute
WMTErrRetType WMFetchActivityInstanceAttribute (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenActivityInstanceAttributesList query command.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.3.7
WMCloseActivityInstanceAttributesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenActivityInstanceAttributesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.3.8
WMGetActivityInstanceAttributeValue
WMTErrRetType WMGetActivityInstanceAttributeValue (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPActivityInstID pactivity_inst_id,
in WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pactivity_inst_id Pointer to a structure containing the unique activity
instance ID.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer to be filled.
WM_INVALID_SESSION_HANDLE
WM_INVALID_ATTRIBUTE
WM_INSUFFICIENT_BUFFER_SIZE
7.3.9
WMAssignActivityInstanceAttribute
This command changes the value of the attributes of a activity instance. These attributes of activity instances are of the kind called Process Control and Process Relevant Data. These attributes are specified as quadruplets of name, type, length and value.
WMTErrRetType WMAssignActivityInstanceAttribute (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPActivityInstID pactivity_inst_id,
in WMTPAttrName pattribute_name,
in WMTInt32 attribute_type,
in WMTInt32 attribute_length,
in WMTPText pattribute_value)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pactivity_inst_i Pointer to a structure containing the activity instance
d identification for which the attribute will be assigned.
pattribute_name Pointer to the name of the attribute.
attribute_type Type of the attribute.
attribute_length Length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ACTIVITY_INSTANCE
WM_INVALID_ATTRIBUTE
WM_ATTRIBUTE_ASSIGNMENT_FAILED
7.4
WAPI Process Status Functions
The process status functions are intended to provide a view of the work done, work to be done, work associated with a workflow participant or group of workflow participants, etc. The status queries may be requested by a normal workflow participant or may be requested by a manager or process administrator who wishes to view the progress of work within his/her domain.
The status API calls are structured such that they provide views ranging from a view of global work to a view of work within a single process instance. These views are as follows:
1 All the process instances WM(Open+Fetch+Close)ProcessInstancesL associated with a process ist definition. 2 A view of a single process WMGetProcessInstance instance.
In addition, various filters (parameters) are provided with the calls such that the information returned may be tailored.
The API functions associated with these API calls are described in this section.
7.4.1
WMOpenProcessInstancesList
This command will be used to set up a wide variety of queries of process instances. For example, this command will be used to set up the query for a list of completed or suspended process instances. If pproc_inst_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL accessible process instances.
WMTErrRetType WMOpenProcessInstancesList (
in WMTPSessionHandle psession_handle,
in WMTPFilter pproc_inst_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_filter Pointer to a structure containing the information for
this request.
count_flag Boolean flag that indicates if the total count of process
instances should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of process instances that fulfill the filter
condition.
WM_INVALID_SESSION_HANDLE
WM_INVALID_FILTER
WMTErrRetType WMFetchProcessInstance (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPProcInst pproc_inst_buf_ptr)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstancesList query command.
pproc_inst_buf_pt Pointer to a buffer area provided by the client
r application where the set of process instances will be
placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.4.3
WMCloseProcessInstancesList
WMTErrRetType WMCloseProcessInstancesList (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenProcessInstancesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WMTErrRetType WMGetProcessInstance (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
out WMTPProcInst pproc_inst)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to the process instance identification.
pproc_inst Pointer to a structure containing the requested process
instance information. Includes the state and other
attributes of the process instance.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
The process status functions are intended to provide a view of the work done, work to be done, work associated with a workflow participant or group of workflow participants, etc. The status queries may be requested by a normal workflow participant or may be requested by a manager or process administrator who wishes to view the progress of work within his/her domain.
The status API calls are structured such that they provide views ranging from a view of global work to a view of work within a single activity instance. These views are as follows:
1 All the activity instances WM(Open+Fetch+Close)ActivityInstances associated to a process definition List or instance 2 A view of a single activity within WMGetActivityInstance a process instance.
In addition, various filters (parameters) are provided with the calls such that the information returned may be tailored.
The API functions associated with these API calls are described in this section.
7.5.1
WMOpenActivityInstancesList
This command will be used to set up a wide variety of queries of activity instances. For example, this command will be used to set up the query for a list of completed or suspended activity instances. If pactivity_inst_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL accessible activity instances.
WMTErrRetType WMOpenActivityInstancesList (
in WMTPSessionHandle psession_handle,
in WMTPFilter pactivity_inst_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pactivity_inst_filt Pointer to a structure containing the information for
er this request.
count_flag Boolean flag that indicates if the total count of
activity instances should be returned.
pquery_handle Pointer to a structure containing a unique query
information returned by this function.
pcount Total number of activity instances that fulfill the
filter condition.
WM_INVALID_SESSION_HANDLE
WM_INVALID_FILTER
WMTErrRetType WMFetchActivityInstance (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPActivityInst pactivity_inst)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by the
WMOpenActivityInstancesList query command.
pactivity_inst Pointer to a buffer area provided by the client application
where the set of activity instances will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
WMTErrRetType WMCloseActivityInstancesList (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenActivityInstancesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WMTErrRetType WMGetActivityInstance (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPActivityInstID pactivity_inst_id,
out WMTPActivityInst pactivity_inst )
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the process instance
identification.
pactivity_inst_id Pointer to a structure containing the identification of the
activity instance.
pactivity_inst Pointer to a structure containing the activity instance
information.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_ACTIVITY_INSTANCE
The WAPI worklist API calls provide workflow participants access to information about work to which they have been assigned. As described by the WFM Coalition reference model, a process consists of a set of activities connected in such a way to control the sequencing of application invocation. An activity is associated with one or more applications to be invoked and also, during run time, is associated with the person(s) who has been assigned to do the work. Depending upon a WFM product's implementation, a workflow participant may be assigned one or more pieces of work at any one time. Each piece of work assigned to a workflow participant is called a `work item' and the collection of all work items assigned to a workflow participant is called that workflow participant's `worklist'.
(Note: To clarify the difference between an `activity' and a `work item' the following discussion is included. When a process is being defined (build time), an `activity' is the construct used to define a piece of work to be done. It serves as a type of anchor point for further descriptions of that work to be done (i.e., the name of the application to be invoked, possibly a reference to skills needed to do the work, a symbolic name denoting the network address where the application is to be executed, etc.). During run time, when the activity is ready to be executed and one or more candidate persons are assigned to do the work, a work item is created and placed on that person(s) worklist. So, even though an activity and a work item both represent a piece of work, they come into existence at different points in time, there may be more than one work item for an activity and some operational characteristics may be different.)
A worklist then is defined as: the result of an implementation-defined query against the work item space. It is a list of work items and a work item is one element in a worklist.
The API calls in this section exist for the manipulation of work items and
worklists.
7.6.1
WMOpenWorkList
A query handle will be returned for the list of work items that match the specified value for the attribute. The command will also return, optionally, the total count of work items available. If the count is requested and the implementation does not support it, the command will return a pcount value of -1. If pworklist_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL accessible work items.
WMTErrRetType WMOpenWorkList (
in WMTPSessionHandle psession_handle,
in WMTPFilter pworklist_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pworklist_filter Pointer to a structure containing the filter information for
this request.
count_flag Boolean flag that indicates if the total count of work items
should be returned.
pquery_handle Pointer to a structure containing a unique query information
returned by this function.
pcount Total number of work items that fulfill the filter condition.
WM_INVALID_SESSION_HANDLE
WM_INVALID_FILTER
WMTErrRetType WMFetchWorkItem (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPWorkItem pwork_item)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by the
WMOpenWorkList query command.
pwork_item Pointer to a buffer area provided by the client application
where the set of work item will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
WMTErrRetType WMCloseWorkList (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenWorkList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.6.4
WMGetWorkItem
This command operates on a single work item basis. This command execution need not imply that the work item is reserved or locked.
WMTErrRetType WMGetWorkItem (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id,
out WMTPWorkItem pwork_item )
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the work item
identification for this request.
pwork_item Pointer to a structure containing the work item being
returned by this function.
WM_SUCCESS
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_WORKITEM
To change a work item's attributes, multiple calls to WMAssignWorkItemAttribute.
WMTErrRetType WMCompleteWorkItem (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the work item
identification for this request.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_WORKITEM
Typically, a work item will correspond to an activity instance. However the API should allow the existence of multiple work items per activity, executed one at a time. So completion of a work item does not necessarily mean that all work for an activity instance is completed. Completion of a work item could trigger the start of the next work item that corresponds to that activity instance. The Workflow Engine will determine the next work item based on the process definition.
(Note: Possible future releases of the API specification may provide for an entire worklist to be reassigned in total.)
WMTErrRetType WMReassignWorkItem (
in WMTPSessionHandle psession_handle,
in WMTPWflParticipant psource_user,
in WMTPWflParticipant ptarget_user,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
psource_user The identification of a workflow participant from which work
is to be reassigned.
ptarget_user The identification of the workflow participant to whom work
is to be assigned.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the work item
identification being reassigned.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_WORKITEM
WM_INVALID_SOURCE_USER
WM_INVALID_TARGET_USER
With the reassignment API, workflow participants in that department may reassign work to themselves after they finish a current work item and become available for more work. This creates a possible de facto people load balancing scheme.
One of the uses of this API, together with the corresponding fetch and close calls is to allow a workflow application to query the Workflow Engine for the available attributes that can be assigned to the work item, in order to offer this list to the application user. Attribute values can be obtained as well provided that a buffer of enough size is passed in the fetch call. Individual attribute values can also be retrieved with the WMGetWorkItemAttributeValue call. If pwork_item_attr_filter is NULL, then the function, with the corresponding fetch calls will return the list of ALL attributes available for the work item.
WMTErrRetType WMOpenWorkItemAttributesList (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id,
in WMTPFilter pwork_item_attr_filter,
in WMTBoolean count_flag,
out WMTPQueryHandle pquery_handle,
out WMTPInt32 pcount)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the unique work item
ID.
pwork_item_attr_filt Filter associated with the work item attributes.
er
count_flag Boolean flag that indicates if the total count of work
item attributes should be returned.
pquery_handle Pointer to a structure containing a unique query
information.
pcount Total number of attributes for this work item.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_WORKITEM
7.6.8
WMFetchWorkItemAttribute
WMTErrRetType WMFetchWorkItemAttribute (
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle,
out WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by
the WMOpenWorkItemAttributesList query command.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
WM_NO_MORE_DATA
7.6.9
WMCloseWorkItemAttributesList
in WMTPSessionHandle psession_handle,
in WMTPQueryHandle pquery_handle)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pquery_handle Identification of the specific query handle returned by the
WMOpenWorkItemAttributesList query command.
WM_INVALID_SESSION_HANDLE
WM_INVALID_QUERY_HANDLE
7.6.10
WMGetWorkItemAttributeValue
WMTErrRetType WMGetWorkItemAttributeValue (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id,
in WMTPAttrName pattribute_name,
out WMTPInt32 pattribute_type,
out WMTPInt32 pattribute_length,
out WMTPText pattribute_value,
in WMTInt32 buffer_size)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the unique work item ID.
pattribute_name Pointer to the name of the attribute.
pattribute_type Pointer to the type of the attribute.
pattribute_length Pointer to the length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
buffer_size Size of the buffer to be filled.
WM_INVALID_SESSION_HANDLE
WM_INVALID_ATTRIBUTE
WM_INSUFFICIENT_BUFFER_SIZE
7.6.11
WMAssignWorkItemAttribute
WMTErrRetType WMAssignWorkItemAttribute (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id,
in WMTPWorkItemID pwork_item_id,
in WMTPAttrName pattribute_name,
in WMTInt32 attribute_type,
in WMTInt32 attribute_length,
in WMTPText pattribute_value)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the unique process
instance ID.
pwork_item_id Pointer to a structure containing the work item ID for which
an attribute will be added or changed.
pattribute_name Pointer to the name of the attribute.
attribute_type Type of the attribute.
attribute_length Length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
WM_INVALID_WORKITEM
WM_INVALID_ATTRIBUTE
WM_ATTRIBUTE_ASSIGNMENT_FAILED
7.7
WAPI Administration Functions
The set of administration functions provide the functionality needed to perform
administration and maintenance functions of a workflow system. This set
includes the minimal services contemplated for this client application
interface. The set includes functions to change state of a set of process or
activity instances, terminating and aborting process instances, and for
assigning attributes to a set of process and activity instances.
7.7.1
WMChangeProcessInstancesState
Execution of this command will cause a set of process instances of the named process definition change their state. If the filter pointer pproc_inst_filter is NULL, then the command is applied to all process instances. Specific state names and their semantics are dependent upon the particular WFM Engine implementation.
This call will be executed when a set of process instances of a process must have a new state, such as suspended, disabled or enabled. Specific state names and semantics must be included in implementation documentation.
Since this command operates on a set of process instances of a named process definition, it is expected to be issued by a person having the authority to do so. The scope of this operation may be different depending on the vendor's implementation.
WMTErrRetType WMChangeProcessInstancesState (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPFilter pproc_inst_filter,
in WMTPProcInstState pproc_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing a unique process
definition ID.
pproc_inst_filter Pointer to a structure containing the filter information
for this request.
pproc_inst_state An ID that indicates the process state that you want to
change to.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_FILTER
WM_INVALID_STATE
WM_TRANSITION_NOT_ALLOWED
Each process definition must have a unique ID within an administrative scope.
WMTErrRetType WMChangeActivityInstancesState (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPActivityID pactivity_def_id,
in WMTPFilter pact_inst_filter,
in WMTPActivityInstState pactivity_inst_state)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing a unique process
definition ID.
pactivity_def_id Pointer to the activity definition ID.
pact_inst_filter Pointer to a structure containing the filter information
for this request.
pactivity_inst_sta An ID that indicates the activity instance state that you
te want to change to.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_ACTIVITY_NAME
WM_INVALID_FILTER
WM_INVALID_STATE
WM_TRANSITION_NOT_ALLOWED
Each activity must have a unique ID within a process definition.
WMTErrRetType WMTerminateProcessInstances (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPFilter pproc_inst_filter)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing the process definition
for which all process instances are to be terminated.
pproc_inst_filter Pointer to a structure containing the filter information
for this request.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_FILTER
7.7.4
WMAssignProcessInstancesAttribute
This command changes the value of the attribute of a process instance. These attributes of process instances are of the kind called Process Control or Process Relevant Data.
WMTErrRetType WMAssignProcessInstancesAttribute (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPFilter pproc_inst_filter,
in WMTPAttrName pattribute_name,
in WMTInt32 attribute_type,
in WMTInt32 attribute_length,
in WMTPText pattribute_value)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing the process definition ID
for which the attribute of all process instances will be
changed.
pproc_inst_filter Pointer to a structure containing the filter information
for this request.
ppattribute_name Pointer to the name of the attribute.
attribute_type Type of the attribute.
attribute_length Length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_FILTER
WM_INVALID_ATTRIBUTE
7.7.5
WMAssignActivityInstancesAttribute
WMTErrRetType WMAssignActivityInstancesAttribute (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPActivityID pactivity_def_id,
in WMTPFilter pact_inst_filter,
in WMTPAttrName pattribute_name,
in WMTInt32 attribute_type,
in WMTInt32 attribute_length,
in WMTPText pattribute_value)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing the process definition
ID. In the case that the attribute will be changed for all
activity instances that correspond to the process
definition. This parameter will be NULL otherwise.
pactivity_def_id Pointer to a structure containing the activity definition
identification for which the attribute will be assigned.
pact_inst_filter Pointer to a structure containing the filter information
for this request.
pattribute_name Pointer to the name of the attribute.
attribute_type Type of the attribute.
attribute_length Length of the attribute value.
pattribute_value Pointer to a buffer area provided by the client
application where the attribute value will be placed.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_ACTIVITY_NAME
WM_INVALID_FILTER
WM_INVALID_ATTRIBUTE
7.7.6
WMAbortProcessInstances
WMTErrRetType WMAbortProcessInstances (
in WMTPSessionHandle psession_handle,
in WMTPProcDefID pproc_def_id,
in WMTPFilter pproc_inst_filter)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_def_id Pointer to a structure containing the process definition
for who all processes instances is being aborted.
pproc_inst_filter Pointer to a structure containing the filter information
for this request.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_DEFINITION
WM_INVALID_FILTER
WMTErrRetType WMAbortProcessInstance (
in WMTPSessionHandle psession_handle,
in WMTPProcInstID pproc_inst_id)
Argument Name Description
psession_handle Pointer to a structure containing information about the
context for this action.
pproc_inst_id Pointer to a structure containing the process instance being
aborted.
WM_INVALID_SESSION_HANDLE
WM_INVALID_PROCESS_INSTANCE
8.
Appendix A
8.1
Additional API Areas
The WFM Coalition API specification work will address the following areas. It
will be determined whether API calls should be created for these areas or
whether they are the sole domain of particular WFM product implementations.
8.1.1
WFM Data API calls
The types of data that applications need to manipulate through this API
specification are process control data, process relevant data, and application
data. The current specification addresses the access to these data through the
definition and manipulation of attributes of processes, activities and work
items. It is currently believed that some additional new API calls or
parameter additions to existing API calls will be required for complete data
manipulation.
8.1.2
Ad hoc activities
In a future release of API specifications, the API working group will consider
the functionality to allow applications to add activities to an instance of a
process that are not part of its definition. These ad-hoc additions will be
done on an instance basis.
· Purging
· Backup
· Archiving
· Download and Upload instances (for remote users)
8.1.4
Names and Roles
The API working group believes that a Workflow Engine should also provide
services for definition, assignment, mapping and maintenance of roles and names
(identities). The working group also believes that these services should be
provided through interface 5 as well.
8.2
Additional Issues
The WFM Coalition API specification work will be expanded to take care of the
following issues for future releases.
8.2.1
Error reporting and control
All WAPI function calls have a uniform error return datatype. This data type is
shared among all API calls. This specification assumes that the Coalition will
specify a subset of the main error return codes, leaving for vendor specific
implementation the remaining main error return codes and the set of subcode
codes to provide extensibility and specialization of error codes. (See section
WAPI Data Types, and WAPI Error Return Codes sections).
8.2.2
Synchpoint processing
Synchpoint processing deals with recoverability. The API working group
believes that this area is extremely important to WFM exploiters. However, it
is also believed that it would be one of the more difficult areas to deal with
in terms of member agreement. Work in this area is being deferred to the
second release of the API specifications.
8.2.3
Security
The current version of the WFM API specification does not include any specific
requirements or provisions for security mechanisms, except for the inclusion of
user password in the WMTConnectInfo structure. Implementation of
security mechanisms are left up to the specific implementations.
8.2.4
Locking
The current version of the WFM API specification does not include any specific
requirements or provisions for locking mechanisms. Implementation of locking
mechanisms are left up to the specific implementations.
8.2.5
Process Integrity
The current version of the WFM API specification does not include any specific
requirements or provisions for mechanisms to guarantee process integrity.
Implementation of process integrity mechanisms are left up to the specific
implementations.
9.
Appendix B: Object Bindings
This chapter provides a specification of the Workflow Application Client
interface in terms of objects. An abstract object model is described and
bindings to OLE and OMG IDL are defined.
9.1
Abstract Object Definition
The following diagram shows the primary objects used in the definition of the
Workflow Application Client interface.
The WorkflowServer provides the context for communication with the Workflow Enactment Service. It allows for filtered queries on objects owned by the specific Enactment Service. An executable workflow model itself is represented by the ProcessDefinition ; the Process Definition serves as a Factory for creating instances of the Workflow Model that are enacted by the Workflow Management System. To execute a specific process, a ProcessInstance of the ProcessDefinition is created. During execution of the ProcessInstance, the Enactment Service creates instances (ActivityInstance) of the Activity Definitions contained in the Process Definition. Assignment of an activity instance to a participant creates a WorkItem.
The next diagram shows the auxiliary constructs that are used to complete the Object Model.
A set of standardized Attributes is defined for each of the objects - attributes specific to a particular Enactment Service or user-defined attributes that determine the specifics of a Workflow object in a particular Workflow Model. Access to filtered lists of objects owned by the Enactment Service is managed via Collection-type interfaces; Filter objects support definition of selection criteria for those lists.
Workflow Object Collections are realized as OLE-Collections in the OLE binding;
in the OMG IDL binding an Iterator-type interface is defined for each of the
fundamental Workflow Object interfaces.
9.1.1
Mapping WAPI to the OLE and IDL Bindings
The following table describes how the ingredients of the Common Object Model
described above map to the WAPI constructs defined in this specification.
WAPI Element OLE Object IDL Interface
WMTSession WorkflowApplicationServer Server
WMTFilter Filter Filter
WMTQueryHandle OLE-Collection ProcessDefinitionsList
ProcessInstancesList
ActivityInstancesList
WorkList AttributeList
WMTProcessDefinition ProcessDefinition ProcessDefinition
WMTProcessInstance ProcessInstance ProcessInstance
WMTActivityInstace ActivityInstance ActivityInstance
WMTWorkItem WorkItem WorkItem
WMTAttributeName Attribute Attribute
WMTAttributeType
WMTAttributeLength
WMTAttributeValue
9.2
OLE Automation Binding
This appendix describes the OLE automation binding for the Workflow Management
Coalition Interface 2 (WAPI2). It is based on:
· the WAPI specified in this document, and
· Microsoft Visual Basic 4.0, Professional Features, Creating OLE Servers, Chapter 3, Standards and Guidelines
This binding has two goals:
1. To accurately reflect the functionality specified by WAPI2.
2. To conform to the standards and guidelines for OLE automation interfaces.
Note that this version of the binding does not yet include the "entitiy"
functions.
9.2.1
Expressing WAPI2 as an OLE Automation Interface
WAPI2 is defined in terms of data structures and functions. An OLE automation
interface consists of object classes, each with properties and methods. The
OLE automation binding for WAPI2 was derived using the following rules:
1. Define an OLE automation object class for each WAPI2 data structure. However, if a WAPI2 data structure consists of a single WMTText field, use the OLE automation String class.
2. Define a read-only OLE automation property for each field in each WAPI2 data structure, on the object class corresponding to the data structure.
3. For each WAPI2 function, define a method on the appropriate object class. Omit the session handle parameter from the methods (except for the Server methods).
4. Use OLE automation collections for each Open/Fetch/Close...List combination of functions, and for fields in data structures that hold multiple values (e.g. participants).
5. Errors are reported via exceptions.
9.2.1.1
Object Classes
The OLE automation binding defines an OLE automation object (class) for each
WAPI2 data structure. For example, WAPI2 defines a process instance data
structure as follows:
typedef struct
{
// This is the minimum list of elements at this time. Future versions to provide extensibility for this structure.
WMTText process_name[NAME_STRING_SIZE];
WMTProcInstID proc_inst_id;
WMTProcDefID proc_def_id;
WMTProcInstState state;
WMTInt32 priority;
WMTText data_reference[DATA_REFERENCE_SIZE];
// private element containing vendor specific information
WMTWflParticipant proc_participants[20];
//up to 20 63 character long participant identifiers
} WMTProcInst;
The OLE automation binding defines a ProcessInstance object class with properites Name, ID, ProcessDefinitionID, State, Priority, DataReference, and Participants. This ProcessInstance object class defines Start and Terminate methods, corresponding to the WMStartProcess and WMTerminateProcessInstance WAPI2 functions.
The table below lists the object classes in the WAPI2 OLE automation binding, and the corresponding WAPI2 data structures. Note that there are exceptions to the rules stated above. There is no ConnectionInfo object class - the information is passed as separate parameters to the Connect method of the Server class. There is an Attribute object class - its properties are passed as separate parameters in the WAPI2 attribute functions.
OLE Automation Object WAPI 2 Data Type
Server WMTSessionHandle
WMTConnectInfo
Filter WMTFilter
Collection WMTQueryHandle
ProcessDefinition WMTProcDefID
ProcessInstance WMTProcInst
ActivityInstance WMTActivityInst
WorkItem WMTWorkItem
Attribute
String WMTWflParticipant
WMTProcDefState
WMTProcInstState
Server
Process Definitions
States
Process Instances
Attributes
Participants
States
Activity Instances
Attributes
Participants
States
Work Items
Attributes
Participant
Filter
WAPI2 requires a program to first obtain a session handle, and then use it to
get process, activity, and work item handles. In the OLE automation binding,
Server and Filter are the top level objects. The Server object class has
methods for listing process definitions, process instances, activity instances,
and work items.
9.2.1.3
Collections and Queries
WAPI2 supports several retrieval operations that return multiple values:
· a list of process definitions, process instances, activity instance, or work items,
· the states of a process definition, process instance, or activity instance
· the attributes of a process instance, activity instance, or work item
For each such retrieval operation, WAPI2 defines three functions:
· WMOpen...List
· WMFetch...
· WMClose...List
The open functions take a filter parameter. The fetch functions are used to iterate through the values retrieved.
OLE automation uses the Collection object class to navigate such one-to-many relationships in the object hierarchy. The Server object class has list methods which take a Filter object as a parameter and return a collection of ProcessDefinition, ProcessInstance, ActivityInstance, or WorkItem objects. The ProcessDefinition, ProcessInstance, and ActivityInstance object classes have a States property whose value is a collection of states. . The ProcessInstance, ActivityInstance, and WorkItem object classes have an Attributes property whose value is a collection of attributes. These properties have a Filter parameter.
The Collection object class has a Count property (the number of elements in the collection) and provides methods for iterating through its elements. For example, here is the VBA code to populate a list box with a user's work items:
Dim mySession As Session
Dim myWorkList As Filter
Dim myWorkItem As WorkItem
Set mySession = CreateObject("WAPI2.Session")
mySession.Connect(...)
For Each myWorkItem In Session.ListWorkItems(myWorkList)
ListBox.AddItem myWorkItem.Name
Next myWorkItem
The ProcessDefinition, ProcessInstance, ActivityInstance, and WorkItem classes
each have collection-valued properties for their states, attributes, and
participants. The elements of the state and participant collections are
strings. The elements of the attribute collections are Attribute objects,
which have two properties: Name and Value. The Value property is expressed as
an OLE automation Variant, which provides methods for determining its data type
and length.
9.2.1.4
Exceptions
OLE automation supports exceptions. OLE automation servers can report errors
by raising an exception rather than returning an error code. This allows
chaining calls to an OLE automation interface in a single expression. For
example, the following expression
WorkItem.ProcessInstance.ProcessDefinition.Name
makes three calls to the OLE automation interface to return the name of the process definition for the process instance that contains the work item. These expressions commonly appear in programs or macros that call an OLE automation interface. Any one of the calls could encounter an error, which would be reported to the calling program through an exception.
The OLE automation binding for WAPI2 uses exceptions to report errors. The
exception object carries a text description of the error with it. The Server
object also has ErrorCode and ErrorSubCode properties. When a program calls
the WAPI2 OLE automation interface, and the server encounters an error, it sets
the Server properties to the error codes in the WMTErrRetType data structure,
and raises an exception.
9.2.2
Server
The Server object class corresponds to the WMTSessionHandle data type. Server
objects are externally creatable. A program must successfully call the Connect
method on a Server object before it can be used to access other objects.
9.2.2.1
Properties
A Server object has the following properties:
Name Type Description ErrorCode Integer WMTErrRetType.main_code ErrorSubCode Integer WMTErrRetType.sub_code
These properties are read-only. They are set when the OLE automation interface
raises an exception.
9.2.2.2
Methods
A Server object has the following methods:
Signature Description Connect in String User WMConnect in String Password Disconnect WMDisconnect Collection WMOpenProcessDefinitionsList ListProcessDefinitions in Filter ProcDefFilter Collection ListProcessInstances WMOpenProcessInstancesList in Filter ProcInstFilter ProcessInstance WMGetProcessInstance GetProcessInstance in String ProcInstID Collection ListActivityInstances WMOpenActivityInstancesList in Filter ActivityInstFilter ActivityInstance WMGetActivityInstance GetActivityInstance in String ProcInstID in String ActivityInstID Collection ListWorkItems in WMOpenWorkItemsList Filter WorkItemFilter WorkItem GetWorkItem in WMGetWorkItem String ProcInstID in String WorkItemID
Connect (
in String User,
in String Password)
Argument Description (WMConnect Argument) User pconnect_info.user_identification Password pconnect_info.password
Disconnect ()
9.2.2.5
ListProcessDefinitions
This method is the binding for the WMOpenProcessDefinitionsList
function.
Collection ListProcessDefinitions (
in Filter ProcDefFilter)
Argument Description (WMOpenProcessDefinitionsList Argument) ProcDefFilter pproc_def_filter Collection pquery_handle
Collection ListProcessInstances (
in Filter ProcInstFilter)
Argument Description (WMOpenProcessInstancesList Argument) ProcInstFilter pproc_inst_filter Collection pquery_handle
ProcessInstance GetProcessInstance (
in String ProcInstID)
Argument Description (WMGetProcessInstance Argument) ProcInstID pproc_inst_id ProcessInstance pproc_inst
Collection ListProcessInstances (
in Filter ActivityInstFilter)
Argument Description (WMActivityInstancesList Argument) ActivityInstFilte pactivity_inst_filter r Collection pquery_handle
ActivityInstance GetActivityInstance (
in String ProcInstID,
in String ActivityInstID)
Argument Description (WMGetActivityInstance Argument) ProcInstID pproc_inst_id ActivityInstID pactivity_inst_id ActivityInstance pactivity_inst
Collection ListWorkItems (
in Filter WorkListFilter)
Argument Description (WMOpenWorkList Argument) WorkListFilter pworklist_filter Collection pquery_handle
WorkItem GetWorkItem (
in String ProcInstID,
in String WorkItemID)
Argument Description (WMGetWorkItem Argument) ProcInstID pproc_inst_id WorkItemID pwork_item_id WorkItem pwork_item
Name Type Description Type Integer WMTFilter.filter_type Length Integer WMTFilter.filter_length AttributeName String WMTFilter.attribute_name Comparison Integer WMTFilter.comparison FilterString String WMTFilter.filter_string
Name Type Description ID String WMTProcDefId.proc_def_id States Collection WMOpenProcessDefinitionStatesList
All of these properties are read-only. The States property takes a Filter
parameter.
9.2.4.2
Methods
A ProcessDefinition object has the following methods:
Signature Description ProcessInstance CreateInstance WMCreateProcessInstance ChangeInstancesState in WMChangeProcessInstancesState Filter InstanceFilter in String InstanceState ChangeActivityInstancesState WMChangeActivityInstancesState in String ActivityDefinitionID in Filter InstanceFilter in String InstanceState TerminateInstances in Filter WMTerminateProcessInstances InstanceFilter AssignInstancesAttribute in WMAssignProcessInstancesAttribut Filter InstanceFilter in e String Name in Variant Value AssignActivityInstancesAttribute WMAssignActivityInstancesAttribu in String ActivityInstanceID te in Filter InstanceFilter in String Name in String Value AbortInstances in Filter WMAbortProcessInstances InstanceFilter
Note that the Server parameters to these methods is implicit. They use the
server from which the process definition was obtained.
9.2.4.3
CreateInstance
This method is the binding for the WMCreateProcessInstance function.
ProcessInstance CreateInstance ()
Argument Description (WMCreateProcessInstance Argument) ProcessInstance pproc_inst_id
ChangeInstancesState (
in Filter InstanceFilter,
in String InstanceState)
Argument Description (WMChangeProcessInstancesState Argument) InstanceFilter pproc_inst_filter InstanceState process_inst_state
ChangeActivityInstancesState (
in String ActivityDefID,
in Filter InstanceFilter,
in String InstanceState)
Argument Description (WMChangeActivityInstancesState Argument) ActivityDefID pactivity_def_id InstanceFilter pact_inst_filter InstanceState activity_inst_state
TerminateInstances (
in Filter InstanceFilter)
Argument Description (WMTerminateProcessInstances Argument) InstanceFilter pproc_inst_filter
AssignInstancesAttribute (
in Filter InstanceFilter,
in String Name,
in Variant Value)
Argument Description (WMAssignProcessInstancesAttribute Argument) InstanceFilter pact_inst_filter Name attribute_name Value pattribute_value
AssignActivityInstancesAttribute (
in String ActivityDefID,
in Filter InstanceFilter,
in String Name,
in Variant Value)
Argument Description (WMAssignActivityInstancesAttribute Argument) ActivityDefID pactivity_def_id InstanceFilter pact_inst_filter Name attribute_name Value pattribute_value
AbortInstances (
in Filter InstanceFilter)
Argument Description (WMAbortProcessInstances Argument) InstanceFilter pproc_inst_filter
Name Type Description
Attributes Collection WMOpenProcessInstanceAttributesLis
t
DataReference String WMTProcessInst.data_reference
ID String WMTProcessInst.proc_inst_id
Name String WMTProcessInst.process_name
Participants Collection WMTProcessInst.proc_participants
Priority Integer WMTProcessInst.priority
ProcessDefinitio ProcessDefinit WMGetProcessDefinition
n ion
ProcessDefinitio String WMTProcessInst.proc_def_id
nID
State String WMTProcessInst.state
States Collection WMOpenProcessInstanceStatesList
All of these properties are read-only, except for the State property. Updating this property has the same effect as calling the ChangeState method. The Attributes and States properties take a Filter parameter.
The ProcessDefinition property is a convenience. It calls the
GetProcessDefinition method on the session from which the process instance was
obtained, passing the ProcessDefinitionID property value.
9.2.5.2
Methods
A ProcessInstance object has the following methods:
Signature Description ProcessInstance Start WMStartProcess Terminate WMTerminateProcess ChangeState in String State WMChangeProcessInstanceState AssignAttribute in String WMAssignProcessInstanceAttribute Name in Variant Value Abort WMAbortProcessInstance
Note that the Server parameters to these methods is implicit. They use the
server from which the process instance was obtained.
9.2.5.3
Start
This method is the binding for the WMStartProcess function.
ProcessInstance Start ()
Argument Description (WMStartProcess Argument) ProcessInstance pnew_proc_inst_id
Terminate ()
9.2.5.5
ChangeState
This method is the binding for the WMChangeProcessInstanceState
function.
ChangeState (
in String State)
Argument Description (WMChangeProcessInstanceState Argument) State pproc_inst_state
AssignAttribute (
in String Name,
in Variant Value)
Argument Description (WMAssignProcessInstanceAttribute Argument) Name attribute_name Value pattribute_value
Abort ()
9.2.6
Activity Instance
The ActivityInstance class corresponds to the WMTActivityInst data type.
Activity instance objects are not externally creatable. They are returned by
the Server object's ListActivityInstances method, and by the ActivityInstance
property of a WorkItem object.
9.2.6.1
Properties
An ActivityInstance object has the following properties:
Name Type Description
Attributes Collection WMOpenActivityInstanceAttributesLis
t
DataReference String WMTActivityInst.data_reference
ID String WMTActivityInst.activity_inst_id
Name String WMTActivityInst.activity_name
Participants Collection WMTActivityInst.proc_participants
Priority Integer WMTActivityInstance.priority
ProcessInstanc ProcessInstanc WMGetProcessInstance
e e
ProcessInstanc String WMTActivityInstance.proc_inst_id
eID
State String WMTActivityInstance.state
States Collection WMOpenActivityInstanceStatesList
All of these properties are read-only, except for the State property. Updating this property has the same effect as calling the ChangeState method. The Attributes and States properties take a Filter parameter.
The ProcessInstance property is a convenience. It calls the GetProcessInstance
method on the server from which the activity instance was obtained, passing the
ProcessInstanceID property value.
9.2.6.2
Methods
An ActivityInstance object has the following methods:
Signature Description ChangeState in String State WMChangeActivityInstanceState AssignAttribute in String WMAssignActivityInstanceAttribut Name in Variant Value e
Note that the Server parameters to these methods is implicit. They use the
server from which the activity instance was obtained.
9.2.6.3
ChangeState
This method is the binding for the WMChangeActivityInstanceState
function.
ChangeState (
in String State)
Argument Description (WMChangeActivityInstanceState Argument) State pactivity_inst_state
AssignAttribute (
in String Name,
in Variant Value)
Argument Description (WMAssignActivityInstanceAttribute Argument) Name attribute_name Value pattribute_value
Name Type Description
ActivityInstanc ActivityInstan WMGetActivityInstance
e ce
ActivityInstanc String WMTWorkItem.activity_inst
eID
Attributes Collection WMOpenWorkItemAttributesList
DataReference String WMTWorkItem.data_reference
ID String WMTWorkItem.workitem_id
Name String WMTWorkItem.workitem_name
Participant String WMTWorkItem.proc_participant
Priority Integer WMTWorkItemance.priority
ProcessInstance ProcessInstanc WMGetProcessInstance
e
ProcessInstance String WMTWorkItemance.proc_inst_id
ID
All of these properties are read-only. The Attributes property takes a Filter
parameter. The ActivityInstance and ProcessInstance properties are a
convenience. They call the GetProcessInstance and GetActivityInstance methods,
respectiively, on the server from which the work item was obtained, passing
the ProcessInstanceID or ActivityInstanceID property value.
9.2.7.2
Methods
A WorkItem object has the following methods:
Signature Description AssignAttribute in String WMAssignWorkItemAttribute Name in Variant Value Complete WMCompleteWorkItem Reassign in String WMReassignWorkItem SourceUser in String TargetUser
Note that the Server parameters to these methods is implicit. They use the
server from which the work item was obtained.
9.2.7.3
AssignAttribute
This method is the binding for the WMAssignWorkItemAttribute function.
AssignAttribute (
in String Name,
in Variant Value)
Argument Description (WMAssignWorkItemAttribute Argument) Name attribute_name Value pattribute_value
Complete ()
9.2.7.5
Reassign
This method is the binding for the WMRessignWorkItem function.
Reassign (
in String SourceUser,
in String TargetUser)
Argument Description (WMReassignWorkItem Argument) SourceUser psource_user TargetUser ptarget_user
WorkItem.Attributes("Due Date").Value
evaluates to the value of the "Due Date" attribute of a work item. The data
type of the Value property is the OLE automation Variant type. This data type
provides functions for determining the data type of its value, and converting
its value to a basic data type.
9.2.8.1
Properties
An Attribute object has the following properties:
Name Type WMFetch...Attribute Parameter DataType Integer attribute_type Name String attribute_name Value Variant pattribute_valueAll of these properties are read-only. To modify an attribute value, call the object's AssignAttribute method.
The interfaces defined by this module are:
· Attribute interface, which provides access to attributes of various types of workflow objects.
· AttributeList interface, which provides operations to handle filtered lists of Attributes.
· Filter interface, which is used to define queries for workflow objects issued agaist the Workflow Enactment Service who owns these objects.
· WorkflowObject interface, which defines generic operations and attributes common to many workflow objects
The following abbreviated IDL summarizes the interfaces contained in the CfWFBase module.
module CfWorkflowFacilityBase {
... // data type and general exception definitions
interface Filter {
... // query filter object definitions
};
interface Attribute {
... // workflow object attribute definitions
};
interface AttributeList {
... // workflow object attribute list definitions
};
interface WorkflowObject {
... // workflow object definitions
};
};
The following sections describe the contents of the CfWFBase module in detail.
9.3.1.1
Data Types and General Exceptions
The following data types and exceptions are defined in the CfWFBase module and
are used in various interfaces of the Workflow Facility.
// TYPE DEFINITIONS
typedef string WMTName;
typedef WMTName WMTState;
typedef sequence<WMTState> WMTStates;
typedef string WMTId;
typedef integer WMTErrorCode
// EXCEPTION DEFINITIONS
exception InvalidFilter (WMTErrorCode badFilter);
exception NoMoreData ();
exception InvalidState();
exception TransitionNotAllowed();
exception AttributeAsignmentFailed();
exception InvalidAttribute();
Each workflow object has a name and a state. WMTName and WMTState define the types to specifiy the corresponding attributes. In addition, the WMTName type is used to define any kind of name-like attribute, e.g., to specifiy named references to objects outside the scope of the Workflow Facility specification. WMTStates handles a list of states. The WMTId type is used for identification of persistent object references. The WMTErrorCode type is used to provide additional information with some Exceptions, e.g., the InvalidFilter exception uses the Error Code to indicate the specific problem with the Filter.
The InvalidFilter and NoMoreData exceptions are related to processing of
filtered queries and query result lists. InvalidState and TransitionNotAllowed
exceptions are raised by state-changing operations on workflow objects.
9.3.1.2
Filter Interface
The Filter interface is used to specify the filter criteria for a query
against the set of objects of a specific type.
interface Filter {
attribute long filterType;
attribute long filterLength;
attribute WMTName attributeName;
attribute integer comparison;
attribute string filterString;
};
9.3.1.3
Attribute Interfaces
The Attribute interface is used to access attributes of workflow objects.
Attribute data are accessed by value; the attributeValue is of type any and is
further specified by attributeType.
There are basically three types of attributes of a workflow object that can be accessed via this interface:
· The standard attributes described in this document (e.g., Name)
· Vendor specific attributes associated with a particular object type (e.g., `ProcessClass' attribute of a ProcessDefinition)
· User defined attributes associated with particular object instances (e.g., `CustomerNumber' attribute of a particular ProcessInstance)
interface Attribute {
attribute WMTName attributeName;
attribute string attributeType;
attribute long attributeLength;
attribute any attributeValue;
};
typedef sequence<Attribute> Attributes;
The AttributeList interface provides iterator operations for handling of a list of Attributes; the corresponding factory operation for this interface can be found in an workflow object interface. The fetchAttribute operation gets the next Attribute from the list, the fetchAttributes operation gets the next howMany Attributes from the list; if the list is empty, the NoMoreData exception is raised.
interface AttributeList {
attribute long count;
Attribute fetchAttribute()
raises (NoMoreData);
Attributes fetchAttributes(in long howMany)
raises (NoMoreData);
};
9.3.1.4
Workflow Object Interface
The Workflow Object interface defines the attributes and operations common to
most workflow objects. Each WorkflowObject has a Name, a State and a set of
Attributes associated with it.
A list of valid states for a particular WorkflowObject can be obtained using the listValidStates operation; the InvalidState exception is raised when a state change to an unknown state is requested. getState obtains the current State of a workflow object and setState changes the State; the TransitionNotAllowed exception is raised when the transition from the current state to the new state is not allowed.
OpenAttributesList is the factory operation for an AttributeList, allowing for a query for attributes; getAttributeValue supports access to attributes by name. The AssignAttribute(s) operations assign new values to Attributes. The InvalidAttribute exception is raised on requests for attributes not defined for the workflow object; tha AttributeAssignmentFailed exception is raised when the Attribute could not be modified, e.g., is read-only.
interface WorkflowObject {
attribute WMTName name;
attribute WMTId id;
WMTStates listValidStates (
in Filter filter);
void changeState (in WMTState newState)
raises (TransitionNotAllowed, InvalidState);
WMTState getState ();
AttibuteList openAttributeList (
in Filter filter,
in boolean countFlag)
raises (InvalidFilter);
Attribute getAttributeValue (in WMTName name)
raises (InvalidAttribute);
void assignAttribute ( in Attribute attribute)
raises (InvalidAttribute, AttributeAssignmentFailed);
void assignAttributes ( in Attributes attributes)
raises (InvalidAttribute, AttributeAssignmentFailed);
};
9.3.2
The Workflow Application Client Module
The Worflow Application Client Module contains the interfaces used to exchange
information between a workflow client application and the Enactemnt Service. It
allows workflow participants to control execution of workflow processes and to
process their worklists.
The module defines the following interfaces:
· ApplicationClientServer interface, which handles connection of a workflow participant with a particular Enactment Service and provides factory interfaces for access to filtered list of workflow objects owned by that Enactment Service.
· ProcessDefinition interface, which represents an executable workflow model; this interface serves as a factory for instances of a workflow model.
· ProcessInstance interface, which represents an active workflow process model and provides operations to control execution of that model
· ActivityInstance interface, which represents an active node in a workflow process instance
· WorkItem interface, which represents a piece of work assigned to a particular workflow participant and allows for controlling the execution of this work.
The following abbreviated IDL summarizes the interfaces contained in the CfWFApplicationClient module.
#include "CfWFBase.idl"
module CfWFApplicationClient {
... // Data type and specific exception definitions
interface ProcessDefinition; // Forward declaration
interface ProcessInstance; // Forward declaration
interface ActivityInstance; // Forward declaration
interface WorkItem; // Forward declaration
interface ProcessDefinitionList {
... // Iterator for process definition query result
};
interface ProcessInstanceList {
... // Iterator for process instance query result
};
interface ActivityInstanceList {
... // Iterator for activity instance query result
};
interface WorkList {
... // Iterator for work item query result
};
interface ApplicationClientServer {
... // application client server object definitions
};
interface ProcessDefinition : CfWFBase::WorkflowObject{
... // process definition object definitions
};
interface ProcessInstance : CfWFBase::WorkflowObject {
... // process instance object definitions
};
interface ActivityInstance : CfWFBase::WorkflowObject {
... // activity instance object definitions
};
interface WorkItem : CfWFBase::WorkflowObject {
... // work item object definitions
};
};
9.3.2.1
Data Types and Specific Exceptions
The following data types and exceptions are specific to the Workflow
Application Client module.
// TYPE DEFINITIONS
typedef string WMTDataReference;
typedef WMTName WMTWflParticipant;
typedef sequence<WMTWflParticipant> WMTWflParticipants;
// SPECIFIC EXCEPTION DEFINITIONS
exception NotConnected();
exception ConnectFailed( CfWFBase::WMTErrorCode);
exception InvalidId();
A WMTDataReference provides information on data associated with a workflow object; WMTWflParticipant provides info on workflow participants. Interpretation of the contents of these slots is left to the Workflow Application Client.
The exceptions defined here deal with poblems related to management of the
connection to the Enactment Service.
9.3.2.2
Workflow Application Client Server Interface
The Workflow ApplicationClientServer interface handles the connection of a
particular workflow user to an Enactment Service and provides access oto the
workflow objects accessible through this Enactment Service.
The connect operation initializes the ApplicationClientServer; the context of the connection is defined by the engineName and the scope. The ConnectFailed excpetion is raised when a connection could not be established. The disconnect operation serves as a destructor for the ApplicationClientServer.
Access to the workflow objects accessible through the connection is supported by providing factory methods for interfaces managing access to lists of workflow objects: the Open...sList operation take a filter as their first argument (see the CfWFBase module descritpion for details), the countFlag parameter indicates whether the number of elements in the query result should be returned. A NotConnected exception is raised when no connection was established. The query results are bound to a connection and are invalidated when the connection is terminated.
Operations are provided to get a ProcessInstance, ActivityInstance or WorkItem object via its identifier.
interface ApplicationClientServer {
attribute CfWFBase :: WMTName engineName;
attribute CfWFBase :: WMTName scope;
void connect(
in CfWFBase :: WMTName userId,
in string password)
raises (ConnectFailed);
void disconnect()
raises (NotConnected);
ProcessDefinitionList openProcessDefinitionsList(
in CfWFBase :: Filter filter,
in boolean countFlag)
raises (InvalidFilter, NotConnected);
ProcessInstanceList openProcessInstancesList (
in CfWFBase :: Filter filter,
in boolean countFlag)
raises (InvalidFilter, NotConnected);
ActivityInstanceList openActivityInstancesList (
in CfWFBase :: Filter filter,
in boolean countFlag)
raises (InvalidFilter, NotConnected);
WorkList openWorkList (
in CfWFBase :: Filter filter,
in boolean countFlag)
raises (InvalidFilter, NotConnected);
ProcessInstance getProcessInstance(
in CfWFBase :: WMTId processInstanceId)
raises (InvalidId);
ActivityInstance getActivityInstance(
in CfWFBase :: WMTId processInstanceId,
in CfWFBase :: WMTId activityInstanceId)
raises (InvalidId);
Workitem getWorkitem(
in CfWFBase :: WMTId processInstanceId,
in CfWFBase :: WMTId workItemId)
raises (InvalidId);
};
9.3.2.3
Process Definition Interface
The Process Definition interface provides factory operation for Process
Instances and supports Process Management operations on workflow objects
related to the Process Definition: change of State and change of a specific
Attribute's value for all members of a filtered set of Process Instances and
Activity Instances.
The ProcessDefinition interface inherits attributes and operations from WorkflowObject.
interface ProcessDefinition : CfWFBase :: WorkflowObject {
ProcessInstance createProcessInstance (
in CfWFBase :: WMTName instanceName)
raises (NotConnected);
void changeProcessInstancesState (
in CfWFBase :: Filter filter,
in CfWFBase :: WMTState newState)
raises (NotConnected, TransitionNotAllowed InvalidState);
void abortProcessInstances (
in CfWFBase :: Filter filter)
raises (NotConnected, TransitionNotAllowed);
void terminateProcessInstances (
in CfWFBase :: Filter filter )
raises (NotConnected, TransitionNotAllowed);
void assignProcessInstancesAttribute (
in CfWFBase :: Filter filter,
in CfWFBase :: Attribute attribute)
raises (NotConnected, InvalidFilter, InvalidAttribute, AttributeAssignmentFailed);
void changeActivityInstancesState (
in CfWFBase :: Filter filter,
in CfWFBase :: WMTState newState)
raises (NotConnected, InvalidFilter, TransitionNotAllowed, InvalidState);
void assignActivityInstancesAttribute (
in CfWFBase :: Filter filter,
in CfWFBase :: Attribute attribute)
raises (NotConnected, InvalidFilter, InvalidAttribute, AttributeAssignmentFailed);
};
9.3.2.4
Process Instance Interface
The ProcessInstance interface provides operations to access and modify the
state and the attributes of a Process Instance object.
State changes can be performed using the start, terminate or abort operations. Additional state transitions may be supported by an EnactmentService(see the WorkflowObject :: changeState() operation described above). The getParentProcessDefinition operation returns the ProcessDefinition object that was used to create the specific ProcessInstance. The listAssignedParticipants operation provides the list of workflow Participants associated to the Process Instance. The ProcessInstance interface inherits attributes and operations from WorkflowObject. All operations require an active connection to the Enactment Service.
interface ProcessInstance : CfWFBase :: WorkflowObject{
attribute CfWFBase :: WMTDataRef dataReference;
attribute long priority;
ProcessDefinition getParentProcessDefinition ();
void start ()
raises (NotConnected, TransitionNotAllowed);
void terminate();
raises (NotConnected, TransitionNotAllowed);
void abort();
raises (NotConnected, TransitionNotAllowed);
CfWFBase :: WMTWflParticipants listAssignedParticipants ()
raises (NotConnected);
};
9.3.2.5
Activity Instance Interface
The Activity Instance interface provides operations to access and modify the
attributes and the state of an ActivityInstance object.
The getParentProcessInstance operation returns the ProcessInstance object that owns the specific ActivityInstance. The listAssignedParticipants operation provides the list of workflow Participants associated to the Activity Instance. The ActivityInstance interface inherits attributes and operations from WorkflowObject. All operations require an active connection to the Enactment Service.
interface ActivityInstance : CfWFBase :: WorkflowObject {
attribute CfWFBase :: WMTDataRef dataReference;
attribute long priority;
ProcessInstance getParentProcessInstance ();
CfWFBase :: WMTWflParticipants listAssignedParticipants ()
raises (NotConnected);
};
9.3.2.6
Work Item Interface
The WorkItem interface provides operations to access and modify the attributes
and the state of a WorkItem object.
The get- and completeWorkitem operations change the State of a WorkItem. getAssignedParticipant returns the workflow participant currently assigned to the work item; reassignWorkItem assigns it to another participant.
interface WorkItem : CfWFBase :: WorkflowObject {
attribute CfWFBase :: WMTDataRef dataReference;
attribute long priority;
ProcessInstance getParentProcessInstance ();
ActivityInstance getParentActivityInstance ();
void reassign (
in CfWFBase::WMTWflParticipant sourceUser,
in CfWFBase::WMTWflParticipant targetUser)
raises (NotConnected, InvalidSourceUser, InvalidTargetUser);
void get ()
raises (NotConnected, TransitionNotAllowed);
void complete()
raises (NotConnected, TransitionNotAllowed);
CfWFBase :: WMTWflParticipant getAssignedParticipant()
raises (NotConnected);
};
9.3.2.7
Filtered List Processing
The following interfaces provide iterators for results returned from filtered
list requests; see the section on Attributes for a description of the iterator
functions.
typedef sequence<ProcessInstance> ProcessInstances;
typedef sequence<Activitynstance> ActivityInstances;
typedef sequence<WorkItem> WorkItems;
interface ProcessDefinitionList {
attribute long count;
ProcessDefinition fetchProcessDefinition()
raises (NoMoreData);
ProcessDefinitions fetchProcessDefinitions(
in unsigned long howMany)
raises (NoMoreData);
};
interface ProcessInstanceList {
attribute long count;
ProcessInstance fetchProcessInstance()
raises (NoMoreData);
ProcessInstances fetchProcessInstances(
in unsigned long howMany)
raises (NoMoreData);
};
interface ActivityInstanceList {
attribute long count;
ActivityInstance fetchActivityInstance()
raises (NoMoreData);
ActivityInstances fetchActivityInstances(
in unsigned long howMany);
raises (NoMoreData);
};
interface WorkList {
attribute long count;
WorkItem fetchWorkItem()
raises (NoMoreData);
WorkItem fetchWorkItems(
in unsigned long howMany);
raises (NoMoreData);
};