ibmmaximorestjsonapis/maximorestclient

The Maximo REST client library provides a set of driver API's which can be consumed by an JAVA based web component that would like to interface with a Maximo instance.

Updated

1. Added support to group by for ResourceSet
2. Added support to sync for ResourceSet
3. Added support to bulk for ResourceSet
4. Added new examples about new API in TestOSLCAPI.java.
5. Fixed bugs
6. 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!

1. Added support to arbitrary parameters for Resource/ResourceSet
2. Added support to arbitrary headers for get/post/patch/merge/delete
3. Added support to order by for ResourceSet
4. Added support to invoke action with properties for Resource
5. Added new examples about new API in TestOSLCAPI.java.
6. 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.

1. Create a new Maven project.
2. 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.

1. Run mvn clean install -Dgpg.skip at the dictionary of library.
2. Create a new Maven project
3. 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("maxauth").host("host").port(7001));
mc.connect();

• Get a work order set from the Maximo server:

ResourceSet rs = mc.resourceSet("mxwodetail").pageSize(10).

• Travel through the work orders that are on the current page:

for(int i=0;i<rs.count();i++){
	Resource re = rs.member(i);
	...//other operations
}

• Travel through all of the workorders.
• Only available in github. Issue is encountered when pushing code to Maven.

for(int i=0;i<rs.totalCount();)
{	
	for(int j=0;j<rs.count();j++)
	{
		Resource re = rs.member(j);
	}
	i+=rs2.count();
	if(!rs2.hasNextPage())
	{
		break;
	}
	rs2.nextPage();
}

3.1.4 Disconnect from Maximo Asset Management

• End the session with Maximo Asset Management after you finish the work:

mc.disconnect();

3.2 Create a new work order (mxwodetail)

The following instruction shows how to create a new work order by Maximo Rest Client.

3.2.1 Get the work order set

• Connect to Maximo Asset Management

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

• Get the existing work order list from the Maximo server to support the creation.

ResourceSet rs = mc.resourceSet("mxwodetail");

3.2.2 Create a new work order

• Create a valid JSON object that has the essential information, such as siteid for BEDFORD.

For non-lean, add the prefix before the attribute:

JsonObject jo = Json.createObjectBuilder().add("spi:siteid", "BEDFORD").add("spi:description", "test").build();
Resource re = rs.create(jo);

For lean, skip the prefix, and use the attribute directly:

JsonObject jo = Json.createObjectBuilder().add("siteid", "BEDFORD").add("description", "test").build();
Resource re = rs.create(jo);

• To work with child objects, as per the Object Structure definition, you can just make it part of the work order json. The following code shows the creation of a planned labor record or object that is a child of the work order:

JsonObject wplJo = Json.createObjectBuilder().add("skilllevel", "FIRSTCLASS").add("craft", "ELECT").build();
JsonArray wpLaborArray = Json.createArrayBuilder().add(wplJo).build();
jo.add("wplabor",wpLaborArray );

Note: The sample uses the lean format.

3.2.3 Return with the properties

By default, the create operation will not return any content of the newly created work order. Because many attributes use default values or calues that auto-generated at the server based on Maximo business logic, it often makes sense to get the final representation of the newly created resource.

Instead of reselecting the work order, which makes a round-trip to the server, it is easy to get the resource content in response information when a new work order is created by the Maximo REST Client.

For non-lean:

Resource re = rs.create(jo,"spi:wonum", "spi:status","spi:statusdate","spi:description");

or simply:

Resource re = rs.create(jo,"*");

For lean:

Resource re = rs.create(jo,"wonum", "status","statusdate", "description");

or simply:

Resource re = rs.create(jo,"*");

3.3 Update a purchase order (mxpo)

To update a resource, you can use either the update() or the merge() APIs. The difference between these APIs how they handle the related child objects in the Resource. An example that uses the PO Resource (mxpo) best illustrates this difference. This example will reference two of the Maximo business object that is contained in the Resource: the PO(parent) and POLINE(child).

In this scenario, you have an existing purchase order that has one PO Line child objects. If you wanted to update the PO with a new PO Line entry, which is the second line, you use the merge() api. The merge process goes through the request "poline" array of objects and matches them up with the existing set of polines, which is the current one, and it will compare the rdf:about, if it is present in the new poline, to determine if this line is an existing poline or a new one. If it determines that it is a new one, it will proceed with creating this new poline, and you have two polines. If it finds a match, it will proceed with updating the matched one with the requested poline content, and you have one updated poline. If there are other existing polines, they won't be updated by the process.

