The Process Manager Web Service - PMService2

PMService2 provides the same methods as the original PMService API (PMService) with the exception of the following changes:

Instead of returning XML as strings, PMService2 will use the built-in serializers provided with Apache Axis, as well as custom serializers, to return data as complex types defined in the WSDL instead of free-form XML.
Since the Web service API and process manager reside inside the same context in the J2EE application server, the HTTP calls will be replaced with direct calls to the ProcessManagerServer in the pm context.

This section contains the following topics:

Typical User Session

Session Management

Complex Types - PMService2

The com.ejbtech.processmanager.services Package

Typical User Session

PMService1 in Axis

With PMService, a user session with the Axis client libraries might look something like this:

SAXReader reader = new SAXReader();
PMService service = new PmServiceServiceLocator().getpmService();
String sid = service.logInPM("caflow", "caflow");
String[] definitions = service.getDefinitions(sid);
for (int i = 0; i < definitions.length; i++) {
     Document doc = reader.read(
new ByteArrayInputStream(definitions[i].getBytes()));
     System.out.println(doc.getRootElement().elementText("name"));
}

PMService2 in Axis

With PMService2, the same session looks like this (note that we must explicitly tell axis to maintain the session for us):

PMService2 service = 
new PmServiceServiceLocator().getpmService2();
((PmService2SoapBindingStub)service).setMaintainSession(true);
service.logIn("caflow", "caflow");
ProcessDefinitionDescriptor[] definitions = 
service.getDefinitions();
for (int i = 0; i < definitions.length; i++) {
	System.out.println(definitions[i].getName());
}

