WARP Integration Guide

  1. Java API
  2. XML-RPC API

Preliminaries

  1. WARP and the necessary requirements are installed.
  2. User defines and authors workflows, describing the procedures to track and the types of observable events.

Operation

WARP offers two modes for integration with an application: it can be directly incorporated as a Java library, or run as a standalone service and accessed via XML-RPC. The Java and XML-RPC APIs mirror each other following the control flow outlined below.

  1. A WARP tracker is started.
  2. Client calls addFullStateListener(listenerURI) on WARP to receive workflow tracking updates from WARP.
  3. Client calls startTrackingWorkflow(workflowInstanceURI, workflowTypeURI), where workflowInstanceURI is a URI that uniquely identifies the instance of the workflow being tracked. It will be used to identify workflows while making updates. workflowTypeURI identifies the workflow template from which the instance is drawn.
  4. As the operator performs actions in the domain of interest, instrumentation within the client sends these raw events to WARP by calling addEvent(eventName, args).
  5. WARP calls workflowUpdateInfo(workflowStateUpdates) on all clients, notifying them of the current state of all tracked workflows.
  6. Client calls removeFullStateListener(listenerURI) on WARP to stop receiving updates.

Java API Integration

This section describes how to use WARP as a Java library.

The following code fragment illustrates how to initialize a WARP multiple workflow tracker, and then start tracking the simple "Delivery" example. The demo application will bring up a graphical view of the current belief about the state in the workflow and contains a simple panel for notifying the tracker of new observations. The application also shows how to subscribe to updates from the tracker, when the current belief state has changed. The full source code for this demo is in WarpExample.java

Starting the WARP Tracker

The primary class used for tracking is the MultiWorkflowManager which receives requests to track workflows, processes incoming events, and can track one or more workflows simultaneously.

