IBM Maximo REST API Guide – Interfacing with the Workflow Engine

Initiating a workflow for a given MBO can be done by using the following API:

POST /oslc/os/<os name>/{rest id}?action=workflow:<workflow name> 
x-method-override: PATCH

This invokes the named workflow in the context of the MBO that is identified in the URI.

Handling Task Nodes

After initiation, the workflow may end up in a task node, which generates an assignment. The following APIs shows how you can handle assignments and where you can fetch assignments.

GET /oslc/os/mxapiwfassignment?oslc.select=*

All the assignments for that user are fetched. Each assignment has a positive action and a negative action to take as shown in the following example JSON:

[
  {
    "description": "mydesc",
    "wfassignmentid": "myid",
    "href": "http://myhref",
    "wfaction": [
      {
        "instruction": "myinstruction1",
        "ispositive": false

Note that the wfaction JSON contains the positive and negative actions and you choose one of those actions.

The following API call shows how to take the positive action.

POST /oslc/os/mxapiwfassignment/{id}?action=wsmethod:completeAssignment 
x-method-override: PATCH

Body:

{
  "memo": "some memo",
  "accepted": true
}

To take up the negative route, you can just set the accepted flag to false in the JSON and POST to the same href.

Handling Input Nodes

Input nodes provide you with interactive options to choose from in a workflow path. You do not need to choose anything, in which case the workflow stays in that same state. If the workflow framework looks ahead and sees an input node as the next node, the rest API response for the current node (say that was a task assignment that you accepted or rejected) is returned.

A response JSON that has the details of the options that the input node provides. The consuming client code is supposed to use those options to let you decide which option to chose.
A response location header with the URL to POST the users choice to.

The response JSON may look like:

{
  "member": [
    {
      "actionid": "myactionid1",
      "instruction": "myinstruction1"
    },
    {
      "actionid": "myactionid2",
      "instruction": "myinstruction2"

Note that the input node type says that its WFINPUT. This information can be used by the consuming code (say a mobile app) to display a generic UI to represent these options.

The following API call describes how to choose an option:

POST <location uri>

Body:

{
  "actionid": "choose one of the action id from the json above",
  "memo": "some memo"
}

Note if this call is not made, the workflow stays with the current node (ie the node previous to the input node) and does not move to the next node. In essence the input node is a transient node which is only available for processing within that context of the previous node.

Handling Interaction Nodes

Interaction nodes are Maximo UI dialogs, applications, or tabs that are presented for you to take an action by using that UI artifact. Unlike an input node, an interaction node is not a transient node. This implies that the workflow engine has moved to the this node from the previous node.

When the workflow lands into this node, the response JSON from the previous call indicates the details of the interaction node, presenting the information from the WFINTERACTION table for that node. This identifies (using the JSON property internalnodetype with a value of WFINTERACTION ) the client code that provides an equivalent interface for the dialog or application. Like the case with the input node, the rest framework generates a URI (set the in the response location header) for the client code to respond back to the interaction such that the workflow instance can move to the next node in the path.

If you ignore this node, the system just moves on to the next node. To indicate that the interaction node job is complete, you need to re-route the workflow by pressing the workflow route button in the Maximo Asset Management application. To simulate that in the API realm, the client code needs to apply the following api call:

POST <location uri>

Body:

{
  "interactioncomplete": 1
}

This indicates to the workflow engine that the interaction is complete.

Handling Wait Nodes

Wait nodes are listeners to the MBO (that is being workflowed) event. Effectively, the workflow waits on this event and when the event eventually happens, it moves to the next node. There is no handling of APIs for this node as this is backend event driven. So if an event comes from any API calls, MIF calls, or UI call for that MBO, the workflow moves to the next node in the path if the condition is met.

Handling Condition Nodes

Condition nodes are automatically evaluated by the workflow engine and the engine moves to the next node in the path after condition evaluation.

Edit this page on GitHub

Hierarchical Data: Dealing with Hierarchical Data

File import and export: Import