MaximomizeMaximomize/
⛰️NextGen REST API
Search
⛰️

NextGen REST API

Created
Aug 4, 2021 09:03 AM
Tags
integration
Status
Published
Created Date
Table of Contents
IntroductionAuthenticationAPI Home (/oslc)QueryingCreate and updateDeletingActionsAutomation ScriptsBulkAttachmentsDistinctSaved QueriesFile OperationsAPI Keys

Introduction

Significantly enhanced support for querying Maximo data - subselects, related object queries,
multi-attribute text search, custom queries (java/scripting).
  • Support for system level actions - bookmarking, notifications, e-sig, image association and so on.
  • Tight integration to automation scripts - query, actions, custom APIs.
  • Enhanced REST support for Maximo Integration Framework (MIF) standard services - support
JSON data type for those service methods.
  • Metadata support using JSON schema.
  • Supports dynamic query views.
  • Support for GROUP BY queries.
  • Supports custom JSON elements that are appended to the object structure JSON.
  • Integration with the Maximo Asset Management cache framework.
  • Integration with Maximo Asset Management formulas.
  • Integration with federated Maximo business objects (MBOs)
You can also download the official document from below
Maximo_Nextgen_REST_API.pdf
2121.3KB

Authentication

Native authentication
With native authentication, Maximo Asset Management is configured to manage the user repository along with the user credentials. The REST API expects the HTTP request with a MAXAUTH request header that has a base64 encoded userid:password. The following example shows a sample request:
POST /oslc/login
maxauth: <base64 encoded user:pass>
<no body required>
 
LDAP based authentications
  1. BASIC authentication
With BASIC authentication, authentication credentials in the application server are presented in the following format:
POST /oslc/login
Authorization: BASIC <base64 encoded user:pass>
<no body required>
  1. Form Authentication
With FORM authentication, authentication credentials are presented in the following format:
POST /j_security_check
Content-type: application/x-www-form-urlencoded
j_username=<userid>&j_password=<password>
Since this FORM request is a form encoded POST, the user ID and password values need to be URL encoded values. The response for this request will have the jsessionid cookie along with Ltpa token cookies (for Websphere). These cookies need to be reused for the subsequent API calls

API Home (/oslc)

The API root URL is /oslc. A GET call on the API root fetches a JSON object with necessary links to get the details of the current Maximo runtime environment. Explore the links like systeminfo, whoami, installedProducts, serverMembers APIs along with details like the current date time, language, and the calendar of the deployed Maximo system. The following list describe these API links:
  • systeminfo: The GET /oslc/systeminfo API provides the system information JSON for the deployed Maximo instance
  • Whoami: The GET /oslc/whoami API provides the profile JSON for the user that is logged in
  • installedProducts: The GET /oslc/products API provides the list of installed add-ons for Maximo Asset Management
  • serverMembers: The GET /oslc/members API is the root API for the Maximo Management Interface (MMI)
The response JSON contains the list of live Maximo servers as per the Maximo serversession table. Note that it takes some time for the Maximo runtime environment to detect a down server and hence it is possible that the response shows some servers that may not be operating at that instant.
The resulting JSON will have links to drill down into individual servers and examine the various aspects of the Maximo runtime server health, such as memory, MBO count, integration caches, threads, and database connections.
  • License: The GET /oslc/license API provides the list of available license keys for the various
Maximo components in this deployment.
  • Apimeta: The GET /oslc/apimeta API provides the metadata for all the object structures that are API eligible, that is the usewith value of reporting, integration and oslc
The metadata for each object structure includes the schema information as well as the available queries (saved queries). Additionally, the metadata provides the creation API URL and the (security) authorization application name

Querying

Being able to fetch data from related objects leveraging existing Maximo relationships without
additional configuration
Paging
e.g.
GET /oslc/os/mxasset?oslc.select=assetnum,location,description,status&oslc.pageSize=10
totalCount and totalPages are not displayed by default. You can enable totalCount and
totalPages by including the query parameter collectioncount=1 .Personally this can cause the server to get stuck
If you set the mxe.oslc.collectioncount system property to 1, the totalCount and totalPages
parameters are included by default as part of the responseInfo.
Database aggregation functions
Maximo REST API supports using database aggregation (maxminavg, sum, count, and exists) functions on related MboSets. For example, to apply these functions on the open work orders for an asset, all
the aggregation functions are used in the following API
GET /oslc/os/mxasset/{restid}?oslc.select=assetnum,openwo.actlabhrs._dbavg,openwo.actlabhr

