Updated

Added support to group by for ResourceSet
Added support to sync for ResourceSet
Added support to bulk for ResourceSet
Added new examples about new API in TestOSLCAPI.java.
Fixed bugs
Removed references to javax.xml.bind.DatatypeConverter.printBase64Binary because that API is not available on Android. It now uses commons-codec to get base64 support.

Maximo Rest Client 1.0 Released!

Added support to arbitrary parameters for Resource/ResourceSet
Added support to arbitrary headers for get/post/patch/merge/delete
Added support to order by for ResourceSet
Added support to invoke action with properties for Resource
Added new examples about new API in TestOSLCAPI.java.
Fixed bugs

I. Introduction

The Maximo REST client library provides a set of driver APIs that can be consumed by a Java-based web component that wants to interface with a Maximo instance. The client APIs use the Maximo NextGen REST/JSON APIS, which were originally inspired by Linked Data principles. By using this API, you are able to create, update, delete, and query Maximo business objects by using Maximo integration framework object structures.

The following main components are included in this client library:

[MaximoConnector (com.ibm.maximo.oslc.MaximoConnector)] - The driver API that establishes the authenticated HTTP session with the Maximo server. It is used by the other APIs to create, update, delete, and query Maximo data. The authentication and the other basic information can be configured using an [Options (com.ibm.maximo.oslc.Options)] object.
[ResourceSet (com.ibm.maximo.oslc.ResourceSet)] - This API represents a collection of Maximo resources of a given type. The type is determined by the object structure definition that it refers to. In effect, this api is equivalent to the concept of the Maximo MboSet.
[Resource (com.ibm.maximo.oslc.Resource)] - Each member of a ResourceSet is represented by an instance of this class. This class is equivalent to the concept of a Maximo business object (MBO).
[Attachment (com.ibm.maximo.oslc.Attachment)] and [AttachmentSet (com.ibm.maximo.oslc.AttachmentSet)] - These APIs represent the attached documents, or doclinks, in Maximo Asset Management. These APIs are always associated with a Resource object.

Currently the only supported data format is JSON, and we have two flavors of JSON: the lean and the namespaced. The lean format is supported starting in Maximo Asset Management version 7.6.0.1 and is the recommended format to use, because it uses less bandwidth.

II. Install

2.1 As a Maven dependency

2.1.1 Central repository

Maximo REST Client is available in the Maven Central repository as an open source artifact. It can be included in a Maven project easily by adding the dependency to the project. The Maven will automatically handle the maven transitive dependencies.

Create a new Maven project.
Add following dependency to your pom.xml file.

Latest Release

<dependency>
    <groupId>com.ibm.maximo</groupId>
    <artifactId>maximo-restclient</artifactId>
    <version>1.0</version>
</dependency>

Last Release

<dependency>
    <groupId>com.ibm.maximo</groupId>
    <artifactId>maximo-restclient</artifactId>
    <version>0.1</version>
</dependency>

2.1.2 Local repository

You can use a local repository if the Internet is unavailable or it is difficult to access the central repository for some reason. The client can be installed locally. After the installation, it can be included in a Maven project as well.

Run mvn clean install -Dgpg.skip at the dictionary of library.
Create a new Maven project
Add following dependency to your pom.xml file.

<dependency>
	<groupId>com.ibm.maximo</groupId>
	<artifactId>maximo-restclient</artifactId>
	<version>VERSION</version>
</dependency>

Where VERSION is the version you gave this artifact in the pom.xml.

2.2 As a Java library

If the Maven environment is unavailable, the Maximo REST Client can be used as a regular reference library in the Java project. Because the client depends on javax-json, the javax-json and commons-codec libraries are also needed.

You can get it from http://repo1.maven.org/maven2/org/glassfish/javax.json/1.0.4/ or use the Maven dependency as shown in the following code:

<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>javax.json</artifactId>
    <version>1.0.4</version>
</dependency>
<dependency>
	<groupId>commons-codec</groupId>
	<artifactId>commons-codec</artifactId>
	<version>1.1</version>
</dependency>

When the javax.json-1.0.4.jar, commons-codec-1.1.jar, and maximo-restclient-0.1.jar files are ready, add them to the Java project as common reference libraries.

III. Usage

Maximo Resources, or object structures, represent a graph of related Maximo business objects (Mbos) that provides an atomic view/object to create, update, delete, and query the releated set of Mbos.

