Metastorm BPM : Understanding the Transaction Protocol (Part 1)

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.

Saving State

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.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s