If you use the update() API instead of the merge() API for this scenario, have only one PO Line. If there are any other PO Lines, they will be deleted. This deletion is because the update process treats the "poline" element as an atomic object and will update it as a complete replacement. Processing will insert the new PO Line or update the matching PO Line and delete all the other existing PO Lines for that PO.

The update() and merge() behavior applies only for child objects and not for the root object. The root object is always updated by using either API, assuming some attributes of that object have been changed.

In another scenario, you have an exsiting PO that has three polines(1,2,3) and you want to complete the following actions:

1. delete poline#1
2. update poline#3
3. create a new poline#N

You need to do the following tasks:

Use the update() API and send three polines (2,3,4).

The update API will see that the request does not contain PO Line 1 and so it will delete it. It will skip the update of PO Line 2 because no attributes were change, update PO Line 3, and add a new line, PO Line 4.

After the update, the PO has lines 2,3 and 4.

So if you used the merge() API instead, the only difference is that PO Line 1 is not deleted. The PO has lines 1,2,3 and 4.

3.3.1 Update the poline in the purchase order

You can create a new PO Line on a purchase order and then update this purchase order by using the update() API to update the existing PO Line or replace the existing one by the a new PO Line.

If the polinenum(s) is matched, Maximo Asset Management will update the existing poline with a new array.

If the polinenum(s) is not matched, Maximo Asset Management will delete the existing poline array and create a new one with the new array. The array size will be equal to the new array.

• Connect to Maximo Asset Management:

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

• Get a Resource from ResourceSet:

ResourceSet reSet = mc.resourceSet("MXPO").fetch();
Resource poRes  = reSet.member(0);

• Build a valid JsonObject for adding a new Child Object for Resource:

JsonObject polineObjIn = Json.createObjectBuilder().add("polinenum", 1).add("itemnum", "560-00").add("storeloc", "CENTRAL").build();
JsonArray polineArray = Json.createArrayBuilder().add(polineObjIn).build();
JsonObject poObj = Json.createObjectBuilder().add("poline", polineArray).build();

• Create a new poline:

poRes.update(poObj);

• Build a valid JsonObject for updating that Child Object in the Resource:

JsonObject polineObjIn2 = Json.createObjectBuilder().add("polinenum", 2).add("itemnum", "0-0031").add("storeloc", "CENTRAL").build();
JsonArray polineArray2 = Json.createArrayBuilder().add(polineObjIn2).build();
JsonObject poObj2 = Json.createObjectBuilder().add("poline", polineArray2).build();

• Update the Resource:

poRes.update(polineObj2);

At the end of it, you have a PO with 1 POLINE. The steps below explains how it happens:

The server-side framework will attempt to locate a POLINE that has the polinenum 2 and will not find any, because there is only a POLINE with polinenum 1).

• It will add a new POLINE that has polinenum 2.

• It will delete all the remaining POLINEs that are not present in the JSON object, which will result in PO Line 1 being deleted.

3.3.2 Merge the poline in the purchase order

You can create a new poline on a purchase order and then merge this purchase order by using another poline object. You can create a new PO Line on a purchase order and then merge this purchase order by using the merge() API to update the existing line or add an additional line.

If the poline(s) is matched, Maximo Asset Management will update the existing poline with new array, which is similar to using the update() method.

If the poline(s) is not matched, Maximo Asset Management will add the new poline array to the existing poline array.

• Connect to Maximo Asset Management:

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

• Get a Resource from ResourceSet:

ResourceSet reSet = mc.resourceSet("MXPO").fetch();
Resource poRes  = reSet.member(1);

• Build a valid JsonObject for adding a new Child Object for the Resource:

JsonObject polineObjIn = Json.createObjectBuilder().add("polinenum", 1).add("itemnum", "560-00").add("storeloc", "CENTRAL").build();
JsonArray polineArray = Json.createArrayBuilder().add(polineObjIn).build();
JsonObject poObj = Json.createObjectBuilder().add("poline", polineArray ).build();

• Update the Resource:

poRes.update(poObj);//this creates a POLINE with polinenum 1.

• Build a valid JsonObject for merging the Child Object in the Resource:

JsonObject polineObjIn3 = Json.createObjectBuilder().add("polinenum", 2).add("itemnum", "0-0031").add("storeloc", "CENTRAL").build();
JsonArray polineArray3 = Json.createArrayBuilder().add(polineObjIn3).build();
JsonObject polineObj3 = Json.createObjectBuilder().add("poline", polineObjIn3).build();

• Merge the Resource:

poRes.merge(polineObj3);//this will create a POLINE with polinenum 2.

At the end of it, you have a PO that has 2 POLINEs. The steps below explains how it happens:

The server-side framework will attempt to locate a POLINE that has the polinenum 2 and will not find any, because there is only a POLINE that has polinenum 1.

• It will add a new POLINE with polinenum 2.

• It will keep the remaining lines, in this case POLINE with polinenum 1, as is.

3.4 Delete a service request (mxsr)

You can delete an existing work order by using the Maximo REST Client.

3.4.1 Get an existing service request

• Connect to Maximo Asset Management:

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

• Get the basic service request set from the Maximo server:

ResourceSet rs = mc.resourceSet("mxsr").

• Get an existing service request:

By using a specific URI:

String venUri = "http://localhost:7001/maximo/oslc/os/mxsr/_U1IvMTE3Mw--";

By using ResourceSet:

Resource re = rs.fetchMember(srUri);

Or byusing MaximoConnector:

Resource re = mc.resource(srUri);

By index:

Resource re = rs.member(0);

3.4.2 Delete the service request

• Call the deleteResource method of MaximoConnector:

mc.deleteResource(srUri);

• Call the delete method of Resource:

re.delete();

3.5 Attachments

Attachments in Maximo Asset Management are documents, files, or images that are attached to a resource, such as a work order or service request. The following example shows how to add and delete an attachment on a work order. In the resource definition, the DOCLINKS object, which is a child of the work order object, supports the attachment data.

3.5.1 Create an attachment for an existing work order.

• Connect to Maximo Asset Management:

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

• Get the basic work order set from the Maximo server:

ResourceSet rs = mc.resourceSet("mxwodetail").

• Get an existing work order from the work order set:

By specific URI:

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

By using ResourceSet:

Resource re = rs.fetchMember(woUri);

By using MaximoConnector:

Resource re = mc.resource(woUri);

By index (be careful with the range):

Resource re = rs.member(0);

• Get the attachment set of this work order:

AttachmentSet ats = re.attachmentSet();

• Initial the document data:

String str = "hello world @ "+ Calendar.getInstance().getTime().toString();
byte[] data = str.getBytes("utf-8");

• Initial the attachment files:

Attachment att = new Attachment().name("attachment.txt").description("test").data(data).meta("FILE", "Attachments");

• Attach the file to the work order:

By default,

att = ats.create(att);

Note: For the custom property name for doclinks such as "customdoclink",

att = ats.create("customdoclink",att);

3.5.2 Get the data from the attachment

• Get attachment from AttachmentSet
• Get an existing attachment from Maximo Asset Management:

Attachment att = ats.member(0);

• Get the attachment doc:

byte[] data = att.toDoc();

• Get the attachment meta:

JsonObject attMeta = att.toDocMeta();
JsonObject attMeta = att.fetchDocMeta();

• Get the attachment by using MaximoConnector directly by calling the attachment URI. Because the Resource has a unique ID, the attachment has an ID as well. In the following example, you can see how to get an attachment that has the ID 28 and that is attached to a work order (_QkVERk9SRC8xMDAw):

String attUri = "http://host/maximo/oslc/os/mxwodetail/_QkVERk9SRC8xMDAw/DOCLINKS/28";
Attachment att = mc.attachment(attUri);
byte[] data = mc.attachedDoc(attUri);
JsonObject attMeta = mc.attachmentDocMeta(attUri);

3.5.3 Delete an attachment

• Get an existing work order from a work order set:

By specific URI:

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

By using ResourceSet:

Resource re = rs.fetchMember(woUri);

Or by using MaximoConnector:

Resource re = mc.resource(woUri);

By index (be careful with the range):

Resource re = rs.member(0);

• Get the AttachmentSet from the work order:

AttachmentSet ats = re.attachmentSet();

• Get the attachment from the AttachmentSet:

By index:

Attachment att = ats.member(0);

By using a specific URI:

String attUri = "http://host/maximo/oslc/os/mxwodetail/_QkVERk9SRC8xMDAw/DOCLINKS/28";

By using AttachmentSet:

Attachment att = ats.fetchMember(attUri);