We will use the Work Order, Purchase Order and Companies Resources as examples to show you how to use the Maximo REST Client.

Note: The use cases can be found at TestOSLCApi.java.

3.1 Query a work order for work order set (mxwodetail)

The following instruction shows how to query a work order from Maximo Asset Management by using the Maximo RET Client Library.

3.1.1 Connect to Maximo Asset Management

Before you connect, it is necessary to set up the authentication and environment information in Options.

For authentication, the username, password and authentication method are required. The value for authentication method can be "maxauth", "basic" or "form". The sample code is shown in the following code:

Options option = new Options().user("maxadmin").password("maxadmin").auth("maxauth");

Note: For Maximo Asset Management Multitenancy, take the tenant code = "00", as an example, in the following Options.

Options option = new Options().user("maxadmin").password("maxadmin").auth("maxauth").mt(true).tenantCode("00");

For environment, it needs the data mode setting, host, port, and if the debug is enabled. The sample code is shown in the following code:

option.host("host").port(7001).lean(true);

Based on this configuration, connect to the Maximo Asset Management by using MaximoConnector:

MaximoConnector mc=new MaximoConnector(option).debug(true);
mc.connect();

Or directly by using the following code:

MaximoConnector mc = new MaximoConnector(new Options().user("maxadmin").password("maxadmin").lean(true).auth("maxauth").host("host").port(7001));
mc.connect();

3.1.2 Query the work orders

Create a ResourceSet, which is a query for the Approved Work Order Set. The selected items are wonum, status.

By object structure name:

ResourceSet rs = mc.resourceSet("mxwodetail").select("wonum","status").where((new QueryWhere()).where("status").equalTo("APPR")).fetch();

By RESTful URI :

ResourceSet rs = mc.resourceSet(new URL("http://host:port/maximo/oslc/os/mxwodetail")).select("wonum","status").where((new QueryWhere()).where("status").equalTo("APPR")).fetch();

There is a paging API for thw Maximo REST Client that allows forward and backward paging of data by the client.
- For the page size = 10:

ResourceSet rs = mc.resourceSet("mxwodetail").select("wonum","status").where((new QueryWhere()).where("status").equalTo("APPR")).pageSize(10).fetch();

For the default paging, which assumes that a default page size is configured on the the Resource's object structure. If no page size is configured, this directive is ignored, and all records matching the query filter is returned:

ResourceSet rs = mc.resourceSet("mxwodetail").select("wonum","status").where((new QueryWhere()).where("status").equalTo("APPR")).paging(true).fetch();

For the stablepaging:

ResourceSet rs = mc.resourceSet("mxwodetail").select("wonum","status").where((new QueryWhere()).where("status").equalTo("APPR")).stablePaging(true).fetch();

Turn to next or previous page:

rs.nextPage();
rs.previousPage();

For stable paging where currently only scrolling forward is supported, a call to previousPage() results in an error.

Get the ResourceSet in JSON:

JsonObject jo = rs.toJSON();

Note: we support JSON output in byte array. Try the following code:

byte[] jodata = rs.toJSONBytes();

Each Resource has a unique ID. It is easy to get the specific work order by it. In the following example, you can see how to get the Work Order (_QkVERk9SRC8xMDAw) directly.

By specific URI:

String woUri = "http://host:port/maximo/oslc/os/mxwodetail/_QkVERk9SRC8xMDAw";

By using the ResourceSet

Resource re = rs.fetchMember(woUri);

Or by using MaximoConnector:

MaximoConnector mc = new MaximoConnector(new Options().user("maxadmin").password("maxadmin").lean(true).auth("maxauth").host("host").port(7001));
mc.connect();
Resource re = mc.resource(woUri);

By index, which will query the member resource from the resourceset collection and will not make a trip to the server:

Resource re = rs.member(0);

To query more data from the server for this resource, consider using the load() and reload() APIs on the Resource.

re.reload("wonum","status","assetnum","location","wplabor.craft");

OR simply

re.reload("*");

Get the work order in JSON or byte array:

JsonObject jo = re.toJSON();
byte[] joBytes = re.toJSONBytes();

3.1.3 Traverse the Work Orders

In some case, you might need to traverse some or all work orders. There are some helpful API in the Maximo REST Client.

Connect to the Maximo Asset Management:

MaximoConnector mc = new MaximoConnector(new Options().user("maxadmin").password("maxadmin").lean(true).auth("maxaut

Maximorestclient

Install / Use

README