IBM Maximo REST API Guide

Maximo Asset Management supports a feature called a Saved Query where a pre-built query for an application, such as Work Order Tracking, allows users to retrieve a common set of data (for example, a list of approved work orders). After reading this section, you can use the saved query capability to query records based on defined filter criterion with RESTful API call.

Available Queries for Object Structure

For each object structure, you can find all authorized (for the requesting user) saved queries by using the apimeta API call. See the following MXAPIASSET object structure example:

Attribute	Description
ispublic	If the query is public
name	Query name
title	Query description
href	Query url

GET oslc/apimeta/{osname}

For example, if we would like to get the pre-defined saved query for mxapiasset, we will run

GET oslc/apimeta/mxapiasset

Expected result:

{
  "queryCapability": [
    {
      "ispublic": true,
      "name": "All",
      "href": ".../oslc/os/mxasset"
    },
    {
      "ispublic": true,

There are four types of saved queries for Object structures in Maximo Asset Management.

Query Method (method, java method)

This query is defined in object structure’s definition class. It is sourced from an annotated method name. This option is used if a method was implemented for query purposes. Since there are no default query methods provided, this method would be a custom code implementation by using the following code example, @PreparedQuery("http://maximo.nextgen.asset#publicAssets")

@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);
}

Automation Script (script)

This query is run with a predefined automation script. 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 Query Clause (osclause)

The where clause for this query is defined in this query definition. For this type, you enter a Where clause, provide a name and description for the query, and flag whether the query is public or not. The Where clause format is similar to a Where clause that is used in an application list tab. Public queries are available to everyone to use. Non-public queries are only available to the query owner.

Applications Query (appclause)

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

Open Object Structure APP. Select Query Definition from Action List, set type = appcluase, select the query from the list.
Set the authorization name of MXASSET as ASSET. In apimeta, the saved query names will be listed as original name.
Set the authorization name of MXASSET as MXASSET, then check load queries from all apps. If you have the access to ASSET, in apimeta, the saved query name will show as ASSET:QueryName

For the detail of OSLC Query, see Ability to set query definitions and action associations in the Object Structures application.

Execute saved query for object structures

For Maximo Asset Management RESTful APIs, the query parameter for all of the saved query is savedQuery. This parameter is case-sensitive. If you apply SAVEDQUERY or savedquery, the parameter is ignored as an invalid query parameter without any errors.

In the queryCapability Section of APIMeta, the links for saved queries are already provided. Take ITSTOCK as an example:

GET /oslc/os/mxapiasset?savedQuery=ITSTOCK

Execute KPI clause for Object Structure

By using RESTful APIs, you can get more detail for a KPI by calling its where clause with saved query as follows:

GET /oslc/os/mxapiasset?savedQuery=KPI:ASSETKPI

The API takes the where clause from KPI and apply it to the MXASSET object Ssructure. The KPI clause is not be available in APIMETA and you have to make sure the where clause in KPI can be applied to the main object of the object structure. Otherwise, you will get the SQL error.

Query Template

A query Template is an object structure-based template that includes the query related definition. In the collection level, you can define the page size, search attributes, and timeline attribute in the template. In the attribute level, you can add selected attributes, give the ordered information, and override the title of attribute.

After reading this section, you will be able to create a query template for object structures, apply the template to object structure, and get selected attribute and ordered collection back.

Currently, the query template can be created by JSON API. Using MXAPIASSET as an example, you complete the following tasks where the object structure is named MXAPIQUERYTEMPLATE for querytemplate:

Create query template

Normally, the query template can be created by API - MXAPIQUERYTEMPLATE. Let’s start with create one for MXAPIASSET. Assume we have following definition for this template:

Page Size = 5
Search Attributes = assetnum, description
Timeline Attribute = changedate

POST /oslc/os/mxapiquerytemplate?lean=1

Body:

{
  "pagesize": "5",
  "searchattributes": "assetnum,description",
  "timelineattribute": "changedate",
  "intobjectname": "MXAPIASSET"
}

Note this template currently doesn’t have any selected attribute defined. When we apply it to MXAPIASSET, the response body of members will only contain 5 items with href. Assume the auto generated query template name is 1001, the restful call will look like

GET /oslc/os/mxapiasset?querytemplate=1001&collectioncount=1&lean=1

Expected Response Info:

{
  ...
  "responseInfo": {
    "nextPage": {
      "href": "nextpagelink"
    },
    "totalCount": 1152,
    "pagenum": 1,
    "href": "currentpagelink",

The searchAttribute and timeline attribute are defined in query template already. We could use oslc.searchTerm and tlrange to filter the result set.

GET /oslc/os/mxapiasset?querytemplate=1001&oslc.searchTerm="PUMP"&tlrange=-3M&collectioncount=1&lean=1

Expected Response Info:

{
  "responseInfo": {
    "nextPage": {
      "href": "next page link"
    },
    "totalCount": 43,
    "pagenum": 1,
    "href": "current page link",
    "totalPages": 9

Search strings

On Query Templates it is possible to search strings on by literal value or by words.

Tokenized search is the default way the search is performed.

GET oslc/os/mxapimeter?oslc.select=metername,description&searchAttributes=metername&oslc.searchTerms=meter color

The request above would produce a SQL query below:

SQL select [attributes] from meter  where (metername like '%METER%' or metername like '%COLOR%')

For searching a string in its integrity use two pairs of double quotes

GET oslc/os/mxapimeter?oslc.select=metername,description&searchAttributes=metername&oslc.searchTerms=""oil level""

The request above would produce a SQL query below:

SQL select [attributes] from meter  where (metername = 'OIL LEVEL')

While working with searchTerms remember:

Using 1 pair of double quotes performs a tokenized search;
Using 2 pairs of double quotes on search terms performs a literal search;
It is the same result using a pair of double quotes or no quotes;
Using % on search terms might mess the result;
Avoid using single quotes.

Set up query template with attributes

In most of the use cases we would like to have selected attribute pre-defined in query template. Here is the basic format of attribute, in general, it follows the standard oslc query attribute format and defined per attribute. Query template framework will calculate the select (oslc.select), sortby (oslc.orderBy) from definition when we apply the template to object structure.

Basic

POST /oslc/os/mxapiquerytemplate
{
  "pagesize": 5,
  "intobjectname": "MXASSET",
  "querytemplateattr": [
    {
      "selectattrname": "assetnum",
      "selectorder": 1
    },

Assume the templatename is 1002, the restful call will look like:

GET /oslc/os/mxapiasset?querytemplate=1002

The result will return 5 records per page sorted by site in ascending order, each of the object will contain the assetnum, status and siteid.

Response of one record

{
  "assetusercust_collectionref": "link to assetusercust",
  "assetnum": "1001",
  "_rowstamp": "1195406",
  "status_description": "Not Ready",
  "assetopskd_collectionref": "link to assetopskd",
  "assetmeter_collectionref": "link to assetmeter",
  "status": "NOT READY",
  "assetmntskd_collectionref": "link to assetmntskd",

Advanced Fromat (*)

We also provide the capability to use the complex syntax with * notation for more advanced requirement.

Assume we want to build the following clause

oslc.select=rel.allwo{wonum,siteid,exp.formula,pm{pmnum,description}},location{location,description,allwo.wonum},assetnum,allwo.wonum

It can be translated to x.y.z* syntax as following:

rel$allwo.wonum*
rel$allwo.pm.description*   
assetnum
rel$allwo.siteid*   
location.location*
allwo.wonum
rel$allwo.exp$formula*
location.descrption*
rel$allwo.pm.pmnum*

Differences between basic and advanced format

It is easy to get confused about syntax, let’s take a deeper look at what’s the differences among relName.AttrName, objName.attrName and rel$relName.attrName, taking MXAPIPO as an example and assume we need to deal with this relationship: Name = VENDOR, Parent = PO, Child = COMPANIES and we want to get the name of company.

vendor.name: It’s used to get the name of first company while we don’t have companies defined as child object in MXAPIPO, it will only take the first record back even it could be one to many. companies.name: It will convert to companies{name} by Query Template and used when we have COMPANIES as our child object in MXAPIPO (and relationship could be VENDOR), then we have to use objectname instead of relationship name to get the record back, and it will return multiple records if the result is one to many. rel$vendor.name: It will convert to rel.vendor{name} by Query Template and used when we don’t have COMPANIES as our child object in MXPO but we ant to get all records back if the result is one to many

Edit this page on GitHub

Query (GET): Select distinct data

Create, Update and Delete (POST/PATCH/DELETE): Create and update

Saved queries