NextGen Rest API

Table of Contents

Introduction Authentication Native authentication LDAP based authentications API Home (/oslc)Querying Using Range Filters JSON schema Create and update Deleting Actions Invoking Non Interactive Workflows Actions Using Java Automation Scripts Bulk Creation of multiple resources with BULK Multiple operations with BULK Attachments Distinct Saved Queries Getting available queries for a OS Query method in java Query method in Automation Scripts Object Structure saved queries (osclause)Applications Query (appclause)KPI File Operations API Keys Maximo Management Interface APIs

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

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>

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 (1)

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 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 use 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 properties: * or comma separated attribute 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

Create → Script For Integration. Select object structure, type of script as Action Processing

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

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

Maximo can process multiple resources with multiple operations in a single transaction. The bulk process is supported only by using collection URLs. You can use the POST method and x-method override value BULK in the header.

The multiple resources and operations are provided in the message body with a JSON array. Each resource has an element called _data (reserved name) in which the data for the resource is provided. For update and delete, the resource has an element called _meta (reserved name)

Operation	Data Object Example
CREATE	{"_data":{"assetnum": "test-5","siteid":"BEDFORD", "description": "TS test 5"}}
UPDATE	{"_data":{"description": "NewDescription"},"_meta":{ "uri":"resource uri","method":"PATCH","patchtype":"MERGE"}}
DELETE	{"_meta":{ "uri":"resource uri", "method":"DELETE" }}

Unless there is a syntax type of error in your JSON data for bulk load, you will always get a response code of 200. However, you need to process the response to determine which resources were updated successfully

Creation of multiple resources with BULK

As the regular creation, each of the resources go through the validation process. And the response for each of the resources are shown in response JSON

The processing performs a Commit for each resource


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" }
}]

If the first asset failed the validation process by having the invalid site, the http response code is still be 200. However, the error message similar to the messages in the following example is shown

in the response


[{
"_responsedata": {
"Error": {
"message": "BMXAA4153E - [BEDFORDXXYY is not a valid site. Enter a valid Site value
as defined in the Organization Application.]",
"statusCode": "400",
"reasonCode": "BMXAA4153E",
"extendedError": {
"moreInfo": {"href":"error message uri"}
}}},{
"_responsemeta": {
"ETag": "1992365297",
"status": "201",
"Location": "oslc/os/mxasset/_VEVTVC0zNy9CRURGT1JE"
}}]

The first assets are successful and returns a 400 with an error message. The second asset returns a 201 with the URI to the asset resource

In Maximo Asset Management 7.6.0.8, the request JSON structures for bulk request is simplified. For example, _action at the data level is supported, where the _meta and _data are no longer needed


POST /oslc/os/mxapiasset
properties:*
X-method-override: BULK
[
	{
		"assetnum":"...",
		"siteid":"....",
		"description":"...",
		"_action":"Add"
	},
	{
		"href":"...",
		"description":"...",
		"_action":"Update"
	},
	{
		"href":"...",
		"_action":"Delete"
	}
]

Chaining bulk status


POST /oslc/os/mxapiwodetail?action=wsmethod:changeStatus
X-method-override: BULK

[{
	"status":"APPR",
	"href":"...."
},
{
	"status":"INPRG",
	"href":"...."
}]

Multiple operations with BULK

BULK can be used to perform a mix of create, update and delete of asset resources in a single transaction. To support this, in addition to _data which is used to provide the JSON data for a resource in a BULK transaction, you can also provide meta data by using _meta (reserved

name). The metadata that can be provided are

Metadata	ㅤ
method	It is the equivalent of the x-method-overrideheader discussed earlier in this document. When POSTing to create a new resource, there isneed to provide a method. To perform an update you provide the value `PATCH` and for a delete you provide the value `DELETE`
uri	It is the resource uri when processing an Updateor Delete. This is required when updating ordeleting a resource
patchtype	It allows the support of MERGE when processingan update (as described earlier in thisdocument)

The following example JSON data will complete these tasks:

Update an asset with a 'New Description'

Create a new asset (test-100)

Delete an asset


POST oslc/os/mxasset
X-method-override: BULK
[
  {
    "_data": {
      "description": "New Description"
    },
    "_meta": {
      "uri": "resource uri",
      "method": "PATCH",
      "patchtype": "MERGE"
    }
  },
  {
    "_data": {
      "assetnum": "test-100",
      "siteid": "BEDFORD",
      "description": "New Asset 100"
    }
  },
  {
    "_meta": {
      "uri": "resource uri",
      "method": "DELETE"
    }
  }
]

The first asset _meta data includes the URI to identify it, along with headers identifying that it is a