PMService2 in .NET (C#)

In C#, using stubs generated by wsdl.exe, the PMService2 session would look like this (note the use of a CookieContainer to maintain the session):

pmServiceService service = new pmServiceService();
System.Net.CookieContainer cookies = 
new System.Net.CookieContainer();
service.CookieContainer = cookies;
service.logIn("caflow","caflow");
ProcessDefinitionDescriptor[] descriptors = 
service.getDefinitions();
for(int i=0;i<descriptors.Length;i++) {
	Console.WriteLine(descriptors[i].name);
}

Session Management

The change that will have the largest impact on how this API is used is the change to the session management code. As shown in the previous session example, PMService2 no longer returns a session ID as an explicit parameter from the login method and no longer accepts a session ID as a parameter to the other methods. Instead, Axis returns an HTTP cookie with the login method which must be passed in when any other methods are called.

The line that tells the Axis client to pass along this cookie is "((PmService2SoapBindingStub)service).setMaintainSession(true);" In .NET, adding a CookieContainer to the service instructs the generated stubs to use the cookie. No other client libraries have been tested at this time.

The reason for this change is that it allows you to use the clustering support built into application servers. With cookie-based sessions, we get a consistent and well-tested mechanism to propagate session data throughout the cluster in the case of failover, and we provide the load balancer with sufficient information to keep sessions associated with a single node in the cluster whenever possible.

Complex Types - PMService2

For all of the complex types returned from the workflow except actors, process instances, and process definitions, the schema of complex types is specified in the Web Service Definition Language (WSDL). Descriptions of the complex types for PMService2 follow.

Attribute

Field	Type	Description
complexTypeQName	String	Holds its QName when the attribute is a complex type defined in a schema, otherwise it will be null
description	String	Specifies the description of the attribute
external	Boolean	Specifies whether the attribute is marked as external
input	Boolean	Specifies whether the attribute is an input parameter
name	String	Specifies the name of the attribute
output	Boolean	Specifies whether the attribute is an output parameter
type	Integer	Specifies the type of the attribute, represented as an integer STRING = 0, BYTE = 1, SHORT = 2, INTEGER = 3, LONG = 4, FLOAT = 5, DOUBLE = 6, BOOLEAN = 7, XML = 8, LIST = 9, DECIMAL = 10, DATETIME = 11, BIGINTEGER = 12, COMPLEX = 100, ARRAY = 101
value	String	Specifies the value of the attribute

HistoryRecord

Field	Type	Description
actorName	String	Specifies the name of the actor that performed this operation
eventTypePresentation	String	Specifies the type of event, formatted as a human-readable string
info	String	Specifies information about the event
nodeId	String	Specifies the ID of the node in the definition this event is associated with
nodePresentation	String	Specifies the human-readable name of the node in the definition that this event is associated with
timestamp	Long	Specifies the java time when the event occurred
timestampPresentation	String	Specifies the human-readable time when the event occurred
Type	Integer	WORKITEM_CREATED = 0, WORKITEM_DISPATCHED = 1, WORKITEM_COMPLETED = 2, WORKITEM_OVERDUE = 3, WORKITEM_REMOVED = 4, EXECUTED = 5, STARTED = 6 COMPLETED = 7 EXCEPTION = 8; WORKITEM_INFO = 9;
wiPresentation	String	Specifies the workitem ID as a human-readable string
workItemId	String	Specifies the workitem ID associated with the event

LogEntry

Field	Type	Description
action	String	Specifies the action this log operation occurred in
info	String	Specifies information about the log event
instanceId	String	Specifies the instance this entry pertains to, if applicable
status	Integer	Specifies whether this entry represents a success or failure
taxonomy	String	Specifies the class of the log entry
time	Long	Specifies when this log entry occurred.
workitemId	String	Specifies the workitem this log entry pertains to, if applicable

Parameter

Field	Type	Description
expression	String	Specifies the expression assigned to this parameter
name	String	Specifies the name of the parameter
type	Integer	Specifies the type of the parameter (see Attribute for a list of types)
typeQName	QName	Specifies the type of the parameter as a QName
Value	String	Specifies the value of the parameter

ProcessDefinitionDescriptor

Field	Type	Description
description	String	The description of this definition
id	String	Specifies the definition ID
inuse	String	Specifies the name of the user that has locked this definition, or null if the definition is not locked
modified	Long	Specifies the date (as a java time) when the definition was last modified
name	String	Specifies the definition name
shortName	String	Specifies the definition short name
versions	Version[]	Specifies the descriptors of all the versions of this definition

ProcessInstanceDescriptor

Field	Type	Description
completed	Long	Specifies the java time when this instance was complete, or 0 if it has not been completed
description	String	Specifies the description of this instance
externals	Attribute[]	Specifies the external attributes for the instance
id	String	Specifies the instance ID
inuse	String	Specifies the name of the user that has locked this instance, or null if the definition is not locked
name	String	Specifies the definition name associated with the instance
started	Long	Specifies the java time when this instance was started
status	Integer	Specifies the status of the instance STATUS_CREATED = 0 STATUS_RUNNING = 1 STATUS_COMPLETED = 2 STATUS_SUSPENDED = 3 STATUS_TERMINATED = 4

Version

Field	Type	Description
active	Boolean	Specifies whether this version is active
effective	Long	Specifies the first date when this version can be used (as a java time)
expiration	Long	Specifies the last date when this version can be used (as a java time)
id	String	Specifies the version ID

WorkItem

Field	Type	Description
id	String	Specifies the ID of the workitem
activated	Long	Specifies the java time when the workitem was created
actor	String	Specifies the actor that was assigned the workitem
completed	Long	Specifies the time when the workitem was completed, or 0 if the workitem was not completed
completedBy	String	Specifies the user/actor that completed the workitem
controlAttribute	String	Specifies the name of the variable that is being iterated over if this workitem is part of an iteration
controlValue	String	Specifies the value of the controlAttribute when this workitem was created
dueDate	Long	Specifies the java time when this workitem must be completed
executionId	String	Specifies the execution context the workitem belongs to This value is used in iterations.
id	String	Specifies the workitem ID
inputParameters	Parameter [ ]	Specifies the input parameters that were passed to the workitem
iteration	Integer	Specifies the place in the iteration where this workitem belongs
label	String	Specifies the label of the node this workitem represents
nodeDescription	String	Specifies the description of the node this workitem represents
nodeId	String	Specifies the ID of the node this workitem represents
nodeName	String	Specifies the name of the node this workitem represents
operation	String	Specifies the name of the operation this workitem represents
outputParameters	Parameter [ ]	Specifies the output parameters that were passed in from the actor
parentWorkItemId	String	Specifies the ID of the workitem that precedes this one
processId	String	Specifies the ID of the version of the definition this workitem belongs to
processInstanceId	String	Specifies the ID of the process instance this workitem belongs to
processName	String	Specifies the name of the definition this workitem belongs to
processValues	Parameter [ ]	Specifies any external attributes associated with the process
valid	Boolean	Specifies whether the database representation of this workitem is guaranteed to be accurate Workitems will be persisted before they are valid in the case of long iterations.
sendEmail	Boolean	Specifies whether to send an email
EmailObject	EmailObject	Specifies email details

Tell Technical Publications how we can improve this information