Maximo JSON API- How To Contents

Maximo JSON API- How To
V1 - Updated: 03/02/2016
V2 - Updated: 03/10/2016
V3 - Updated: 03/21/2016
Contents
Introduction .............................................................................................................................................. 2
How do I filter data from a collection? ..................................................................................................... 2
How to just get a count of records that match a query filter? ................................................................. 5
How do I do use sub-selects in a query?................................................................................................... 5
How do I bookmark a record for a given resource type (say mxwodetail)? ............................................. 6
How do I get a list of all bookmarked records for a given resource type (say mxwodetail)?................... 6
How do I use classification attribute search in a query? .......................................................................... 6
How do I load all assets that have at least a meter? ................................................................................ 7
How do I create attachments?.................................................................................................................. 7
How to get internal values for a domain as well as the description associated with the domain value? 7
Does the REST API support CORS? ............................................................................................................ 8
How to make timeline/date range queries using the REST api?............................................................... 9
How do I get a list of valid status for a stateful object? ......................................................................... 11
How do I invoke the getList method in my attribute field validation class? .......................................... 11
How do I get a list of valid actions for a stateful object? ........................................................................ 11
How can I get a add custom JSON to the Object structure JSON? ......................................................... 11
1
Introduction
This document provides examples on 'how to' use the Maximo JSON API for
specific scenarios or features.
How do I filter data from a collection?
There are various ways to filter data in the JSON api. Below is a list
Saved Query
Traditionally saved query refers to Maximo saved queries which are associated
with classical maximo apps.
However, saved queries can be now associated directly with the Object
structures using the Object Structure app. Saved queries in Object Structures
can be implemented using Automation Scripts, sql, java methods.
The java method flavor of saved query is called a parameterized query. It lets
developers define methods in an OS definition class.
There are 2 basic requirements for defining such methods:
1.The methods have to declare a MboSetRemote as the first parameter. All other
parameters needs to be of java literal type.
2.The methods need to get annotated with the PreparedQuery annotation. The
annotation needs to provide a unique string value for that class.
A sample is shown below (this is a simple one and is shown just to give an
example. You can do that by just using a oslc.where=assettype="XYZ")
@PreparedQuery("some unique string")
public void getAllAssetsOfType(MboSetRemote assetSet,String
assetType)
2
{
assetSet.setQbe("assettype","="+assetType);
}
Below is a sample rest api call to invoke this method:
GET
/os/mxasset?savedQuery=getAllAssetsOfType&sqp:assetType=FLEET
As you can see, the method name is passed as the value of savedQuery
parameter value and the assetType method parameter value is passed using the
query parameter sqp:<method param name>.
SQL saved queries
the simple way to create them would be to design your query using oslc.where
and searchTerms and then invoke the action savethisquery on that collection.
A sample of such REST request is shown below
POST
/os/mxasset?oslc.where=assettype="VAN"&oslc.searchTerms="oil
change"&searchAttributes=assetnum,description&action=savethisquery
{
"clausename":"VansThatNeedOilChange",
"description":"vans that need oil change",
"ispublic":true
}
3
The sql where would be (ASSETTYPE = 'VAN') and ((UPPER(DESCRIPTION)
like '%OIL CHANGE%' OR ASSETNUM like '%OIL CHANGE%'))
OSLC Where
This mimics the Maximo QBE grammar. Users can specify a filter criteria based
on either AND or OR clause (but never both together). A sample for each is
shown below
GET
/os/mxasset?oslc.where=status="OPERTING" and statusdate>"some ISO
861 date" and assettype in ["VAN","FLEET"] and
location.status="OPERATING"
Now the same clause if we add an opmodeor=1, it starts treating all the "and"s as
"or"s. So below is the sample
/os/mxasset?oslc.where=status="OPERTING" and statusdate>"some ISO
861 date" and assettype in ["VAN","FLEET"] and
location.status="OPERATING"&opmodeor=1
You also see how we can do nested queries using the dot notation location.status="OPERATING"
Search Terms
This is used for wildcard/text searches. A sample below shows how to leverage it
with searchAttributes.
/os/mxasset/<_someassetid>/openwo?oslc.searchTerms="pump","broken
"&searchAttributes=description,asset.description
4
This will search for occurrence of those tokens in either work order description or
related asset description. A record matches this if any of the search tokens
appears in any of these search attributes.
How to just get a count of records that match a query filter?
<collection uri>?count=1&oslc.where=...&savedQuery=...
The collection URI is pointing either to an Object Structure or a related object, for
example:
http://host:port/maximo/oslc/os/mxasset?savedQuery=ITASSETS&count=1
Note this works with any combination of filters - search terms, classification
attribute search, saved queries, oslc where's.
How do I do use sub-selects in a query?
Sub-selects are used for filtering a resource collection based on another related
query. For example say we wanted to select all work orders based on a subselect on assetnum. The syntax of the query is shown below.
http://localhost:7001/maximo/oslc/os/mxwodetail?lean=1&_lid=wilson&_lpwd=wil
son&subselects=asset.assetnum=<asset where
uri>&oslc.select=wonum&oslc.where=status in ["APPR"]
The asset where clause can be as below (both relative uri and absolute uri
should work):
/os/mxasset?oslc.where=assettype=”IT”
Note we need to encode the assettype=”IT” first and then encode the combined
uri and then use that combined encoded value in the query parameter with the
<> wrapped around.
5
Also the sub-selects have the relationship name as the first token [“asset”] and
then the attribute name [assetnum] on which we would apply the in clause.
How do I bookmark a record for a given resource type (say mxwodetail)?
Just use HTTP POST with a http request header x-method-override of PATCH to
the URI /os/mxwodetail/<resource id>?action=bookmark
POST /os/mxwodetail/<resource id>?action=bookmark
x-method-override: PATCH
<no POST body needed>
Make sure that the OS has an app assigned to it (in the Object structure
configuration – authapp attribute) and the root object (say Workorder for
mxwodetail) has a unique id attribute.
How do I get a list of all bookmarked records for a given resource type (say
mxwodetail)?
Just use the query parameter /os/mxwodetail?bookmarked=1&oslc.where=...
Make sure that the OS has an app assigned to it and it has a unique id attribute.
How do I use classification attribute search in a query?
Just use the query parameter attributesearch as shown below
/os/mxasset?attributesearch=[size:>=1]&oslc.where=...
This searches for all assets that have a class spec attribute called size with a
value >=1. If we did not set that :>=1 and kept the query as
attributesearch=[size], it would have only fetched assets that have size as a
spec attribute. For combining multiple attributes together in the search follow the
example below
/os/mxasset?attributesearch=[size:>=1;attr2;attr3:=5]&oslc.where=...
6
This will search for assets that have a class spec attribute size with a value
greater than 1 and an attribute named attr1 and attribute name attr2 with a value
of 5, all and-ed together.
How do I load all assets that have at least a meter?
This question can be generically restated as – how do I fetch all resources than
have at least one child record of a certain type. The query is described below:
GET
/os/mxasset?oslc.where=assetmeter.metername="*"
Effectively it just uses the relation assetmeter from ASSET to ASSETMETER –
called ASSETMETER and then uses the “.” notation to refer a required attribute
of the ASSETMETER (say metername which is the primary key for the
assetmeter) and compare that to NOT NULL (the attr=”*” implies that the attribute
is not null). So if we wanted to do that same for all WORKORDER's that have at
least one WORKLOG, we would use the where clause like below
GET
/os/mxwodetail?oslc.where=worklogappt.class=”*”
How do I create attachments?
Attachments can be created in 2 ways using the JSON api. We need to add
DOCLINKS object to the Object structure. You can add DOCLINKS to any object
in the Object Structure, provided there is a relationship from that object to
doclinks. One way to do would be to POST to the collection URI for the
attachments.
How to get internal values for a domain as well as the description
associated with the domain value?
This is a very common requirement where MBO attributes are bound to a domain
and the client needs not only the domain external value (which is the mbo
7
attribute value), but also its internal value (the value the Maximo recognizes) and
its associated description.
Fortunately, the API framework recognizes a domain bound attribute from its
metadata and associates the description in the JSON automatically from the
domain cache. The description attribute is named like below <domain bound
attribute name>_description.
In order to get the internal value, just add the query parameter &internalvalues=1
to the query URI and it will add the corresponding internal value to the json as
<domain bound attribute name>_maxvalue.
Below is an example
/os/mxwodetail?oslc.select=status,wonum&internalvalues=1
{
“member”:[
{
“wonum”:”1001”,
“status”:”WAPPR”,
“status_description”:”Waiting For Approval”,
“status_maxvalue”:”WAPPR”
}
V..
]
}
Does the REST API support CORS?
8
Its supported in the JSON framework. It has to be configured by an admin inside
maximo using the 3 properties
mxe.oslc.aclalloworigin
mxe.oslc.aclallowmethods
mxe.oslc.aclallowheaders
You can set the first one to be * or your IP from where you plan to connect. You
can set the 2nd one to POST,GET,DELETE,OPTIONS and the 3rd one to
maxauth,x-method-override,patchtype,content-type,accept.
So as long as the admin does not configure those – the apis are not accessible
using CORS.
How do we get internal values for domain bound attributes?
Just add the query parameter &internalvalues=1 for the GET query URL. You will
see the value appear in the json as <attribute name>_maxvalue. An example for
the status attribute is shown below:
{
“status”:”MY_WAPPR”,
“status_internal”:”WAPPR”
}
How to make timeline/date range queries using the REST api?
There are 2 ways to do this. The first way (not the most elegant – but will work) is
to just use oslc.where like below
oslc.where=statusdate>”some iso date” and statusdate<=”some iso date”
In this way the client side ends up calculating all the “iso dates” and that
sometimes can get difficult. A more elegant way to do this would be to use the
timeline query capability.
9
TimeLine queries support querying around a date attribute within a specified
range. For example is the date attribute is elected to be status date and the date
range in -90D (i.e. list all records that have had a status change in the last 90
days). The sample query is shown below
http://localhost:7001/maximo/oslc/os/mxasset?_lid=wilson&_lpwd=wilson&lean=1
&tlattribute=statusdate&oslc.orderBy=-statusdate&tlrange=-90D
The important things to note here are the 2 query parameters – tlattribute and
tlrange. If we would like to query around a specified date, we can provide the
time line query as below
http://localhost:7001/maximo/oslc/os/mxasset?_lid=wilson&_lpwd=wilson&lean=1
&tlattribute=statusdate=2015-12-08T16:35:0305:00&oslc.select=statusdate&oslc.orderBy=-statusdate&tlrange=%2B-4W
this fires a query to fetch all records that have a status change in the +- 4 weeks
since 2015-12-08T16:35:03
The important thing to note here is the way we set the timeline base date
statusdate=<date in iso 8601 format>. If none is provided, its assumed to be
system current date.
Also note that the tlrange=+-4W – where the '+' is url encoded as %2B. The
supported units are
Y – Year
M - month
D – day
W – Week
h – hour
m - minute
s – second
10
How do I get a list of valid status for a stateful object?
Just add the var allowedstates to the oslc.select / oslc.properties clause. An
example is shown below
GET
/os/mxwo?oslc.select=wonum,description,status,allowedstates
How do I invoke the getList method in my attribute field validation class?
Often you would need to get the list of allowed values for a attribute in the MBO.
Chances are that you already have that logic the MBO attributes field validation
class. To access that logic use the following query as below
/os/mxwo/_QkVERk9SRC8xMDAw?action=getlist&attribute=status
As you can figure out, the attribute name is specified using query parameter
attribute and the action is getlist.
How do I get a list of valid actions for a stateful object?
Just add the variable allowedactions to the oslc.select / oslc.properties clause.
An example is shown below
GET
/os/mxwo?oslc.select=wonum,description,status,allowedactions
It will evaluate all sigoptions/permissions and associated conditions registered for
the actions and then produce the filtered list of actions allowed for this MBO
instance.
How can I get a add custom JSON to the Object structure JSON?
One efficient way to do that would be to create an Object Structure definition
class and override the checkBusinessRules method as shown below.
11
public int checkBusinessRules(MboRemote mbo, MosDetailInfo mosDetInfo,
Map<String, Object> ovrdColValueMap) throws MXException, RemoteException
{
Map<String,Object> jsonMap = new HashMap<String,Object>();
jsonMap.put("notfeventmessage", getNotificationHistMessage(mbo));
ovrdColValueMap.put("json", jsonMap);
return super.checkBusinessRules(mbo, mosDetInfo, ovrdColValueMap);
}
In this code, getNotificationHistMessage (code not shown for brevity) method
generates an arbitrary JSON object and attaches that to the Object structures
json for that mbo with the key notfeventmessage. The resulting json will be like
below
{
V.
“notfeventmessage”: {V}
}
The key to which we attach this to the ovrdColValueMap is “json” - which tells the
serializer to include this json in the output.
12
Please send any corrections or suggestions to Tom Sarasin at [email protected]
13