s._dbsum,openwo.actlabhrs._dbmax,openwo.actlabhrs._dbmin,openwo._dbcount
The format for the sum,avg,max,min functions is <relation name>.<target attrname>.<operation>.
Note that the supported operations are dbsum (for sum), dbavg (for avg), dbmax (for max) and dbmin (for min). The format is always a dot (.) separated by a three token format that includes
Using where clause
Use the oslc.where query parameter. In the example, the whereclause filters assets that are based on locations and the asset status.
GET /oslc/os/mxasset?oslc.where=status="OPERATING" and location.status="OPERATING"
The locations MBO is not part of the MXASSET object structure. The format for the dot notation
(location.status) is <rel1>[.rel2]*.attr1. As you can make out, the dot notation can be nested.
Operator for filtering
Operator
Description
Usage
=
equals
status=”APPR”
>=
Greater than equals
priority>=
>
Greater than
startdate>”iso date”
<
Less than
startdate<”iso date”
⇐
Less than equals
linecost⇐200.
!=
Not equals
priority!=
in
In clause
location in [“A”,”B”,”C”], priorityin [1,2,3]
This query language is data type sensitive and the double quotes "" is used for character based
attributes and for dates (ISO Format). Boolean values are always represented either as 1/0 or
true/false (no quotes)
For the LIKE clause, you can use the following variations:
oslc.where=status=”%APPR%”
If you want to use starts with:
oslc.where=status=”APPR%”
If you want to use ends with:
oslc.where=status=”%APPR”
To use null value queries, you can use the star (*) notation. For example, a not null check is
completed by using the following format where - status is not null.
oslc.where=status="*"
If you want to use the is null check:
oslc.where=status!=”*”
If you want to ise a not in clause, you can use the following format:
location!= “[BR300,BR400]”
Note that this not in clause currently only works for ALN attributes.
Double quotes "" is used for character based attributes and for dates (ISO Format e.g. 2020-02-06T00:00:00). Numeric values are represented in their corresponding ISO formats (that is non localized format). Boolean values are always represented either as 1/0 or true/false (no quotes).
oslc.where=status in ["OPERATING","ACTIVE"] and priority=3 and statusdate>"ISO date

string" and linear=false
 
Using Range Filters
Range filters are used to support range based queries. For example, if you want to only get assets within a certain date range and priority range, you can use this feature.
oslc.where=priority>1 and priority<=3 and
installdate>="1999-02-06T00:00:00-05:00" and
installdate<"2009-02-06T00:00:00-05:00"
JSON schema
GET /oslc/jsonschemas/mxwodetail

Create and update

💡
For update use x-method-override: PATCH
to return attributes after an update use proporties: * or names
An extra request header called patchtype is used with a value of MERGE. This instructs the server to match the child objects - like assetmeter with the existing`assetmters` for this asset. If a match is found, that assetmeter gets updates with the request assetmeter.
POST /oslc/os/mxasset
{
	"assetnum":"ASSET1",
	"siteid":"BEDFORD",
	"description":"my first asset"
}

Deleting

DELETE /oslc/os/<os name>/{rest id}
You get a response of 200 OK if the delete is successful. Starting 7608 you are able to do the same by using the following API:
POST /oslc/os/<os name>/{rest id}
x-method-override: PATCH
{
	"_action":"Delete"
}

Actions

