Blogs

SOBRE ESTE BLOG

Welcome to the Process Automation Blog, where you can read the perspectives from BSM experts. This Blog provides insights into the Process Automation solution, as well as technical details about specific IBM products.

Links

TWEETS RECENTES

Using Rest API on Tivoli's process automation engine, an introduction

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 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:

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 URL above returns the list of person records on the target system.

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:

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

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.