Patch (an update) with a type of Merge.

The second asset provides no meta data since it is a Create and no _meta data is applicable.

The third assets provides only the _meta data to identify the asset to be deleted

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 (osclause)


GET /oslc/os/mxasset?savedQuery=ITSTOCK

Applications Query (appclause)

The query is sourced from a Public Saved Query of an application. Using Asset and MXASSET as an example, the query can be associated with object structures in following ways:

In the the Object Structure application, select the Query Definition action, set type = appcluaseand select the query from the list

Set the authorization name of MXASSET as ASSET. In apimeta, the saved query names is listed as original name

Set the authorization name of MXASSET as MXASSET, then check load queries from all applications. If you have the access to ASSET, in apimeta, the saved query name shows as ASSET:QueryName

For information about OSLC Query, see this

http://www-01.ibm.com/support/docview.wss?uid=swg21972876

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.

Maximo Management Interface APIs

Maximo Management Interface APIs - IBM Documentation

A list of available MMI APIs is in the Monitor Environment Information dialog of the Logging application.

In order for the APIs to collect information from the Maximo environment, the system property mxe.oslc.webappurl must contain the host name of the Maximo server. For clustered environments, the load balancer, such as the HTTP server, must be specified. The default URL is http://localhost/maximo/oslc/

All MMI APIs can be protected through Maximo authorization by using signature options. The signature options must be associated with the Logging application. A signature option can be specified for an API by opening the Monitor Environment Information dialog in the Logging application, locating the API, and selecting a value in the Signature Option field.

The URL template for each API in the table is http://<host>:<port>/maximo/oslc/members/<memberid>/<api>, where <memberid> is the Maximo cluster member.

API	URL template	Description
JVM	http://<host>:<port>/maximo/oslc/members/<memberid>/jvm	Provides information about the JVM that is hosting the Maximo application. Some of the information that is provided includes the start time, the JVM vendor, and the JVM version.You can also drill down, by using links, to provide information about the JVM system properties and the JVM arguments.
Operating system	http://<host>:<port>/maximo/oslc/members/<memberid>/opsystem	Provides information about the operating system for the Maximo run time. Some of the information that is provided includes the OS type, version, architecture, and the number processors that are available.
Database	http://<host>:<port>/maximo/oslc/members/<memberid>/dbinfo	Provides information about the database that is used by the Maximo application. Some of the information that is provided includes the database version or vendor information, and driver information.The resource also provides links to the database connection pool details.
MBO Count	http://<host>:<port>/maximo/oslc/members/<memberid>/mbocount	Provides MBO count information. The resource also provides links to the MBO and the MboSet class. This class can be useful when you are trying to resolve out of memory (OOM) or performance issues.
Memory	http://<host>:<port>/maximo/oslc/members/<memberid>/memory	Provides information about the server heap and non-heap memory usage. All units are in Megabytes (MB).
EventTopicTree	http://<host>:<port>/maximo/oslc/members/<memberid>/eventtopic	Provides information about the Maximo event subscription tree. The resource describes information about event topics, such as add asset or update work order, and the listeners that are associated with those topics.
Logger	http://<host>:<port>/maximo/oslc/members/<memberid>/loggers	Provides information about the state of a Maximo logger. The logger name can be provided to the API by using the oslc.where query parameter. An example of a parameter is oslc.where=oslc:shortId=”maximo.script”. This resource provides information about the automation script logger. API consumers specify the logger name by using the oslc:shortId property for this API to provide information about the logger, which includes the log level, and active state.
Integration Queues	http://<host>:<port>/maximo/oslc/members/<memberid>/queues	Provides information about state of a Maximo integration queue. The resource allows consumers of the API to test the connectivity/read/write to the queue and to browse messages in the queue spi:browseMessage property. By default the API shows only the top 5 messages in the queue. You can control that number by using the query string oslc.where=spi:count=10. This query shows the top 10 messages in the queue Note: Browsing messages is a costly call and browsing too many messages simultaneously can cause memory or performance issues in the server.
JAXP	http://<host>:<port>/maximo/oslc/members/<memberid>/jaxp	Provides information about the JAXP providers in the server.
Object Structure Cache	http://<host>:<port>/maximo/oslc/members/<memberid>/oscache	Provides information about the Object Structure Cache. It identifies cases where there are invalid entries in the Object Structure tables that might cause cache corruption.
Threads	http://<host>:<port>/maximo/oslc/members/<memberid>/threads	Provides information about the threads in the JVM, such as the current thread count, peak thread count, and if there are any deadlocks. It also provides a link to enumerate the threads in the system at that instant. The API consumer can check for thread states and lock information about each thread.