In a recent exchange on the IBM developerWorks forum for Maximo, it was discussed how best to query Maximo through the Integration Framework that is configured for LDAP. Getting data from an LDAP-based Maximo is similar to an environment that is configured to use native authentication, with a few subtle differences. This article will demonstrate how to query for data using the REST API that is found in Maximo 7.5.0.3 and higher, and the JSON API that is found in Maximo 7.6.0.2 and higher.
The information detailed below is available in an IBM article (available as a PDF or as a web page) titled “Maximo NextGen REST API”. Based on questions I have received from our customers and other Maximo professionals, there seems to be some confusion on how to use this information.
There are many tools available that will facilitate communication to and from Maximo using the REST and JSON APIs. This article uses the Postman application which can be downloaded for free here.
Before we dive into the “How” we should discuss the “Why”. What are some reasons for wanting to use these Maximo APIs? Here are a few:
- Creating new records
- Modifying existing records
- Querying Maximo data from an external application
- Performing calculations on Maximo data such as averaging a cost, finding maximum cost or summing a budget from an external application
- Creating lists based on Maximo data
- Querying related records from an external application such as retrieving a list of work orders for a given asset
- Deleting data
- Replacing data
Querying Maximo Data with Native Authentication
Let’s start off with a simple scenario: show me all Person records that start with the string ‘CAR’. Note that we are using the Maximo demonstration data for these examples.
To start, we need two pieces of information to complete a successful API call:
- Maximo API URL
- Maximo Username and Password
However, just having the Maximo Username and Password is not good enough to make an API call. We’ll need to encode those credentials before calling the API.
The credentials will need to be Base64 encoded using the username:password format. For example, if your credentials were maxadmin:maxadmin, your Base64 encoded credentials would be bWF4YWRtaW46bWF4YWRtaW4=. You can use this online utility to perform a successful encode. Place your username:password in the first box and click the > ENCODE < button. Your Base64 encoded string will appear in the box below.
Now we can fire up our Postman application to perform the calls to Maximo.
JSON API
For the JSON API, our Maximo URL will look like this:
http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"
Substitute your Maximo host name for the maximo_host, and include a port number if necessary.
Next, we’ll need to supply the credentials as an HTTP Header. The header key for Native Maximo Authentication is maxauth. The header value will be your Base64 encoded credentials. Finally, we’ll use the HTTP Method of GET. It comes together like this:
GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%" maxauth: bWF4YWRtaW46bWF4YWRtaW4=
In Postman:
Maximo will perform a wildcard search so all person records that contain the string CAR will be returned. In the case of the sample or demonstration data, that is one record.
The result will be something similar to this:
{
"member": [
{
"href": "http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O"
}
],
"responseInfo": {
"href": "http://maximo_host/maximo/oslc/os/mxperson?lean=1&oslc.where=personid=%22CAR%25%22"
},
"href": "http://maximo_host/maximo/oslc/os/mxperson"
}
When using the JSON API you will get a URI back. This URI is especially useful as you can use this URL to query, perform updates, or perform a delete action on a specific record. In this case you can take the URL and place that back into Postman to perform a GET action. You will receive all of the pertinent record information for that specific record.
http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O
REST API
For the REST API, our Maximo URL will look slightly different; however, the concept of authentication remains the same. Substitute your Maximo host name for the maximo_host, and include a port number if necessary:
http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
It comes together like this:
GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR% maxauth: bWF4YWRtaW46bWF4YWRtaW4=
In Postman:
The results are:
{
"QueryMXPERSONResponse": {
"rsStart": 0,
"rsCount": 1,
"MXPERSONSet": {
"PERSON": [
{
"rowstamp": "[0 0 0 0 0 106 -81 -98]",
"ACCEPTINGWFMAIL": true,
"ADDRESSLINE1": "62 Winthrop Street",
"BIRTHDATE": "1962-08-22T00:00:00-04:00",
"CITY": "Medford",
"COUNTRY": "US",
"DISPLAYNAME": "Tara Carson",
"FIRSTNAME": "Tara",
"HIREDATE": "1997-08-01T00:00:00-04:00",
"LASTEVALDATE": "2001-08-01T00:00:00-04:00",
"LASTNAME": "Carson",
"LOCTOSERVREQ": true,
"NEXTEVALDATE": "2002-08-01T00:00:00-04:00",
"PERSONID": "CARSON",
"PERSONUID": 21,
"POSTALCODE": "02155",
"PRIMARYEMAIL": "tara.carson@helwig.com",
"PRIMARYPHONE": "781-555-6247",
"STATEPROVINCE": "MA",
"STATUS": "ACTIVE",
"STATUSDATE": "2003-09-25T15:44:38-04:00",
"STATUSIFACE": false,
"TRANSEMAILELECTION": "NEVER",
"WFMAILELECTION": "PROCESS",
"PHONE": [
{
"rowstamp": "[0 0 0 0 0 96 57 -106]",
"ISPRIMARY": true,
"PHONEID": 145855,
"PHONENUM": "781-555-6247",
"TYPE": "WORK"
}
],
"EMAIL": [
{
"rowstamp": "[0 0 0 0 0 93 114 125]",
"EMAILADDRESS": "tara.carson@helwig.com",
"EMAILID": 145855,
"ISPRIMARY": true,
"TYPE": "WORK"
}
]
}
]
}
}
}
To get information about a single record in the REST API, you need to reference the Unique ID of the record. In this example, since we are referencing the PERSON object, the PERSONUID attribute is our Unique ID. To query for a specific Person record, include the PERSONUID in the URL:
http://maximo_host/maxrest/rest/os/mxperson/88?_format=json&_compact=1
Querying Maximo Data with LDAP Authentication
If your Maximo instance is configured to use LDAP Authentication, you must use a slightly different HTTP Header to supply the appropriate Maximo credentials. The other information, such as the URL and HTTP Method, remain the same.
In place of MAXAUTH, Authorization is used as the property in the HTTP Header. The same Base64 encoded username:password combination created earlier is also used for the value, however, this time it is preceded with the word Basic and a space character.
It comes together like this using the JSON API:
GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%" Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=
In Postman:
Similarly, for the REST API:
GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR% Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=
Maintaining Your Session
Once you establish a successful connection to Maximo, you will receive a cookie back in the response with a JSESSIONID token.
It is recommended to use this token in subsequent requests back to the Maximo API. This will improve performance and limit the number of sessions that Maximo creates.
Please feel free to leave any comments or questions below. For visual instruction of the previous steps, check out our video tutorial.
16 comments
Long
Hi,
I am checking the Rest API to get the workflow task is assigned to some user, by query tis object structure “/maximo/oslc/os/MXAPIWFASSIGNMENT” and condition is “?oslc.select=*&oslc.where=ownertable=”SR” and processname=”MyCompanyWR”, I can get some workflow task, but my problem is that: when i input the user for Rest API authentication, the service always return the Workflow Task which assigned to this user only. My expectation is that: I used only single service user for Rest API authentication like “MAXADMIN”, and get the user’s assigned task by condition like add to the selection condition like “oslc.select=*&oslc.where=ownertable=”SR” and processname=”MyCompanyWR” and assigncode = “MyUserOnly”..
Thank you so much
Long.
Bob Richardson
Hi Long,
If I understand your question, you want to return records from the MXAPIWFASSIGNMENT object structure beyond those records that are assigned to the user being used for authentication. There is a data restriction, called ASSIGNFILTER, on the MXAPIWFASSIGNMENT object structure that is likely impacting your results. If you take a look at that restriction the expression is,
assigncode = :&PERSONID& and assignstatus in (select value from
synonymdomain where domainid = ‘WFASGNSTATUS’ and maxvalue = ‘ACTIVE’)
To return different results, you will likely want to duplicate this object structure and either remove or apply another expression that is more in inline with the record set you are wanting.
Ronak Agrawal
Hi Alex,
How maintain the session for a user when Maximo instance uses LDAP BASIC Auth. Maintaining session workflow:
1. Login (OSLC/login)
2. Subsequent API calls using the Cookies (Get Object values, update object values etc..)
3. Logout (OSLC/logout) (This is also one of the and last subsequent calls for that session).
I am struggling in defining the Header values for the subsequent calls.
If I put Header as :
i. Cookie:”LtpaToken2=; JSESSIONID=” (NOTE Values are taken from initial OSLC/login Method) – The server generates another session
ii. Two headers:
Cookie:”LtpaToken2=”
Cookie:”JSESSIONID=”
Server returns 401 response
iii. Use single Cookie for each call, with value of LtpaToken – Server generates new session
iv. Use single Cookie for each call, with value of JSESSIONID – Server returns 401 response.
NOTE: All the above calls are over HTTPS not HTTP.
Please suggest with any REST Call and response example, for Session management in LDAP BASIC Auth.
Session management for Native Auth works as you have mentioned in this post.
Thanks
Gene
How do I query the Maximo JSON API using python scripting alone? That is no PostMan?
I have Maximo 7.6.1 and I am using basic authentication.
I used Postman to make my Get Request, which was successful and return data, and then clicked on the “Code” button to the right to get the python script. When I use it in my IDE I get this error:
{“Error”:{“reasonCode”:null,”message”:”Lexical error at line 1, column 13. Encountered: \”%\” (37), after : \”\””,”statusCode”:”500″}}
Here is the python:
import requests
url = “http://myserver/maximo/oslc/os/mxwo”
querystring = {“lean”:”1″,”oslc.select”:”wonum,actstart,status,description,reportedby,agx,agy”,”oslc.where”:”problemcode=%22DR07%22″,”status”:”%22APPR%22″}
payload = “”
headers = {
‘maxauth’: “mypasswordhereinbase64”,
‘cache-control’: “no-cache”,
‘Postman-Token’: “3803cf2c-5aed-4739-aab0-f5c86692f7e0”
}
response = requests.request(“GET”, url, data=payload, headers=headers, params=querystring)
print(response.text)
Sreekala
Hi ,
For ADFS enabled maximo environment ,GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4= is not working.
Getting the below error:
function LoginErrors(){this.userNameFormatError = ‘Enter your user ID in the format \u0026quot;domain\\user\u0026quot; or \u0026quot;user@domain\u0026quot;.’; this.passwordEmpty = ‘Enter your password.’; this.passwordTooLong = ‘Password is too long (\u0026gt; 128 characters).’;}; var maxPasswordLength = 128;
//]]>
Any help would be appreciated
Mark Fresa
Does anyone know how to POST updates to Maximo using Postman in URL strings? Please contact me if possible. Thanks in advance.
Ed Matthews
If you have the other comment I just sent this below provides some more detail but not the answer.
In the ibm guide available here:
https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html#_querying_maximo_asset_management_by_using_the_rest_api
it says,
“Just getting the links to the member resources may not be very exciting or useful. Rather than traversing individual URIs for details, the oslc.select clause is used to get more details inlined in this JSON response.
GET /oslc/os/mxasset?oslc.pageSize=10&oslc.select=assetnum,location,description,status”
In the article example above, how would you / could you use the json api to get the same result as
http://maximo_host/maxrest/rest/os/mxperson/88?_format=json&_compact=1 ?
Trying to understand better the advantages and tradeoffs of using
maximo/oslc/os vs maxrest/rest/os
Thanks,
Ed
Alex Walter
Biggest advantages are: 1) the ability to dynamically pull data based on information that may not necessarily be listed in the Object Structure, 2) more fine-grained control of filtering and sorting, 3) the ability to support paging through sets of data, and 4) continuing feature enhancements and support from IBM. The REST API is static and will not continue to be developed, where the JSON API is being updated with each new release of Maximo.
Hope this helps,
Alex
Ed Matthews
Hi Bob,
I’ve heard it’s best to move to the json syntax for its power and flexibility, but the rest message format returned is preferable to the URIs for the case I’m solutioning.
Is there a way to use the json api syntax but to get an output like that of the rest api, that is, the data not the URIs?
It seems maybe possible using {*} for each object, I will work on that option, but that appears to make the query URLs more complex, given the integration object itself that I’m using contains the attribution an external system wants to use, so setting the query syntax to use {*} from the top object down following the whole object structure is redundant.
Wondering what I may be missing.
TANWEER
Hi Alex
i am using REST API in the LDAP enabled environment ,which needs Basic Authentication . i have written the below code but form data is not passing to maximo where as a blank service request record created.
where as if i pass data in url using &, it creates the record with data. but large data cannot be passed in this manner since there is limitation of url size. following is the code i have written to pass form data , can you suggest why form data is not passing.
body
{
direction:ltr;text-align:left;
}
.row
{
display:block; padding:10px;
}
function CallWebAPI() {
var formData = new FormData(document.forms.myForm);
var XHR = new XMLHttpRequest();
});
// Set up our request
XHR.open(“POST”, “http://controldesk.local/maxrest/rest/os/MYSR”);
XHR.setRequestHeader(‘Authorization’,’Basic cG14aW50OlBAc3N3MHJkMTA=’);
// The data sent is what the user provided in the form
XHR.send(formData);
}
// Access the form element…
Basic Authentication Using JavaScript
DESCRIPTION:
INTERNALPRIORITY:
civilid:
Thanks & Regards
Tanweer
Alex Walter
Make sure you don’t have a CORS issue going on with XHR requests.
https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
Nonitha
Is it possible to read the content of the JSON body from automation script?
request.getQueryParam() is to read query parameters and request.getHeaderParams() is to read header parameters.
Is there any method to read body content from the JSON API?
Because passing parameters in URL has many restrictions.
Thanks
Nonitha
Alex Walter
There is a request.readRequestBody() method that returns a byte array.
Hope that helps,
Alex
sun
Thanks for explaining how to encode the login & password. I’m going to try using CURL and see if I can login and retrieve results via a URL.
John Harper
any way to capture the jsession id and run a get oslc/logout for that session for high volume of call?
Alex Walter
The JSESSIONID can be captured via the Set-Cookie header in the response from the oslc/login call. When you are finished with the session call the oslc/logout with those credentials.