To see the available actions for an object structure. Use any existing wonum or id
GET /oslc/os/mxwo?oslc.where=wonum="1001"&oslc,select=allowedactions
Invoking Non Interactive Workflows
To invoke ABC workflow for the asset:
POST <uri of the asset 1001>?action=workflow:ABC
x-method-override: PATCH
Actions Using Java
Add WebMethod to any existing Maximo application service by extending the service class and adding a method. This example is from extending the Workorder Service psdi.app.workorder.WOService
@WebMethod
public void approve(@WSMboKey(value="WORKORDER") MboRemote wo, String memo) {
	wo.changeStatus("APPR",MXServer.getMXServer().getDate(), memo);
}
To invoke a web method. Also set the request header x-method-override as PATCH for invoking this action API, as this is operating on an existing mbo
POST <uri of the workorder 1001>?action=wsmethod:approve
x-method-override: PATCH
{
	"memo":"Testing"
}
Actions can be also defined in object structures application Actions using Automation Scripts
  1. Create → Script For Integration. Select object structure, type of script as Action Processing
  1. In Object Structure application. Select the Action Definition action and set the script as an action to the object structure. Name the action same as the name of the script
      2. notion image
For example,
mbo.changeStatus(“OPERATING”,False,False,False,False)
Invoke this script similar to the following request:
POST <uri of the asset 1001>?action=TEST
x-method-override: PATCH
 
 

Automation Scripts

importPackage(Packages.psdi.server);
var resp = {};
var site = request.getQueryParam("site");
var woset = MXServer.getMXServer().getMboSet("workorder",request.getUserInfo());
woset.setQbe("siteid","="+site);
var woCount = woset.count();
resp.wocount = woCount;
var srset = MXServer.getMXServer().getMboSet("sr",request.getUserInfo());
srset.setQbe("siteid","="+site);
var srCount = srset.count();
resp.srcount = srCount;
resp.total = srCount + woCount;
var responseBody = JSON.stringify(resp);
To invoke
GET /oslc/script/countofwoandsr?site=ABC
{
	"wocount":100,
	"srcount":20,
	"total":120
}

Bulk

POST oslc/os/mxasset
X-method-override: BULK
[{
"_data":{
"assetnum": "test-5", "siteid": "BEDFORD", "description": "TS test 5"}
}, {
"_data":{
"assetnum": "test-6", "siteid": "BEDFORD", "description": "TS test 6" }
}]

Attachments

GET oslc/os/mxasset/{rest id}/doclinks/{id}

Distinct

GET /os/mxapiasset?distinct=siteid&oslc.where=...
Also workflow management is there too

Saved Queries

Getting available queries for a OS
GET oslc/apimeta/mxasset
The response will be like
{ 
"queryCapability": [
{ "ispublic": true,
	"name": "All",
	"href": ".../oslc/os/mxasset"
	},
{ "ispublic": true,
	"name": "publicAssets",
	"javaMethod": true,
	"href": ".../oslc/os/mxasset?savedQuery=publicAssets"
}...
Query method in java
This query is defined in object structure’s definition class. It is sourced from an annotated method name.
@PreparedQuery("http://maximo.nextgen.asset#publicAssets")
public void publicAssets(MboSet assetSet) throws MXException, RemoteException
{
	String whereusercust="assetnum not in (select assetnum from assetusercust)";
	assetSet.setUserWhere(whereusercust);
}
Query method in Automation Scripts
This configuration allows for more complex queries than are normally supported by a query clause.
The creation of a script for an object structure can be defined as a query clause. When you define a
script as a query clause, the script can be configured as an object structure query for use with the
JSON API
Object Structure saved queries
GET /oslc/os/mxasset?savedQuery=ITSTOCK
KPI
GET /oslc/os/mxasset?savedQuery=KPI:ASSETKPI

File Operations

Import
POST oslc/os/mxapimeter?action=importfile&lean=1
METERNAME,METERTYPE,READINGTYPE,DESCRIPTION,MEASUREUNITID
RUNHOURS2,CONTINUOUS,DELTA,Run Hours2,HOURS
TEMP-F2,GAUGE,,Temperature in Fahrenheit2,DEG F
Export
add _format=csv to any rest call to export as CSV
GET
/oslc/os/mxapiasset?lean=1&oslc.select=assetnum,siteid,description,location&oslc.pageS
ize=10&oslc.orderBy=-assetnum&_format=csv

API Keys

When an API key is assigned to the external client, the external client can access and interact with data in the Maximo system by using the API key as an apikey query parameter or an apikey request header in REST API calls.