This entry is part of the Maximo Integration Framework series.
Update April 2021 – This post describes the old REST APIs. A tutorial on the new APIs can be found here.
In this tutorial I will show how easy it is to query and update data in Maximo using the Integration Framework (MIF) REST interface.
To send REST calls you first need to setup an HTTP/REST client. In this tutorial I will use a Google Chrome add-on called Advanced REST Client.
Retrieve a record
In this first example I will show you to retrieve a PERSON record from Maximo using a REST call with an HTTP GET request:
http://[MXHOST]/maxrest/rest/mbo/person/1
Probably you will get an authentication error like this:
Error 401: BMXAA0021E - User name and password combination are not valid. Try again.
This means that you have to pass the authentication credentials to your request. If you are using native authentication you can pass the _lid and _lpwd arguments as described in this example:
http://[MXHOST]/maxrest/rest/mbo/person/1?_lid=wilson&_lpwd=wilson
Now you should see the PERSON record identified by the PERSONUID=1.
NOTE: For all the examples below I will exclude the authentication arguments for simplicity.
MBO and OS resources
The REST API provides access to business objects and integration object structures.
The two calls below will provide access to the same resource:
http://[MXHOST]/maxrest/rest/mbo/person/1
http://[MXHOST]/maxrest/rest/os/mxperson/1
The first call access data straight from the PERSON object through MBO persistence layer.
The second call access data from the MXPERSON integration object structure through the MIF.
You will notice that results are slightly different.
Data format (XML or JSON)
By default Maximo retrieves data in XML format. JSON could be used instead passing the _format argument:
http://[MXHOST]/maxrest/rest/mbo/person/?_format=json
Select records
To retrieve the REVIS person record use the following REST call:
http://[MXHOST]/maxrest/rest/mbo/person/?personid=revis
Note that Maximo will perform a wildcard search by default so if you type ‘re’ instead of ‘revis’ you will get a list of records that contains ‘re’ in the PERSONID field:
http://[MXHOST]/maxrest/rest/mbo/person/?personid=re
To search with an exact match use the ~eq~ token as demonstrated in this examples:
http://[MXHOST]/maxrest/rest/mbo/person/?personid=~eq~revis
http://[MXHOST]/maxrest/rest/mbo/person/?personid=~eq~re
Results can be sorted using the _orderby, _orderbyasc or _orderbydesc argument. Multiple attributes can be passed separated by a comma character.
http://[MXHOST]/maxrest/rest/mbo/person/?personid=re&_orderby=statusdate
http://[MXHOST]/maxrest/rest/mbo/person/?personid=re&_orderby=status,statusdate
Create or Update a record (AddChange)
To create an existing record the AddChange action can be used. The following example will create a new person named RESTINT. Note that in this case a POST request must be used instead of a GET.
http://[MXHOST]/maxrest/rest/mbo/person/?_action=addchange&personid=restint&firstname=Rest&lastname=Int
To update the same record we can use the PERSONUID returned from the create. In my example it’s 161.
http://[MXHOST]/maxrest/rest/mbo/person/161?_action=addchange&personid=restint&firstname=RestNew&lastname=IntNew
Updating child objects
Lets now pretend we need to update an asset specification and one of its attributes. You will see things are now a little more complex.
First of all we can create a new asset with a POST request.
http://[MXHOST]/maxrest/rest/mbo/ASSET/?assetnum=myasset01&siteid=BEDFORD&description=TestTest
Take note of your ASSETUID and query the new record with a GET request.
http://[MXHOST]/maxrest/rest/mbo/ASSET/2585
Now login to Maximo, classify the MYASSET01 as a BEARING, add an ALN attribute and save it.
If you query the asset using the GET request above you will notice that you just have a CLASSSTRUCTUREID attribute with a number in it specifying the classification. This is not usable in our scenario and will not allow to update attribute.
The right approach is to switch to the object service structure. Try to query the new record with a GET request like this:
http://[MXHOST]/maxrest/rest/os/MXASSET/2585
You will see that the HIERARCHYPATH field is now available and a subelement ASSETSPEC returns the attribute.
If we now want to update the value of the ALN attribute we can use a POST with a dotted notation like this:
…/MXASSET/2585?ASSETSPEC.1.ASSETATTRID=BEARTYPE&ASSETSPEC.1.ALNVALUE=ABC&ASSETSPEC.1.LINEARASSETSPECID=0
If you want to set a new classification here’s an example:
http://[MXHOST]/maxrest/rest/os/MXASSET/2585?hierarchypath=BEARING%20\%20ROLLER
Note how the spaces have been encoded in the URL with the ‘%20’ string. Hope this can help all of us dealing with integration scenarios using REST calls…
References
IBM Documentation
Maximo REST APIs reference material
@Bruno great posting – as usual!
I do have one question though – did you ever get REST MBO query to work with _rcol.alias request parameter in order to retrieve related MBO attributes without a need to use REST OS?
I tried it many times but failed unfortunately.
If you succeeded then maybe you can share working example like: retrieve ASSET.ASSETNUM,ASSET.DESCRIPTION,ASSET.LOCATION,ASSET.LOCATION.DESCRIPTION values using http://[MXHOST]/maxrest/rest/mbo/asset?
Thank you in advance!
@Bruno, thank you for wonderful blog!
Please, say have you got any example how can I make rest request of external system from MAXIMO ? I found many examples with file import, but no rest calls with MAXIMO
Hello friends.
Can anyone help. We can't find some information for load JSON object INTO Maximo to MBO.
We have:
IBM WebSphere Application Server 8.5.5.10
Tivoli's process automation engine 7.6.0.3 Build 20160114-1313 DB Build V7603-151
IBM TPAE Integration Framework 7.6.0.3 Build 20160108-1912 DB Build V7603-21
IBM Maximo Asset Management 7.6.0.3 Build 20160113-2204 DB Build V7603-01
Linux 2.6.32-642.el6.x86_64
Our project uses a PI Web API (external system) server that provides a set of REST services (JSON objects). We need the integration of IBM Maximo with the PI Web API:
1. Is it possible to integrate this using Maximo Integration Framework (without creating custom Java classes)?
2. The exchange process is as follows:
on the MAXIMO side must generate dynamic HTTPS request, the PI Web API returns a JSON response. We need to store this JSON object to our MBO. We created the end point, tested it. Make sure that the data exchange occurs. How can we make invoke to extrenal system?
What do you need to do next? What objects do we need to create and how to link them together, so that we can process the resulting value in MAXIMO? How to create a JSON object right? How we can get the value and show it in intreface control?
We would be helped very much by the example in the form of "quick start". Can you give us such an example?
Our task:
1. From Maximo make request to external system (REST, JSON)
2. Get a response from external system
3. Convert a respons to existing MBO (map JSON attributes to MBO attributes)
4. Save response from External System (JSON object) to MBO
Our steps:
1. Create a EndPoint with HTTPMETHOD and URL to External System
2. Test EndPoint (Success). External system return data for us
3. Create JSON resourse with test data from URL (JSON structure)
4. Create object structure with existing JSON object
5. Create Invoctional Chanel with end point and request and response object structure
6. Create Action to "Run" Invoctional Chanel.
7. Create Button
Help =)
Hi Kreng,
Any luck?
I was able to achieve steps 1 and 2
Hi, I suggest you to post this questions on developerWorks forum: https://www.ibm.com/developerworks/community/forums/html/forum?id=11111111-0000-0000-0000-000000001119
It's the most active Maximo forum around.
As I can see someone reported this problem at IBM and APAR IV97375 (REST API QUERY PARAMETER _RCOL IS NOT WORKING) has been authorized.
For more details see this page: https://www-304.ibm.com/support/entdocview.wss?uid=swg1IV97375&myns=swgtiv&mynp=OCSSLKT6&mync=R&cm_sp=swgtiv-_-OCSSLKT6-_-R
Hi Bruno,
I am trying to get Service request details(MXSR object structure) using rest service with TICKETID field for wild card search, Please find the following URL
http://[MXHOST]/maxrest/rest/os/MXSR/?ticketid=10048 It gives an error (BMXAA4183E – Constructor not found. Use database configuration to check the field class registered and ensure that it is valid and included in the deployment.) Whereas it works fine when I am giving exact TICKETID (1004840). Please help me out with this.
How to edit existing Task in Response plan and add a new Triggered Action business rule in ibm maximo TSRM. please help
How can I access to the REST API without authentication. I don't want to pass the username and password through the URL parameters, so I am using SSL mutual authemtcation, but still REST API asking for username and password.
Thank you for your post, especially the part about updating the values of the assetspec's. This was tremendously helpful. Is there also a good way to query on the assetspec via ReST API? Using your example, how would you then retrieve all assets where ASSETATTRID=BEARTYPE ASSETSPEC.1.ALNVALUE=ABC
Hi Bruno,
I would like to know if there is a way to customize the MBO deserialization using specific code.
Thank you
hi Bruno,
can you recommend api that we could use for CD(continuous deployment)?
Hi all, and as usual, Thanks Bruno, for your work on this site.
Is it possible in a GET to set the orderby of the rows from a related child object to a parent?
Say we have some custom integration object structure, customwo, with workorder and child woactivity.
WORKORDER, relationship to woactivity on siteid to siteid, wonum to parent, WOACTIVITY
Given a query for a wonum, we want to get the wonum attribution plus all of the child woactivity records and we want to set the orderby on the woactivity record set, ie not on the workorder.
We want not to use order by in the relationship, we want the query structure to output the workorder + woactivity with woactivity orderby changedate desc, for example.
So how to add &_orderbydesc=changedate for just the woactivity set to this:
http:///maxrest/rest/os/CUSTOMWO?_format=json&_compact=1&wonum=10831500
Hi,
I would like to save values in maximo custom table. its working fine on dev environment , on production we are using ssl its asking for credential again even i am passing credentials, any idea.
Regards
Haris
Hi,
I am trying to add an assignment to the work order using REST API, which is giving 500-Internal Server Error.
I am able to create the new work order using mbo fine, but not a new assignment to an existing work order.
Appreciate any help on this.
Are there anyone that has used the two query parameters of _qop and _rcol.alias of the maximo REST API? If there pls kindly give an example for usages of the tow parameters.I had tried to use them but didn’t the result expected.