February 17, 1995
Authored by Workflow Management Coalition Working Group 1A
Send comments to kswenson@ossi.com
Subject to Change
This draft document is being circulated for wider comment for the purpose improving it. It has not been adopted by the Workflow Management Coalition as an official document. Reviewers of this document should understand that this document may go through significant changes in the future, and no commitment of any kind is made to the current form.
This document defines the API specifications of the Work Flow Management (WfM)
Coalition, for defining workflow definitions and managing such definitions
within a workflow enactment system.
Purpose
The purpose of this document is to specify work flow management Application
Programming Interfaces (APIs) which can be supported by WfM products today.
These APIs 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). The WAPI consists of five main parts; this
document deals with part 1 also known as interface 1.
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 APIs are also intended to allow the workflow
applications to be adjusted to operate with different WFM Engines using this
common API interface.
These APIs should allow a WFM exploiter to have a single end user interface
regardless of the number of WFM products existing in an installation. WAPI may
be implemented in a number of languages. The first Coalition specification
will be for the `C' language. The API operates as CALLS and handles to data
structures. No assumption is made regarding the underlying implementation of
the CALLS in a particular WFM product implementation, nor are there any
assumptions about the actual implementation of the data structures (entities)
other than that a handle exists for them, and CALLS that manipulate them.
Workflow
Definition Management
Workflow definition management is the ability to list existing definitions, modify them, to create new definitions, to delete definitions. A standard set of routines are provided that act in a way very similar to file open and close. These API calls interact directly with the workflow engine server; there are no files involved. Purposes for defining standards in this area include:
To provide a common way to access workflow definitions. Some workflow engines save workflow definitions in files which are accessible from the client, in some cases the files are not accessible, in some cases the workflow definition is a collection of records in a relational database, or a collection of entities in an OO database, and in some cases a collection of files is needed to piece together a single workflow definition. Defining a common way to access the workflow definition solves a lot of basic problems.
To assure independence from having to map into a real file system gives Workflow Engine (WfE) a great deal more flexibility. We can not assume that the client and server share file systems. The one assumption that we can make is that the workflow system provides some way to programmatically communicate from client to the server (the API) so we should make an API oriented standard.
To assure that Vendor type and version are reliably available up front so that a program will be able to determine whether it can read that format or not, before it actually reads.
To provide a single standard on naming conventions that will simplify the job of any program accessing the WfE in this way. Standard for wild cards, and for composing name from multiple pieces of information will encourage tools to read and exchange workflow definitions.
The model assumes that there are a number of workflow definitions[1] within the workflow engine. This interface provides access to those definitions for modifying them, deleting them, or adding new ones.
Every workflow definition has a name which is a unique identifier used to
reference a specific workflow definition. In order to comply with this
interface, the name must be an ASCII string composed of printable characters.
Furthermore there are three reserved characters that are not allowed in the
names: semicolon, asterisk, and question-mark.
Goals
Incremental Set of API calls. It is assumed that as
the WFM technology evolves, likewise the specifications defined in this
document will evolve and will be added to in subsequent versions of this
document.
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.
Reference
Documents
The following documents are associated with this document and should be used as
a reference.
May 16, 1994 - Meeting in London.
May 18, 1994 - Discussion paper from Keith Swenson summarizing the April 8 meeting.
May 20, 1994 - Discussion paper from David Redmond-Pyle covering architectural issues and proposing an object approach.
May 23, 1994 - Progress report presented at Technical Committee Meeting in Grenoble.
June 2, 1994 - API document from Keith Swenson incorporating material from May 18 paper, May 20 paper, and input received at the TC meeting.
July 4, 1994 - Discussion paper 5 from David Redmond-Pyle expanded on and refined earlier documents.
July 7 1994 - WG1 meeting in Sunnyvale where July 4 document is discussed in terms of earlier documents.
July 18, 1994 - IF1 API document produced in WMC standard format by Keith Swenson includes results of July 7 meeting.
July 20, 1994 - Meeting in Vienna, and phone conference afterwards to include American members.
Aug 3, 1994 - Essentially the same as the July 20 version, handed out at the TC meeting in San Jose on Aug 4.
Jan 9, 1995 - Updated to include results of discussions in Sept - Dec.
Feb 17, 1995 - Updated with the results of the Dallas Working Group meeting.
Conformance
In order for an implementation of this specification to be conformant it must
meet the following criteria:
All API calls and data structures must be implemented as defined. Features within this specification that are defined as optional or with exceptions are not included in this criterion. Those API calls or data structures that are marked as optional, must comply with this specification if they are implemented.
Levels of implementation will be defined, labeled with letters of the alphabet. A product will be considered conformant to level B when it implements all of the API calls of level B and level A. It may include some API calls from level C but is not considered comforming to a level unless all of the API calls are implemented.
All API commands defined in this document will allow for individual product extensions which may be used between homogeneous components of the WFM Enactment system. These extensions may be ignored when received by different WFM products. Vendors are encouraged to register their extensions with the Coalition in order to facilitate higher commonality of WFM Engine access and for possible inclusion in a future release of the specifications. Extensions include additional API calls as well as additional parameters in existing API calls.
Handles,
Entities, Attributes, and Lists
The WAPI makes use of some basic data structures in order to communicate
information is a simple logically consistent way.
Handles
API calls that return a value that is not a simple data type, will usually
return a handle. This handle is a way to refer to a data structure through the
API, while the data structure itself is actually maintained inside the body of
code that implements the API. We can say that the handles refer to "objects",
but the term "object" implies to many people that you need to use an OO
language. For this reason we shall say that the handles refer to "entities"
which are a data structure of some kind. The WAPI does not specify how the
data structures behind the handles are implemented. In fact, the handle
oriented scheme can be implement in the widest variety of languages, quite
possibly all programming languages. This approach can be used successfully
with C, PASCAL, Basic, FORTRAN, C++, assembly language, LISP, dBase, and even
spreadsheet macros.
An entity might actually be a record, or a number of records, in a database table. It might be a C struct, or a PASCAL record. It might be an array in other languages. It might be text. Regardless of the particular implementation, it is convenient to talk about "entities" as being the basic units of manipulation.
Entity Reference (Ref): WAPI entities will have a reference value. The reference is a unique name for the entity (within a scope) and the value remains constant from session to session, and from client to client. The reference is a character string implemented in a way consistent with the API language binding. The reference is used to allow entities to refer to each other in a persistent way.
Handle: The handle to a local structure is used in API calls that access or manipulate the entity. The actual implementation will depend upon the language binding, but will typically be a 32-bit integer, such as a C language pointer or an array index. Having a handle assumes that some system resource (e.g. memory) might be tied up, so handles must be obtained and later freed in order to release these system resources.
Entities
System Entities and Local Data Structures: Implicit in the model is basically
two kinds of data structures, which in some implementations might be the same.
System Entities are persistent across sessions and are represented throughout
the system. These entities have a Ref with which to refer to them. Local
structures are created by the API in order to manipulate and access information
from the system entity. The Get_Handle command might create a local structure
that is a surrogate for the system entity. The need for this design comes from
those vendors implementing a client server connectivity that is not
transparent. The surrogate local structures hide the connectivity mechanism.
Some workflow vendors may have the ability to access system entity directly,
and therefor will not have a need for local structures. Lists are purely local
structures. They are accessible only from the client they were created on,
they do not generally persist from session to session, and therefor have no
need for a Ref. Local structures are removed by "free" commands.
The diagram at the right is an attempt to illustrate the surrogate structure concept. The three entities in the server have Refs of "A", "B", and "C". The application has requested a handle to "C", so a local surrogate structure has been created for it. Interactions with the local "C" structure will then ultimately be interactions with the shared "C".
In some cases the shared persistent entities will be files on a file server. A "get" on one of those entities would be equivalent to opening the file, and providing a handle that represents the open file. For email based systems, the shared entities are passed around by email, and the local structure is again the open, in-memory handle to the information contained in the email message. Client server systems based on network protocols might implement a more or less literal interpretation of the diagram where actions on the local structure are turned immediately to actions on the shared entity. Systems based on ORB technology might dispense with the local structure all together, and return a handle directly to the shared entity. This mechanism should provide enough generality to handle all cases.
There is no requirement that the server/client work at the same granularity as the entities being requested. Some systems will incur a communications load when initially fetching the information for an entity. Local structures might be created for a batch of entities at the same time. For the example above, A and B are not present in the local environment, but some systems might find a benefit to retrieve A, B, and C at the same time, when a handle for C is requested. Then subsequent requests for handles for B or A would incur almost no overhead. This method will need to be used for systems which hold a set of entities in a form in the server where individual entities are not easy to separate. For example, the server may hold all the entities for a process instance in a single "file" which is handed over in its entirety to the client module. In this case creating a whole collection of local surrogate structures at the same time might be necessary.
Attributes
Every entity has attributes which contain specific information about the
entity. These values are accessed via the GetAttribute and SetAttribute
commands. Some levels of interface 1 will define some standard attributes, and
there will be other attributes that vendors will wish to implement specifically
for their systems. In this way the entities are extensible by vendors.
The data contained in an attribute will of a specified type. These types are:
Data Type Meaning
String Any text string value.
Number A numerical value
Boolean A true/false value.
Date A date or a date/time value.
Symbol A string that can be used as an identifier for an
attribute or user. This string has some special
restrictions -- some characters are not allowed.
For example, "String", "Number", Boolean",
"Date", "Symbol", and "Reference" are all symbols.
Reference (Ref) A reference to an entity. This is a special kind
of symbol that is globally unique, or at least unique
within a particular scope. It is used to refer to a
specific instance of an entity.
There is no requirement that the entire list be available or in memory all at the same time. Extremely large lists might potentially be cached by the API implementation. These details are hidden by the interface. The only requirement is that elements of the list are available when the calls are made to retrieve them.
The list can be called an ordered collection since it preserves the order of the items in the list. This form is chosen because it is the most semantically neutral. The list does not impose any sorting order nor make any constraint about duplicates in the list. When the workflow definition requires a collection of entities in a particular order, the workflow engine or the workflow definition tool is responsible for providing the entities in the correct order to the API. If the workflow definition requires that there not be any duplicates in a given collection, it is the responsibility of the workflow engine or the workflow definition tool to remove duplicates. The API merely transmits the collection of entities.
Lists maintain a "current" position. This can be set to a specified position
in the list, or reset to the beginning. In a single operation the value at the
current position can be retrieved and the current position incremented.
Generic
Commands
There are a set of API commands that are used for generic manipulation of
structures in a way that is not specific to workflow at all. First is general
manipulation of entities, handles, and attributes. Shared persistent entities
are created and deleted through the use of Create_Entity and
Delete_Entity. If you have a reference to an entity, you must retrieve
it before getting details about it. Get_Handle will allocate a local
data structure for an entity, and return a handle to it. Free_Handle
will tell the system that it can get rid of the local structure.
Given a handle, you can retrieve an entity's attributes. Get_Attribute is used to get single valued attributes, while Get_List will get attributes with multiple values. Set_Attribute and Set_List set the single valued or multi-valued attributes.
Single values are easy to manipulate, but lists require special consideration, since few programming languages give good support for lists, and because lists can not be guaranteed to fit in memory, the list itself is not returned to the caller in its entirety. Instead, like the entity, the list is manipulated through a handle. A new list handle is created with New_List. Free_List tells the system it can reclaim the memory used by the list. Get_List just logically copies the multiple values from an attribute into an existing list structure with. Seek_List will set the list pointer to a particular place in the list. The individual values in the list can be retrieved by Get_Next_Item. Remove_Item will take a specified item out of the list. Clear_List will remove everything from the list. Append_Item will add a new item to the list. Set_List then logically copies the values from a list into the attribute.
Workflow
Specific Commands
Then there are commands that are more directly related to workflow. First,
Connect and Disconnect are used to allocate and free local
structures that maintain access to the server. Get_Directory_List is
used to retrieve a list of process definition references. This is a way to
search for a particular process definition from the workflow server. Then
Open_Workflow_Definition will retrieve a particular definition
structure, and Close_Workflow_Definition will allow the system to free
up the local structures involved.
A typical scenario is presented below that should give an idea of how the various API calls are used in conjunction to retrieve a workflow definition.
1 Connect(server,user,etc,S1)
2 New_List(L1)
3 Get_Directory_List(S1,pat,L1)
4 Get_Next_Item( L1, R1 )
5 while (R1) {
6 Get_Handle( S1, R1, H1 )
7 Get_Attribute( H1, "Name", N)
8 ... /* insert N into a listbox for the user */
9 Free_Handle( H1 )
10 Get_Next_Item( L1, R1 )
11 }
12 index = ... /* user selects one line from listbox */
13 Seek_List( L1, index )
14 Get_Next_Item( L1, R2 )
15 Get_Handle(S1, R2, H2)
16 Get_Attribute( H2, "Name", N )
17 Free_Handle( H2 )
18
19 W1 = Open_Workflow_Definition( S1, N, "read" )
20 Get_Attribute( W1, "VendorID", VID )
21 if (VID .... /* test if vendor Id is appropriate */
22 Clear_List(L1)
23 Get_List(W1, "Activities", L1)
24 ... /* futher processing of activities */
25 Close_Workflow_Definition( W1, "save" )
26
27 Free_List( L1 )
28 Disconnect( S1 )
Line 2 creates a list structure. Line 3 retrieves a particular list of (names of) workflow definitions from the server into the list structure L1. The loop construct depends upon language. Its purpose is to sequentially retrieve and display every item from the list for the end user by first retrieving the entity reference (line 4 & 10), and get the handle (line 6). Since this entity does not belong to a workflow definition the scope is the session. Line 7 gets the name from the entity to display. Line 9 is to clean up and release the handle. R1 is a simple value so it does not need to be freed.
Line 12 is to symbolize where the user selects one from display. Line 13 finds the entry in list again. Next retrieve the desired entity reference (line 14), the desired handle (line 15), and the full name of the workflow definition.
Line 19 retrieves the root entity of the workflow definition. Line 20 retrieves attributes about the workflow definition, for example here retrieve the vendor ID. Empty out the list for another purpose on line 22. Retrieve an attribute which is a list in line 23; this example is to retrieve the list of activities for the workflow definition.
Finally, in line 28, close the session.
All of the commands are listed below in alphabetical order.
Append_Item
Syntax
Append_Item <L_handle> <new_value>
Descriprition
Adds an item to the end of the list.
Parameters
1). L_handle. The handle of the list being appended to.
2). New_Value. The value that will be the new last item in the list.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Create_Entity
Syntax
Create_Entity <scope> <class> <name>
<ref-return>
Descriprition
This is how new entities are created that compose the workflow
definition. The entity created is a workflow persistent entity. The reference
to that entity will be returned.
Parameters
1). Scoping handle. Indicates the scope in which the
entity is to be created.
2) Class: Specifies what class of entity is to be created. The range of classes is defined by the schema associated with the scoping entity.
3) name: Some systems need to be given a name of the entity, from which to make the unique entity reference. This may be left blank. The value passed here, and the effect on the entity reference is system dependent.
4) ref-return: This is where the reference to the new entity will be returned.
Return Values
1). Success/Failure indicator for the command.
Requirements
The implementation must provide default values where
appropriate.
Rationale
This is called "Create" instead of "New" because "New" is used in
this document to mean creation of an API local structure. This call is to
create a system entity that is persistent across sessions, so it might make
sense to distance it from New_List by using the "Create" verb. Subsequently,
Free_Handle will cause the destruction of the local structure without affecting
the workflow entity, while Delete_Entity will get rid of both.
Clear_List
Syntax
Clear_List <L_handle>
Descriprition
Removed all the items from the list. The result is that the list
will be empty.
Parameters
1). L_handle. The handle of the list being cleared.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Close_Workflow_Definition
Syntax
Close_Workflow_Definition <WD_handle> <save/abort>
Descriprition
Close_Workflow_Definition, the opposite of Open, ends the
interaction with a particular workflow definition.
Parameters
1). WD_handle. The handle of the workflow definition that
had been opened.
2) Save/Abort. This parameter communicates whether the changes, if any, should be saved, or whether they should be thrown away.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
The save/abort flag is an attempt to represent transactions that can
be committed or rolled back. Open issues include how to save changes without
losing the entity, possibly changing from read/write mode to read only mode.
Also unclear is how one will be notified if someone else changes the workflow
definition, and how one would retrieve the updated version. Finally, what if
the workflow engine allows changes to be controlled at a finer level than the
entire workflow definition. Perhaps a general start-transaction,
commit-transaction, rollback-transaction mechanism should be allowed on a
vendor defined scope.
Connect
Syntax
Connect <user> <Engine Name> <notification>
<S_Handle>
Descriprition
The CONNECT command informs the WFM Engine that other commands will
be originating from this source. This command is described in detail in the
Interface 2 specification document, and is copied here for convenience. Since
this returns a handle to a session entity this API call can be considered a
specialization of the Get_Handle command except that it is the starting point
for access to the system and does not need a scoping handle.
Parameters
1). User identification. The identification of the workflow
participant on whose behalf the Worklist Handler will be operating. The value
specified may represent a human, a device, etc. This identification is
normally used for security checking, accounting, etc.
2). WFM Engine Symbolic Name. 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 Worklist Handlers which interact with multiple WFM Engines. This would be a symbolic name which is resolved through a lookup facility. This is essentially the entity reference for the session entity.
3). Notification Type. The type of notification to be used to alert a workflow participant that a change has occurred in the system in one or more of the data structures previously received. The program can then use this as a cue to refresh the display or take other action. [OPTIONAL]
4). S_handle. This session handle is returned so that it can be passed to the API on all subsequent API calls which would identify interactions within the CONNECT/DISCONNECT bounds, that define a participant's session interaction with the Engine. These handles are opaque so that in connectionless 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 API call.
Return Values
1). Success/Failure indicator for the command.
Delete_
Entity
Syntax
Delete_Entity <scoping_handle> <Ref>
Descriprition
Causes the entity to be delete from the workflow system. Any
references to the entity from other entities may or may not be removed -- this
will depend upon the implementing system. Behavior of the system with respect
to tree structures is similarly undefined: the system may delete entities in a
tree contained by an entity, when that entity is deleted.
This function may fail for a variety of reasons. The system may require that certain conditions exist before the entity can be deleted.
Parameters
1). Scoping handle. Indicates the scope in which the
entity is to be created.
2) Ref. The reference to the entity being deleted.
Return Values
1). Success/Failure indicator for the command.
Requirements
Disconnect
Syntax
Disconnect <S_handle>
Descriprition
The Disconnect command tells the WFM Engine that no more API calls
will be issued from this source using the named handle. The WFM Engine could
discard state data being held or take other closure actions.
Parameters
1). S_handle. The session handle of the session being
disconnected.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Free_
Handle
Syntax
Free_Handle <Handle>
Descriprition
This call allows system resources dedicated to the local structure
to be reclaimed. After this call the O_handle is no longer valid. This API
call does not delete the system entity from the workflow system; it only
removes the local structure making the system entity inaccessible.
Parameters
1). Handle. The entity handle of the entity being
freed.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
The client programs have to run in a wide variety of environments
many of which have very limited memory. The entire workflow may grow to be
arbitrarily large. Therefor there needs to be a way for the API to manage the
memory it has effectively. This API call allows it to reclaim memory that the
calling application no longer needs. In some (other) environments this API
call may not do anything.
Free_List
Syntax
Free_List <L_handle>
Descriprition
Free_List releases the system resources (e.g. memory) for a list
structure. Since lists do not have Refs they can never be retrieved after
being freed. The values in the list items are deleted from memory also. If
the list contains handles the handles are deleted, but the entities they point
to are not.
Parameters
1). L_handle. The handle of the list to be deleted and
freed.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Get_Attribute
Syntax
Get_Attribute <O_handle> <attribute name>
<return_value>
Descriprition
Returns the value of the attribute named, or get the first item if
the attribute is a list. See Get_List to get all of the elements of a list.
Actually, the value of the attribute named is effectively copied into a
variable. For example, if the name of an activity is retrieve into a variable
"S", further manipulation of "S" will have no effect on the name of the
activity.
Parameters
1). Handle. The handle of the entity from which the
attribute is being retrieved.
2) Attribute Name: The name of the attribute desired, probably expressed as a string, but the exact details will depend upon the language binding.
3). Return Value: This is where the value of the attribute is returned.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
The value returned is not an entity and does not have any attributes
itself, such as class, etc.
Get_Directory_List
Syntax
Get_Directory_List <S_handle> <Pattern> <L_handle>
Descriprition
This command is given a pattern, and fills a list with workflow
directory items which represent all of the workflow definitions that have names
that match the pattern. The complete workflow definition entity is not
included, but rather a workflow directory item which is a small entity giving
the name on other information about the workflow definition which may then be
used to retrieve the actual definition. This is much like a directory listing
or a file system.
Parameters
1). S_handle. The session handle of the session from which
the workflow definition directory is being searched.
2). pattern. The pattern is a string that is used for specifying what subset of the workflow definitions in the entire directory are requested for listing. Then name of the workflow definitions may have fields, and searching for particular fields is possible.
3). L_handle. The handle of a list is passed. The results of the search will be put into this list.
Return Values
1). Success/Failure indicator for the command.
Requirements
Special characters are used as wild cards to allow searching.
* The asterisk is used as a wild card to denote any character and any number of characters up to the end of the field. Non-delimiter characters before the asterisk are characters to come at the beginning of the field; characters after the asterisk must be at the end of the field. Only one asterisk is valid per field.
? The question mark will allow any printable character for a single position in the name. Question marks may be used in any position of the search pattern and with no limit on the number (up to the maximum size of the workflow definition name). A search pattern of "?????" (5 question marks) will find all names that are exactly 5 characters long (in that field).
; The semicolon is used to delimit field in the search pattern just as they are used to delimit fields in the actual name. If the WfE supports two field, then to find all names of all workflow definitions the user must use "*;*" as the search pattern. Unspecified fields in the search pattern are treated as asterisks and will find all values for that field.
Rationale
Get_
Handle
Syntax
Get_Handle <scope_handle> <Obj_Ref> <return_handle>
Descriprition
References to entities can be obtained a number of ways, including
as attributes on other entity. In order to access the details about the
referenced entity, a handle to that entity must be obtained by using the
Get_Handle command.
Get_Handle may, depending upon the implementation, retrieve the entity from a server, may initiate a connectionless message in order to do this, and may have to wait for a response, etc. This is hidden from the calling program.
Strictly speaking, the API returns a handle to a local structure; manipulations on this local structure ultimately manipulate the system entity. The local structure can be viewed as a surrogate for the system entity. When the local structure is no longer needed, it must be freed (by a call to Free_Handle) which has the effect of deleting the local structure without having any effect on the system entity.
Parameters
1). Scoping handle: The scoping handle can be a S_handle
(session handle) or a WD_handle (workflow definition handle). It defines the
name scope within which the entity reference is unique and the entity is
findable from its ref.
2). Obj_Ref: The reference to the entity to be retrieved.
3). Return_Handle: This handle is returned in this parameter.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
We must not assume that the entire workflow definition fits in client
memory. This API call allows the API to manage memory (and other system
resources) in a more intelligent manner. Parts of the definition can be
referred to without having them actually in memory. Then, when needed, the
calling program can ask for the entity with this API call. The memory is made
available again with the Free_Handle command. Some systems may choose to make
the entire definition available in memory at once, and this API call might be
very simple.
Get_List
Syntax
Get_List <O_handle> <Attribute_Name> <L_handle>
Descriprition
Given an entity with an attribute which as a list value, this API
call will put this list value into the list passed in as the third parameter.
Actually, the value of the attribute named is effectively copied into the list.
For example, if a set of roles is retrieved from a workflow instance into a
list variable "S", further manipulation of "S" will have no effect on the set
of roles in the workflow instance (unless, of course, S is used in a Set_List
operation).
If this call is used on a scalar attribute, an error will result.
Parameters
1). O_handle. The handle to the entity.
2). Attribute_Name. The name of the attribute of the entity being accessed.
3). L_handle. The handle to the list entity that will be filled with the value of the attribute. See the section on lists for more clarification on how lists are created and filled.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Get_Next_Item
Syntax
Get_Next_Item <L_handle> <return_value>
Descriprition
Returns the current item in the list, and it sets itself to be
pointing at the next item in the list ready for the next call. Subsequent
calls to the Get_Next_Item API call will return subsequent items from the list.
This is the easiest way to walk through a list programatically.
Parameters
1). L_handle. The handle of the list.
2). Return Value: The value of the item in the list is returned here.
Return Values
1). value. the value of the current list element. Will
return a null value when it iterates past the last item in the list.
Requirements
Rationale
New_List
Syntax
New_List <return_value>
Descriprition
Creates a new list structure (empty) for use in retrieving list
attribute values, or for filling and setting attributes values.
Parameters
None
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
The list structure is a "local" structure that is a container for
information being passed in and out of the system; the list is not a
persistent part of the model. Because of the variety of environments to be
supported, there must be a clear model of how memory is managed. The model
presented here always puts the burden of freeing the system resources on the
same entity that claimed the resources in the first place. Thus the calling
application is required to both create the list structure and to free it. Once
a list structure is created it can be used many times. API calls that return
list values do so not by creating a new list, but rather by filling an existing
list structure that is passed in.
Open_Workflow_Definition
Syntax
Open_Workflow_Definition <S_handle> <exact_name>
<mode> <WD_Handle>
Descriprition
The actual definition is opened for read, or read-write. This API
call returns the handle for the top level entity for the workflow definition.
This handle can be used to retrieve entities within the workflow definition (as
attributes on this entity) and it is also used as the scoping handle for all
entity within the workflow definition. This API call should fail if the system
can not find a workflow definition with the specified name.
Parameters
1). S_handle. The session handle of the session from which
the workflow definition directory is being searched.
2) Exact_Name. The actual fully qualified name of the workflow definition. This is the name that is retrieved from the Workflow Directory Item entity. Exact name must be used; wild card characters are not permissible.
3) Mode. The mode specifies whether this definition is being opened for read, write, or both. This call may fail if the current user does not have sufficient privileges. The exact definition of what privileges are required, or whether the user meets the requirements is defined by the specific engine vendor.
4). WD_handle. The workflow definition handle is returned. This is a handle to the Workflow Definition Entity, which is the root level entity of the workflow definition.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Remove_Item
Syntax
Remove_Item <L_handle> <Existing_Value>
Descriprition
Given an value of an item already in the list, that value is
removed from the list. If the value exists multiple times, only the first
occurrence is removed from the list.
Parameters
1). L_handle. The handle of the list from which the item
is removed.
2). Existing_Value. The value to find and remove from the list.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Seek_
List
Syntax
Seek_List <L_handle> <index>
Descriprition
Sets the list's current position to the specified location in the
list. The first element in the list is 0.
Parameters
1). L_handle. The handle to the list that is being set.
2). index. The number of the item in the list that current pointer will be set to point to.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Set_Attribute
Syntax
Set_Attribute <O_handle> <Attribute_Name>
<New_Value>
Descriprition
This is how scalar attributes are set. An error will result if
this API call is used for a list attribute.
Parameters
1). O_handle. The handle to the entity.
2). Attribute_Name. The name of the attribute of the entity being set.
3). New_Value. The new value for the attribute is passed as the third parameter. A value of null can be passed to "unset" the attribute which is the same as making the attribute undefined.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
Set_List
Syntax
Set_List <O_handle> <Attribute_Name> <L_handle>
Descriprition
This is how a non-scalar attribute is set. The value of the
attribute is replaced with the value of the list passed in. If Set_List is
used on a scalar attribute, an error will result.
Parameters
1). O_handle. The handle to the entity.
2). Attribute_Name. The name of the attribute of the entity being set.
3). L_handle. The handle to the list entity that will be put into the attribute. In order to clear the attribute an empty list should be passed in. See the section on lists for more clarification on how lists are created and filled.
Return Values
1). Success/Failure indicator for the command.
Requirements
Rationale
C
Language Version API
Below is presented a binding of this API into the C Language. All the functions return an error code. Values are returned to a void*, so it is the responsibility of the calling program to know the type of attribute it is accessing. Since interface 1 has schema meta-objects the value type can be looked up in the schema, as long as the workflow system provides the schema, which is optional.
/**************************************************************/
/* Fujitsu Open Systems Solutions, Inc. */
/* */
/* Trial implementation of the Workflow Management Coalition */
/* (WAPI) Interface 1 - Process Definition Management */
/* */
/* Author: Keith D Swenson */
/* Created: Jan 12, 1995 */
/* */
/**************************************************************/
typedef int Err_Code;
typedef int Boolean;
typedef long Handle;
typedef long ListHandle;
typedef char* String;
typedef char* Symbol;
typedef char* Reference;
/* Object Manipulation */
Err_Code Get_Handle (Handle scope, Reference Ref, Handle* result);
Err_Code Free_Handle (Handle obj);
Err_Code Create_Entity(Handle scope, Symbol class_name, String ref_info);
Err_Code Delete_Entity(Handle scope, Reference Ref);
/* Attribute Manipulation */
Err_Code Get_Attribute(Handle obj, Symbol attr_name, void* return_value);
Err_Code Get_List (Handle obj, Symbol attr_name, ListHandle return_list);
Err_Code Set_Attribute(Handle obj, Symbol attr_name, void* value);
Err_Code Set_List (Handle obj, Symbol attr_name, ListHandle value);
/* List Manipulation */
Err_Code New_List (ListHandle* return_handle);
Err_Code Free_List (ListHandle alist);
Err_Code Clear_List (ListHandle alist);
Err_Code Append_Item (ListHandle alist, void* value);
Err_Code Remove_Item (ListHandle alist, void* value);
Err_Code Seek_List (ListHandle alist, int index);
Err_Code Get_Next_Item(ListHandle alist, void* return_value);
/* Workflow Management Commands */
Err_Code Connect (Reference username, Reference EngineName,
Handle* return_handle); /*Notification??*/
Err_Code Disconnect (Handle session);
Err_Code Get_Directory_List(Handle session, String pattern,
ListHandle return_list);
Err_Code Open_Workflow_Definition(Handle session, Reference name,
String mode, Handle* return_value);
Err_Code Close_Workflow_Definition(Handle wd_handle, Boolean commit);
This section presents the entity classes, and for each entity class the attributes defined for the class. The definition of standard entities and classes is something that will continue over time. It is impossible to come up with a complete specification in the first release, so the workflow management coalition will take a phased approach and will define levels of conformance. As the workflow field matures, new entities will be needed with new definitions and interactions. It is our expectation that the job of defining standard entities for exchanging across the WAPI for defining workflows will be an unending job. Initially we recognize the following release levels:
Goal 1: Level A compliance provides a complete interface for manipulate and manage workflow definitions. A common model for a directory to those definitions is proposed and can be implemented with the API calls at this level. This includes the ability to add new workflow definitions to the directory and delete workflow definitions from the directory. Access to the definitions is provided that allows a client program to retrieve a definition, to modify a definition, and to write a definition. This is performed using semantically neutral entities that a general enough to fit any workflow model.
Goal for RFC: February 1995
Goal 2: Level B compliance defines a basic set of workflow entities which are common across all workflow vendors, or enough vendors to make it worth while. Standardizing these entity class names will give a common starting point for the vendor specific extensions to the basic model. This level of conformance can be likened to the "ASCII Text" level of exchange of document between word processors. For example, this level may define the network of entities of workflow definition, along with basic attributes, but without storage of bitmaps, costs, durations, scheduling, dates, responsibilities, and other richer features; it simply tells engines how to more work from one activity to another.
Completion Date Goal: June 1995
Goal 3: Level C compliance will include a fairly rich set of entities and attributes defined in standard ways. This level can be compared to Rich Text Format exchange of documents for word processors. A reasonably large percentage of the processes that people will want to implement will be able to be expressed and understood by a reasonable number of workflow vendors. Not only are entities accessible, but their definitions and attribute types are available through the standard entity meta-model. Possibly there may be intermediate releases.
Completion Date Goal: December 1996
Goal 4+: Continuing every two years with updates that incorporate change in workflow technology.
All entities must have a couple of attributes. These attributes are necessary for minimal functioning of the system, and so all of them must be implemented at the "a" compliance level.
The first column in the table below specifies the conformance level. Items with an "A" must be implemented in any system that claims level A conformance.
Attribute Data Type Description
Name
A Entity_Ref Ref This returns the reference to the entity. This
reference might be used to set up a relationship
between two entities.
A Entity_Class Symbol This returns the name of the class of the entity.
A handle to the session handle is returned by the Connect command. The session is an attachment to a particular engine and some things must be known about the engine.
Attribute Data Type Description
Name
A User ID Symbol The user ID of the user that created this session.
This might be redundant because the user ID was passed
in to create the session, but it is included here for
completeness.
A Vendor ID Number The ID of the vendor of the workflow engine. This can
be used as information to qualify the other
information given. Vendor A might implement most of
vendor B's workflow definition format, enough so that
it is quite useful in most situations, but not
completely. A process definition vendor C might learn
that vendor A's implementation of format B lacks some
critical feature needed to implement vendor C's model,
and that for this engine a different format should be
used. Vendor ID values are registered by the WMC.
A Engine Number This is a version of the server, analogous to release
Version level. The server version is set solely by the
vendor.
B Accept_Format List of This is a list of references to Format Entities that
s Ref the workflow engine will accept. A calling
application could retrieve this list, and walk through
it to find the most compatible format for writing to
the server.
When a workflow definition list is retrieved, it is filled with Workflow Directory Items. Each item tells about a workflow definition that exists in the server. This functionality is to allow users and application programs to search for and find the name of a specific workflow definition from all the definitions in the engine.
Attribute Data Type Description
Name
A exact name Ref Unique name that can be used to retrieve the content
of the workflow definition. This may be the same
thing as the ref.
A description String a block of text which gives the user a more complete
description of the workflow definition.
A format Number an integer that specifies the format of the workflow
vendor id definition. A process builder tool will use this
field to determine if it can understand the data
structure that will be delivered. The WMC coalition
will act as a clearing house to allocate unique vendor
id's to any vendor requesting one.
A format Number this is a vendor defined version number for the format
version of the workflow definition. This is NOT the version
of the workflow definition.
A workflow_def Ref This is a reference to the workflow definition entity.
This reference is used with Get_Handle in order to
retrieve the workflow definition handle using the
session handle as the scope.
A date Date that the workflow definition was last updated.
A creator Symbol the user that last updated this definition.
The purpose for the field orientation built into the name is to allow a greater number of builders and engines to interoperate easily. Some workflow engines do not have a simple flat list of definitions, instead have a more complex structure. This design allows the engine to encode the structure into a set of fields which uniquely specify a workflow definition. Builders that are designed for "simple" names (flat list) can always display the name for the user, allow the user to select, and that name can be used to retrieve the content. Builders that are more specifically designed for a particular engine (or family of engines) can easily parse the name into separate fields, displaying them in columns or possibly presenting information in a more sophisticated way. Engines with a flat list of workflow definitions can ignore the field capability, as long as semicolon is not allowed in the name of a definition.
This is the root entity of the workflow definition. It has some required attributes, and then a lot of vendor specific attributes. Level a compliance does not specify the structure of the workflow below this point, this comes in level b compliance.
Attribute Data Type Description
Name
A format Number This tells what format the workflow description is
vendor id expressed in.
A format Number The version of the format as specified by the vendor.
version
A exact name Ref A unique name that can be used to retrieve the content
of the workflow definition.
A description String a block of text which gives the user a more complete
description of the workflow definition.
B Format_Ref Ref Returns a reference to a format entity from which the
definition of the format can be obtained.
The exact schema to be communicated through this interface is still under
development in working group 1B. These entities and attributes will be
distributed for comment at a later time.
Minimal
Vendor Strategy
The vendor can implement the process definition entities a lot of ways. Those
vendors of process definitions build out of a network of data structures will
find they can build a handle oriented interface that matches their own internal
data structure quite well.
Those vendors that do not make use of data structures (e.g. they use a block of text edited by the end user), or for any reason find the handle oriented approach difficult to map into, should be aware that the minimal implementation is one where a new attribute (possibly called Full_Definition) is defined for the Workflow Definition entity. Get_Attribute for this attribute returns the entire definition in a single block. As this approach puts the largest burden on the process definition tools it should be avoided if possible.
This level requires a minimal amount of meta-model entity that describe the data entities and attributes.
This is a meta-data entity. This entity is the starting point for getting information about a class of entity. The purpose of this class is to allow the API to describe the classes of entity that are allowed. The session entity will be able to return a list of these.
Attribute Data Type Description
Name
C Format_Name This is the name of the format.
C Vendor_ID Vendor that invented the format.
C Format_Versio Version of that format as defined by the vendor.
n
C Class_List meta-data: returns a list of class entity references
which give detailed information about the classes of
entity that are allowed in this workflow definition.
This is a meta-data entity. The Class- Definition entity gives information about a class of entity. The purpose is to allow the API to describe the classes of entity that are allowed. Ideally, the main Format entity will return a list of these entities.
Attribute Data Type Description
Name
C Class_Name This returns the value that is the same as the value
returned by the Entity_Class attribute of an entity of
the class being described by this entity. This should
not be confused with this entity class, which is
"Class".
C Attribute_Lis A list attribute returns a list of entity references
t for attribute entities.
This is a meta-data entity. The Attribute-Definition entity gives information about an attribute associated with a class of entity. The purpose of this class is to allow the API to describe the classes of entity that are allowed. The Class_Entity returns a list of there attribute entities. These should not be confused with the attributes that exist as part of every entity.
Attribute Data Type Description
Name
C Attribute_Nam Symbol This returns the name to use in the Get_Attribute
e call.
C Is_List Boolean Tells whether the attribute is a list or not.
C Attribute_Typ Symbol Tell what data type this attribute is defined with.
e If the attribute is a list, then this is the type of
the items in the list.