Section 7.3. WAPI


7.3. WAPI

WAPI[*] is the API offered by the enactment service for use by client applications, invoked applications, and administration and monitoring applications. WfMC's lengthy specification (171 pages), which is mostly a catalog of API functions, is devoid of examples. Specifications are provided in three languages: C, CORBA IDL, and COM Automation. The section on C emphasizes the API's functional breakdown, whereas the IDL and COM chapters provide an object-oriented view. The object-oriented view, depicted in the UML class diagram in Figure 7-5, can help you visualize the overall structure of WAPI.

[*] WfMC, "Workflow Management Application Programming Interface (Interface 2&3) Specification," Version 2.0. July 1998.

The main class, ClientConnection, representing the main capabilities of WAPI, uses classes ProcessDefinition, ProcessInstance, ActivityInstance, and WorkItem, each of which inherits from WorkflowObject. A process definition has one or more process instances, which in turn has one or more activities instances, which can have a work item. The ToolAgent class creates an InvokedApplication class to perform the processing of a particular application invocation.

7.3.1. WAPI Functional Categories

The main functional components can be broken down into the following categories: connection, process control, activity control, worklist, administration, and application invocation.

Figure 7-5. WfMC WAPI class diagram


7.3.1.1 Connection

The connection category allows an application to connect to and disconnect from a workflow engine. (That the connection is to an engine rather than to the engine's enactment service is problematic. One would think that the engine is a private worker used by the service and that client applications know only about the service.) It supports all the reference model interfaces. The major functions include:

  • Connect

  • Disconnect

7.3.1.2 Process control

The process control category contains a large set of functions for process definitions and their instances. Searches are based on filters (e.g., find all instances of bank account application processes for trust accounts). State functions allow the reading and modification of state (enabled and disabled for definitions; running, suspended, terminated, and completed for instances) and data (e.g., get order number from a particular shipping instance).

A process definition is instantiated with the functions CreateInstance( ) and StartProcess( )the document admits that these two operations can be combinedand terminated with TerminateInstance( ). It supports all the reference model interfaces except invoked applications. The major functions include:

  • Search process definitions and instances

  • Search and modify process definition and instance states

  • Search and modify process instance data

  • Create, start and terminate process instances

7.3.1.3 Activity control

The activity control category consists of a set of functions to search for activity instances contained within process instances. Included is the ability to change the state of an instance; valid states are running, suspended, terminated, and completed. It supports all the reference model interfaces except invoked applications. The major functions include:

  • Search and modify activity instance

  • Search and modify activity data

7.3.1.4 Worklist

The worklist category provides methods to search work items in a process, as well as the states and data of work items. (A process activity can be designated as manual, meaning that its completion requires the action of a particular person or member of a group. A work item is an activity assigned to a user.) CompleteWorkItem( ) actions a work item, causing control of the process to resume to the next step. ReassignWorkItem( ) moves a work item from one user or group to another. It supports client interfaces from the reference model. The major functions include:

  • Search work items

  • Search and modify work item states

  • Search and modify work item data

  • Reassign and complete work item

7.3.1.5 Administration

The administration interface category consists largely of functions that allow a single change to be effected, in one fell swoop, to a set of process or activity instances. These include changing state or data, or terminating instances. It supports all the reference model interfaces except invoked applications. The major functions include:

  • Mass change process instances and activity instances state

  • Mass set process instance of activity instance data

  • Mass process instance termination

7.3.1.6 Application invocation

In the WAPI model, special tool agent components provide access to invoked applications on behalf of a process. Presumably, these agents are adapters or plugins to the workflow engine that abstract the connection and communication details of the external system; the engine calls the tool agent when it encounters a process activity that is associated with an application. Before a tool agent can be accessed, it requires the establishment of a connection; the standard WAPI connection function is used for this. A particular invocation starts with the InvokeApplication( ) method; the result is obtained by polling the agent with the CheckStatus( ) method. The deficiency of the model is its lack of clarity around interactions such as synchronous and asynchronous request-response and event notification. The category supports invoked applications from the reference model. The major functions include:

  • Connect to and disconnect from, a tool agent

  • Invoke application

  • Check application status

  • Terminate application

7.3.2. WAPI Example: Complete All My Tasks

The example program in Example 7-2, written in a high-level pseudocode, demonstrates a simple client worklist application that uses WAPI to get and complete each work item assigned to a particular user.

Example 7-2. Sample WAPI code in pseudo-C
 1    // connect to engine at URL 10.12.131.13:9001 using credentials mike/password 2    WAPISession ses = WMConnect("mike", "password", "10.12.131.13:9001") 3      4    // open query result set 5    WMTQueryHandle queryHandle = WMOpenWorkList(ses, 6       "ACTIVITY_TYPE='Approval' and ACTIVITY_ROLE='BranchManager'") 7      8    // loop through each result 9    while(true) 10    { 11       // get next result 12       WMTWorkItem item = WMFetchWorkItem(ses, queryHandle) 13       if no more data, break 14      15       // Extract from item data and print such as item name and ID, 16       //   process and activity instance IDs, priority, and name of participants 17       print ("Your task is " + item.processID + " " item.workItemID) 18      19       // complete the item 20       WMCompleteWorkItem(ses, item.processID, item.workItemID) 21    } 22      23    // close query 24    WMCloseWorkList(ses, queryHandle); 25      26    // disconnect 27    WMDisconnect(ses) 28     

The code begins on line 2 with a call to WMConnect to attach to the engine on port 9001 at the IP address 10.12.131.13 as the user mike (password password); WAPI does not specify exactly how an engine is identified, but other applications commonly listen on an IP port. The call returns a session handle held in the variable WAPISession, which is passed as an argument to each subsequent WAPI call to the engine in this session.

In line 5, the query is submitted to the engine via WMOpenWorkList. The search is for all manual activities of type Approval assigned to the role Branch Manager ("ACTIVITY_TYPE='Approval' and ACTIVITY_ROLE='BranchManager'"). (The WAPI specification is vague on the precise formulation of a worklist filter, and examples of its use are difficult, if not impossible, to find. The specification encourages SQL-style queries, so we use a SQL-style where clause. The assumption is that workflow engine performs a select on a table having columns ACTIVITY_TYPE and ACTIVITY_ROLE.) The call returns an iterator, or cursor, held in the variable WMTQueryHandle.

The while loop in lines 9-21 retrieves and completes each matching activity. The call to WMFetchWorkItem in line 12 gets the next work item from the query; if no work items remain in the result set, the loop is exited in line 13. Line 17 prints out information about the work item. Line 20 calls WMCompleteWorkItem to complete the activity, passing the process ID and work item ID extracted from the work item from the result set.

When the loop is complete, successive calls to WMCloseWorkList (24) and WMDisconnect (line 27) close the result set and the engine connection respectively.



    Essential Business Process Modeling
    Essential Business Process Modeling
    ISBN: 0596008430
    EAN: 2147483647
    Year: 2003
    Pages: 122
    Authors: Michael Havey

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net