Or by using MaximoConnector:

Attachment att  = mc.attachment(attUri);

• Delete the attachment:

By using the attachment, which is useful when you already have the attachment:

att.delete();

By using MaximoConnector, which is useful when you have only the URI:

mc.deleteAttachment(attUri);

3.6 Saved query

Maximo Asset Management supports a feature that is called a Saved Query that is a pre-built query for an application, such as the Work Order Tracking application, which allows a user to easily retrieve a common set of data, for example, a list of approved work orders. Assuming public saved queries are present for an application, you can use the savedQuery() API to query records based on defined filter criterion. You also must ensure that the authorized application is set accordingly for the object structure you plan to use.

Take the "OWNER IS ME" query for the Work Order Tracking (WOTRACK) application as an example, which assumes that the MXWODETAIL object structure is setup with "WOTRACK" as the authorized application.

• Query the data:

ResourceSet rs = mc.resourceSet("mxwodetail").savedQuery(new SavedQuery().name("WOTRACK:OWNER IS ME")).select("*").fetch();

The select("*") statement queries all attributes for the filtered set of mxwodetail. As mentioned earlier, you can do a partial resource selection, such as select("wonum","status").

You can also do further filtering with the saved query.

• Query the data

ResourceSet rs = mc.resourceSet("mxwodetail").savedQuery(new SavedQuery().name("WOTRACK:OWNER IS ME")).where(new QueryWhere().where("status").in("APPR","WAPPR")).select("wonum","status","statusdate").fetch();

3.7 Terms search

This feature is used mostly for text search. This feature needs the server-side object structure to be set up with the searchable attributes. For example, if it is setup with "description", you can use the hasTerms() API to set the searchable terms.

For example, you can select all the resources from oslcmxsr whose description contains email or finance.

• Connect to Maximo Asset Management:

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

• Fetch the ResourceSet:

ResourceSet res = mc.resourceSet("OSLCMXSR").hasTerms("email", "finance").select("spi:description", "spi:ticketid").pageSize(5).fetch();

3.8 Action

Actions are functional components of a resource that perform specific tasks, such as changing the status of a resource or moving a resource. This example uses the changeStatus action as an example (the changeStatus method is annotated marked as a WebMethod in the WorkOrder Service),

• Connect to Maximo Asset Management:

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

• Get the ResourceSet where status is equal to WAPPR:

ResourceSet reSet = mc.resourceSet("MXWODETAIL").where((new QueryWhere()).where("status").equalTo("WAPPR")).fetch();

• Get the first member ofthe ResourceSet:

Resource re = reSet.member(0);

• Build the JsonObject for changing:

JsonObject jo = Json.createObjectBuilder().add("status","APPR").add("memo","approval").build();

• Invoke the action:

re.invokeAction("wsmethod:changeStatus", jo);

References

Java API

maximorestclient's Issues

Retrieving related objects using the "rel.<relationship>" approach not (yet) supported?

It looks like the "rel" option for retrieving (nested) related objects is not yet supported by the java library.

Example for retrieving all the assets of a specific item:
https:///maximo/oslc/os/mxitem?&collectioncount=1&oslc.select=itemnum,rel.ASSET{assetnum, description}&oslc.where=itemsetid%3D%22myItemSet%22+and+itemnum%3D%22myItemNum%22

This approach is documented in chapter "4.1. Select Clause example" of the IBM Maximo REST API (https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html).

Are there any plans for support of this part of the API?

Thanks

Danny Bols

Unable to make the API call

Hi this may not be a defect, but more of understanding issue.
I am trying to connect to enterprise implementation of ISM. Since I do nto have the specific auth information , I have tried withe all 3 authentication and have got same error.

When I connect and post that try to access a resource .. i get an HTML content back (which actually is login page).

Can you please help . .of how to try it !

Test Issue

Test Issue

Upload attachment with url is not supported

Currently it only supports upload attachment with file. Upload attachment with URL is currently not supported.

ResourceSet only supports ordering by descending

The URLs that the ResourceSet builds only support the ordering of parameters in descending order

MaximoConnector should log URIs sooner when debug mode set.

When in debug mode, MaximoConnector does not always log URIs that it attempts to access before accessing them.

For example, in connect(), the URI is not logged until after con.getResponseCode() is called. However, con.getResponseCode() can throw connection errors if the URI is invalid (e.g. incorrect port). This can make it difficult for a Maximo REST client library user to debug the issue.

