Developing your own workflow monitor

Just occasionally I'm tempted to post a really techie article that will probably only be of interest to hard-core xProcess enthusiasts! This is one of those occasions. I've written elsewhere about some of the aspects of workflow support in xProcess (see for example the article on State Diagram support which explains how to define triggers for internal events graphically, and "From tracking to planning and back" which discusses how tracker products can be linked to xProcess via workflow). This article though will go a bit further and give you some hints about how the Workflow Server works and how you can link in your own programs to detect workflow events and trigger actions on them.

The Workflow Server sits in a Tomcat instance watching the outside world (and the inside world of the xProcess Data Source) through a set of monitors. When these monitors discover events that might be of interest, they tell the Workflow Server which checks whether any object in the xProcess Data Source has registered an interest in that type of event. If it has it invokes the defined action(s) for that event, potentially committing changes to the xProcess data or indeed to external systems. Several monitors are delivered with the xProcess Workflow Server. There's the DataSourceMonitor itself which monitors state transitions within the Data Source.There are also monitors for the Flyspray bug tracking system, for CollabNet's Project Tracker and a general purpose email monitor. However if you want to integrate external systems with xProcess this is exactly the way to do it - write your own monitor. In spite of my introduction to this blog article, this is quite straightforward to do. There are 3 key elements:

1. A monitor class (inheriting from com.ivis.xprocess.workflowserver.monitors.MonitorImpl)
2. Methods for this class which initialize it, find the events
   
3. [optionally] An event class (inheriting from com.ivis.xprocess.workflowserver.ExternalEvent) and possibly useful methods that may be called when the event is triggered.

Here (below) is a code snippet for a sample monitor which show the key methods init(), which is called when the Workflow Server starts up, and findEvents(), which is called periodically by the server in order for this monitor to query its external system and provide the events to the server.

public class SampleSystemMonitor extends MonitorImpl {
SortedSet events;
public static String EXTERNAL_SYSTEM_NAME = "My External System";
public static String EXTERNAL_EVENT_NAME = "My event name";

public String getSystemName() {
return EXTERNAL_SYSTEM_NAME;
}

public String[] getEventNames() {
return new String[] { EXTERNAL_EVENT_NAME };
}

@Override
public void init(DataSource dataSource) throws WorkflowException {
super.init(dataSource);
// TODO initialize connection with external system
}

@Override
protected SortedSet findEvents() throws WorkflowException {
events = new TreeSet();
// TODO query external system for new events, e.g.
// loop
ExternalEvent xevent = new SampleSystemEvent(new Date(), EXTERNAL_EVENT_NAME);
Map map = xevent.getMap();
//TODO set map values so they can be referenced in the triggered action, e.g. ...
map.put("name", "New Task");
events.add(xevent);
// end loop
return events;
}
}

The monitors are singleton objects and are instantiated within the server by Spring. So having written your monitor you can inform the Workflow Server that it should be called simply by modifying the xprocess.xml in the Tomcat WEB-INF directory (following the pattern of other monitors). Specific objects in the xProcess Data Source can respond to the events and trigger specific actions through their "WorkflowPackage" - which is declared in the process definition.