April 4, 2017

Maximo REST APIs examples

This entry is part of the Maximo Integration Framework series.

In this tutorial I will show how easy it is to query and update data in Maximo using the Integration Framework (MIF) REST interface.

HTTP test client setup

To send REST calls you first need to setup an HTTP 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


Query

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:

http://[MXHOST]/maxrest/rest/os/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

8 comments:

  1. @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!

    ReplyDelete
    Replies
    1. 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

      Delete
  2. @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

    ReplyDelete
  3. 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 =)

    ReplyDelete
    Replies
    1. 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.

      Delete
  4. 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.

    ReplyDelete
  5. This comment has been removed by the author.

    ReplyDelete
  6. How to edit existing Task in Response plan and add a new Triggered Action business rule in ibm maximo TSRM. please help

    ReplyDelete