Process Automation

Hi Everyone,
 
Welcome to Useful Tiny Little Things, a series of topics published in the Process Automation blog. My name is Leandro Cassa and I work at IBM. The purpose of this series is to provide useful simple things that we sometimes have no idea exist. These tips apply to any products based on Tivoli's process automation engine.
 
Today the topic is REST (Representational State Transfer) application programming interface (API), which provides a ways for external applications to query and update application data in Tivoli's process automation engine.
 
Using the REST API is quite simple and is configuration free. Most process automation engine-based products are ready to use it after a default installation.
 
The purpose of this post is to quickly go through the essentials of the REST API. For additional information please refer to the Maximo Asset Management Infocenter.
(http://publib.boulder.ibm.com/infocenter/tivihelp/v49r1/index.jsp)
 
 
The REST API is part of the integration framework and can be used to Create, Read, Update and Delete (CRUD) and provides two resource data types: XML or JavaScript Object Notation (JSON) format. By default, the system is set up to use XML.
 
It uses serializer classes registered in the System Properties (Go To > System Configuration > Platform Configuration > System Properties) as follows:

mxe.rest.serializer.mbo.xml
mxe.rest.serializer.os.xml
mxe.rest.serializer.mbo.json
mxe.rest.serializer.os.json

The XML output is similar to the integration framework format. And it is possible to extend the existing serializers to generate different outputs.
 
 
To see the REST API working is just a matter of typing a URL on the browser. For example, try the following URL:

http://<your_host_and_port>/maxrest/rest/os/mxperson

 
The URI (Uniform Resource Identifier) have three parts: maxrest/rest which stands for the REST API reference os which means Object Structure is the resource being used, in this case you could also have mbo for the Business Object resources mxperson which is the object being used.
 
In this post we only use os resource, you can find all available Object Structures under your system at Go To > Integration > Object Structures or even create a new one yourself.
 
Notice that the system requested your user and password. This post assumes you are using the system administrator and therefore you should have full access to the records. The process automation engine provides different security options for the REST API. Refer to the information center provided earlier for more information.
 
It is possible as well to get the output for a single record, as shown in the following example:

http://<your_host_and_port>/maxrest/rest/os/mxperson/1

Where 1 is the PERSONUID. If referring to a CI object, it would be CIID and not the CINUM; this is actually the unique ID of the table that represents the object.
 
To filter by a specific field, use web-like HTTP arguments. For example:

http://<your_host_and_port>/maxrest/rest/os/mxperson?displayname=~eq~MAXADMIN&status=~eq~ACTIVE

The displayname and status are the fields to filter by. the operator ~eq~ stands for equal. MAXADMIN is the person I'm looking for and I'm also filtering by ACTIVE users. Using the first URL in this post, you can identify all fields that you can use to filter by. There are many operators (like ~eq~) that can be found in the information center reference provided at the beginning of this post, this post is limited to the most basic operations possible through the REST API.
 
The following script shows how you could use simple Javascript to interact with process automation engine-based systems' REST API. It is important to understand that any programming language can be used, since it supports the HTTP protocol

function requestData() {
  var request = new XMLHttpRequest();
  // set your hostname here
  var host = "http://<your_host>";
  // set your REST URI here
  var uri = "/maxrest/rest/os/mxperson";
  // your query parameters
      var parameters = "PERSONID=~eq~MAXADMIN";
  // defines which function is called when state change
  request.onreadystatechange = state_change;

  request.open("GET", host + uri + "?" + parameters, true);
  // send authorization credentials, base64 encoded for "maxadmin:maxadmin"
  request.setRequestHeader("Authorization", "Basic " + "bWF4YWRtaW46bWF4YWRtaW4=");

  request.send();
    
  function state_change() {
    if (request.readyState == 4) { // 4 = "loaded"
      if (request.status == 200) { // 200 = OK
          // get the XML root element
          var root = request.responseXML.firstChild;
          // get all the tags named DISPLAYNAME
          var displayNameTags = root.getElementsByTagName("DISPLAYNAME");
          // gets the first displayName tag value
          var displayName = displayNameTags[0].firstChild.nodeValue;
          alert(displayName);
        }
        else {
          alert(request.status + " - " + request.statusText);
      }
    }
  }
}

  Be aware that the code above is not going to work if the script is not on the same domain as your process automation engine-based system. By default, web browsers do not accept cross-site scripts and HTTP requests. You might not hit this issue if you are using a language other than Javascript.

 
By modifying the script above you can play with the XML results using Javascript DOM API, with the URI through the uri variable defined and with the parameters, using the parameters variable.
This post only covers the Read part of CRUD. To create, update and delete records you must use the http POST method. See the information center for more information.
That is it for now. Hope this helps you getting started with the REST API. Do not hesitate to add comments if you have questions or feedback.

 
 
Leandro Cassa