Error Handling Inquiry

Hi,

Is there an error handling component? E.g. a request timeout?

Thanks,
J

Issue with Namespace

Hi,

I am having an issue with namespace specific for mxitem. I set lean=1 to skip namespace, and got the "oslc:message": "BMXAA4147E - Item set null does not exist. Enter a valid Item Set as defined in the Organization application." error message.

However, when I sent the same JSON payload with namespace "spi". It is working fine.

Problem is the source system that we are integrating with does not allow namespaces in a JSON payload.

Let me know.

Appreciated!!!

Is there a way to support notEquals in WhereClause

I'm trying the convert the following query into a resource set.
"http://host:9092/maximo/oslc/os/cls?oslc.select=*&oslc.where=spi:resource!="NET";"

However, I don't find a way to check for "notEquals" in the where clause. Is there any workaround on this?

MaximoConnector has no support for proxy servers

MaximoConnector handles the creation of HttpURLConnection objects for generated URIs, but offers no direct way to set up a proxy server for these connections. You can set up a global proxy server for the VM by setting system properties at VM invocation or by calling System.setProperty, but this is not ideal. In my case, I'm dealing with a finicky proxy server, and having more fine-grained control from within my application would be helpful.

When using lean and form auth, the login url generated is "http:///maximo/oslc?&lean=1/j_security_check" which causes errors

I'll have a PR to fix

No support for apikey authentication method

The current implementation doesn't include support for the apikey authentication method.
This is important as customers upgrade to the latest versions and the MAS environment.

Please add this support.
I know that it can be added because a client has added the code but I am not not able to share the code at this time.

Bulk Sync

Hi,

Is a Bulk Sync be implemented in the near future?
Currently, there is only bulk add, update, or sync with only 1 object.
It would make sense to have it because integration could involve quite a few records that might be an add or a change.

Many Thanks

Options defaults to port=80 for SSL connections

If https() is called on an Options object, but port(num) is not called, the Options object retains the default value of 80 for the instance variable port. This should probably default to 443 for SSL-encrypted connections.

However, https() should not override the value set by port(num), even if port has been set to the value 80 by such a call.

Defaulting to 80 for SSL-encrypted connections is likely to lead to occurrences of java.net.ConnectException: Connection refused that have an unclear cause.

ResourceSet methods fetchMember and create do not set Resource to isLoaded

The ResourceSet methods fetchMember and create return a Resource object created from JSON obtained from the server within the same function call. However, they do not set the isLoaded flag in the returned Resource object to true. An examination of the code reveals the same issue with other methods, including sync and mergeSync (possibly others).

Subsequent method calls on the Resource object (notably toJSON) initiate a load call on the Resource object before returning a value. This creates an extraneous call to the web service and discards properties arguments passed to the original loading method. As a result, the user is unable to get a reduced-scope JSON object from Resource objects when using these methods, while also generating unexpected calls to the server.

Possible solutions:

1. Expose the isLoaded variable in Resource through package-private methods or constructors, allowing partner classes to create "pre-loaded" Resource objects.
2. Set isLoaded to true by default in the Resource constructors that take JsonObject parameters. Make the constructors package-private.

Neither solution exposes the isLoaded variable to the public interface, but Solution 2 seems superior. It is simpler to implement and requires no extra work within ResourceSet or other partner classes. The current library design offers no obvious reason for users to construct Resource objects directly. If that need arises, static factory methods could be added to enable controlled construction.

MaximoConnector.create throws unexpected error on Bad Request response

In MaximoConnector.create, on a response code >= 400, the library attempts to decode the HTTP error stream as a JsonObject. When the response code is 400 (Bad Request), the error stream contains only the response headers, which are not valid JSON, resulting in javax.json.stream.JsonParsingException being thrown. Because the error thrown is an unexpected subclass of IOException instead of an OslcException, the error is not informative ("Unexpected char") and difficult to handle gracefully.

This condition may exist in other methods that do similar processing, including MaximoConnector.getAttachmentData.

Also note that con.getErrorStream() can return null in some conditions, which would result in Json.createReader throwing NullPointerException.

Documentation needs to highlight that http.keepAlive Java property should be set to false

Developers using this should ensure that the http.keepAlive Java property is set to false to ensure that the HTTP requests are closed when they are finished.

There are two ways this can be resolved:
1 Add in code to the client so it does not set the keep-alive header
2 Amend the documentation to make it clear that this is required