The Metastorm BPM Transaction Protocol (TP) describes the request and response operations model and interface that enable Metastorm clients to be developed and communicate with the process engine using XML smart messages. Each TP message consists of an XML document type, which may be validated against the e-Work TP schema. Client processes submit requests and receive responses from the process engine via the COM/COM+ (via ActiveX) TP interface. The Metastorm TP is based on synchronous structured-message exchange. These messages are in plain text XML format as defined by the TP schemas (therefore messages are rejected by the process engine if not conforming to the recognized XML format).
The TP allows authenticated clients to access:
• To Do and Watch list filters and lists
• Blank and Administration form filters and lists
• Folders and their contents
• Available actions.
Most requests to the process engine will require a Session attribute. This is the GUID that is assigned to a logged on user when they are authenticated by the engine. The engine will return the GUID inside of the TP login response messages and is stored by the client (in the Metastorm.eSession database). All responses include a Timestamp attribute. This is used by the client to determine the time
difference between client and server which is used to render displayed date-times in the client’s time zone, and to convert all posted (via refill or submit) date-times back into the
server’s time zone.
Each request can optionally include an element. Any value passed here will be returned unaltered by the engine, as ‘ClientData’, in the consequent response. This provides a means for the client to
save and restore state information. Certain response messages may also contain a ‘ServerData’ element. Any value passed here should be returned unaltered, as ServerData, in a subsequent refill or commit request for the same folder.
Transaction Protocol Messages
eLogin – Authenticates a user and creates a new user session.
eLoginRequest (sent back from any preceding eLoginFormResponse)
eLoginResponse (contains session ID for use in susequent TP requests for this user).
eLogout – Forces the engine to drop the user session.
eLogoutRequest (contains sessionID)
eList – Gets all or part of a users To Do, Watch and Forms listing
eListResponse (contains the list of alerts (to do items), forms, or custom list data).
eFolder – Opens a specified Folder at any stage.
eFolderRequest (initiates operation)
eFolderResponse (contains folder and form details)
eAction – used to initiate a new form (creates the folder), or to invoke an action on an existing folder (locks the folder).
eActionResponse (contains the appropriate folder and form (or confirmation))
eSubmitResponse (contains confirmation of action completion)
eSubmit – Used to submit updates to a folder (the green button)
eSubmitRequest (with folder ref)
eSubmitResponse (releases the lock on folder and if no chaining is defined or if the request specified no chaining).
eCancel – Cancel’s updates to a folder (the red button)
eCancelRequest (with folder ref)
eAttachment – Retrieves an attachment from the eAttachment table
eAttachmentResponse (contains attachment in Base64)
ePostAttachment – Posts an attachment to eAttachment table
In the second part of this article, we’ll take a look at an example.