In this example, the MultiWorkflowManager is instantiated with a directory of Workflow schemas (.lhm files), and a set of dictionaries, which are tables of terms associated with observations. For now, the default empty set of dictionaries is sufficient, as WARP automatically populates these dictionaries based on observations encountered during operation.

 public void start() {
      // Load an empty dictionary for this example, as we are not using variables.
      List dictList = new ArrayList();

      // All of the workflow files in this directory will be available for tracking.
      File workflowDir = new File("./schemas");

      // Instantiate a new multiple workflow tracker
      MultiWorkflowManager mgr = new MultiWorkflowManager(dictList, 
          new WorkflowLibrary(workflowDir), false);
      ...

Receiving Updates

We generate a class that implements IWarpFullUpdateListener to enable WARP to receive updates about the workflows being tracked.

  public class TestWARPListener implements IWarpFullUpdateListener {
    URL url= null;
    public TestWARPListener() throws MalformedURLException {      
      url = new URL("http://warp.ai.sri.com/demo/simple-listener");
    }
    public URL getURL() { return url; }

    public void update(List<WarpFullStateUpdate> states) {
      for (WarpFullStateUpdate state : states) {
        System.out.println("- - - - - - - - - - - - - - - - - - - -\n");
        System.out.println("Current State: "+state.getCurrSIR().toStringShort());
        System.out.println("Next State: "+state.getFwdSIR().toStringShort());
      }
    }

    public void workflowTrackingStarted(String wInstURI, String wTypeURI) {
      System.out.println("Tracking started using workflow type="+wTypeURI+", instance="+wInstURI);
    }

    public void workflowTrackingEnded(String wInstURI) {
      System.out.println("Tracking stopped, workflow instance="+wInstURI);
    }
  }
      

This example simply prints out the beliefs about the current state and the likely next state whenever these states have changed.

Each listener is identified by a URL, which is used to reference a specific listener in the list of event subscribers for the MultiWorkflowManager.

update is called by WARP whenever the state of the world has changed. workflowTrackingStarted and workflowTrackingEnded are used to notify the client whenever the tracker has started or stopped tracking a specific workflow with the given instance URI and type URI.

Inserting Events

To track a workflow, WARP must be notified of events of interest as they are performed.

In our example, we bring up a panel with buttons, each corresponding to a sensor observation from the example. Each of these buttons makes a call to feedEvent:

     mgr.feedEvent(eventName, new HashMap<String,String>());

where mgr is an instance of the MultiWorkflowManager.

eventName corresponds to the name of the observation, as declared in the obs-predicate element of the workflow specification (see here for more details).

Starting and Stopping Workflow Tracking

Starting and stopping tracking on workflows is accomplished by calls to startTracking and stopTracking, in MultiWorkflowManager.

  mgr.startTracking(workflowInstURI, label, workflowTypeURI);

The workflowInstURI argument is a string, which is a client-assigned URI that uniquely identifies the specific workflow instance being tracked. label corresponds to the human-readable display used to show the workflow, and workflowTypeURI is the URI used to identify the workflow itself.

To stop tracking a workflow instance, use a call to stopTracking with the URI for that workflow instance.

  mgr.stopTracking(workflowInstURI);

XML-RPC API Integration

WARP can be run in a configuration that advertises services via XML-RPC (port determined by the user). This section describes how to setup and communicate with WARP via the XML-RPC.

This section consists of two parts. The first addresses routines advertised by WARP, which clients may use to perform requests such as starting and stopping a workflow or submitting an event. The second describes the routines that will be called by WARP to provide inference updates to the client, followed by APIs and instructions for registering clients for updates.

  1. XMLRPC Server Setup
  2. WARP Routines
  3. Client Routines
  4. Update Data Format

XML-RPC Server Setup

To start the XML-RPC service version of WARP, use the start(port, dicts, wlib) routine in com.sri.calo.warp.xmlrpc.WarpServer. An example is given in the main() routine for that class.

port indicates the numbered port to run on, with wlib being the WorkflowLibrary object. Following the previous section, this can be set to point to the directory containing the workflow schemas (i.e., new WorkflowLibrary(new File("path/to/workflows"))).


WARP Routines

Subscribe to Notifications: This routine notifies WARP that the given caller wishes to subscribe to fullstate workflow updates from WARP. See the client routines for functions to implement to receive updates. The caller requests that the updates be sent to the given URI.

	public Object addFullStateListener(String URI);
      

Unsubscribe from WARP: The caller notifies WARP to stop sending updates to the listener at the given URI.

	public Object removeFullStateListener(String URI);
      

Start Tracking a Workflow: The client notifies WARP to start tracking a new Workflow instance, identified by the given URI.

	public Object startTrackingWorkflow(String workflowInstanceURI, String workflowTypeURI);
      

Stop Tracking a Workflow: The client notifies WARP to stop tracking the workflow instance identified by the given URI.

	public Object stopTrackingWorkflow(String workflowInstanceURI);
      

Suspend Tracking a Workflow: The client notifies WARP to suspend tracking the workflow instance identified by the given URI.

	public Object suspendTrackingWorkflow(String workflowInstanceURI);
      

Resume Tracking a Workflow: The client notifies WARP to resume tracking the (previously suspended) workflow instance identified by the given URI.

	public Object resumeTrackingWorkflow(String workflowInstanceURI);
      

Show workflow details: The client asks WARP to display its detailed UI for the workflow instance identified by the given URI.

	public Object showWorkflow(String workflowInstanceURI);
      

Hide workflow details: The client asks WARP to hide its detailed UI for the workflow instance identified by the given URI.

	public Object hideWorkflow(String workflowInstanceURI);
      

Indicating a state was executed: This routine can be used to inform WARP that a state in a given workflow instance was executed by an agent that was not the user. This routine enables system designers to force the state for a given workflow instance that is being tracked.

	public Object stateExecuted(String workflowInstanceURI, String subpath,
	Map<String, String> args);
      

The args correspond to the immediate parameters for the state at the given subpath. A subpath specifies the individual state executed, from the given workflow. Globals do not need to be specified.

Instrumentation, passing events to WARP: This routine allows an external event source to pass events to WARP.

	public Object feedEvent(String name, Map<String, String> args);
      

Events are specified by their name and may have a set of attributes/arguments associated with them, given as a Map of strings to strings, args.

For example, an event for opening a Microsoft Word document named Report.doc may be identified by having name MsWord.Open and attributes given by the following Java Map (given in JSON-style syntax):
	{
	file : "Report.doc",
	path : "C:/reports"
	}
      

Client Routines

Below are routines that the client needs to implement to receive updates from WARP.

Note that the following method calls that provide information about workflow changes are targeted at fixed components. In the future, we will implement facilities for determining for which workflow instances a client app would be interested in receiving updates.

Workflow Instance Tracking Started: This routine notifies the client that tracking has begun on the given Workflow Instance. Called by WARP.

	public Object workflowTrackingStarted(String workflowInstanceURI, String workflowTypeURI)
      

Workflow Instance Tracking Ended: This routine notifies the client that tracking has finished on the given Workflow Instance. Called by WARP.

	public Object workflowTrackingEnded(String workflowInstanceURI)
      

Workflow Update: Notifies the client of updates to currently running workflows. See the update format section for more details.

	public Object workflowInfo(List<Map> workflowStateUpdates)
      

Workflow Update Data Format

Below are updates that provide both detailed information (including full probability distributions) and simpler information that predicts the most likely next step. These use the same method with parameters described below:

Note: outputs are expressed as integers (percents).

The workflow state updates are Java Maps using a JSON-style key ==> value description. Maps can nest to sub-maps, which are referenced by their "type:"

	{
	_type_: "WorkflowStateUpdate",            // Corresponds to (part of) Warp class StateInferenceResult
	workflowInstanceURI: workflowInstanceURI,
	currentStateUpdate: PredicateStateUpdate | NestedPredicateStateUpdate, // Will be of either type
	nextStateUpdate: PredicateStateUpdate | NestedPredicateStateUpdate, // Will be of either type
	// Probability of different workflow states
	notStartedProb: Integer
	startedProb: Integer
	activeProb: Integer
	inactiveProb: Integer
	finishedProb: Integer
	}


	{
	_type_: "PredicateStateUpdate",         // Corresponds to Warp class PredicateInferenceResult
	name: String, // direct name, not subpath
	probability: Integer,
	argResults: List<ArgumentResult>,
	globalResults: List<ArgumentResult>
	}

	{
	_type_: "NestedPredicateStateUpdate",   // Corresponds to Warp class NestedPredicateInferenceResult
	name: String, // direct name, not subpath
	probability: Integer,
	argResults: List<ArgumentResult>,
	globalResults: List<ArgumentResult>
	subresult: StateUpdate
	}

	{
	_type_: "ArgumentResult",            // Corresponds to Warp class ArgumentResult
	name: String,
	values: List<ValueAndProb>
	}

	{
	_type_: "ValueAndProb",            // Corresponds to Warp class ProbableValue
	value: String,                     // NOTE: we are giving the raw value here, not the display value
	probability: Integer
	}
	
      

Return values are required by the XML-RPC implementation, and can be ignored.


<<Back: Introduction to WorkflowsTop of WARP User Guide