The Maximo REST API is something really cool and really useful. I have spent a little time playing with it and it’s much easier to use than the MIF web services and SOAP. Although the integration framework is still useful in terms of importing data with interface tables, but the REST services are extremely useful for consuming data. In this tutorial, I will walk through some samples of how to query data using REST.

Let’s just get right to it. Here is a sample URL to query a specific work order record:

http://server/maxrest/rest/os/mxwo?_lid=maxadmin&_lpwd=maxadmin&wonum=1683

The resulting payload is this:

<?xml version="1.0" encoding="UTF-8" ?>
<QueryMXWOResponse xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDateTime="2011-11-02T22:33:34-04:00" transLanguage="EN" baseLanguage="EN" messageID="1320287614816469698" maximoVersion="7 5 20110413-2230 V7500-721" rsStart="0" rsTotal="1" rsCount="1">
<MXWOSet>
  <WORKORDER>
    <ACTFINISH>2001-04-15T19:01:12-04:00</ACTFINISH>
    <ACTINTLABCOST>180.0</ACTINTLABCOST>
    <ACTINTLABHRS>2.2</ACTINTLABHRS>
    <ACTLABCOST>180.0</ACTLABCOST>
     .
     .
     .
    <WONUM>1638</WONUM>
    <WOPRIORITY>2</WOPRIORITY>
    <WORKORDERID>1</WORKORDERID>
    <WORKTYPE>EM</WORKTYPE>
  </WORKORDER>
</MXWOSet>
</QueryMXWOResponse>

Let’s analyze this URL at bit. Here we are using ‘os’ which stands for Object Structure where you can build your own or use the existing ones in that module. This means we want to query data use the OS that has been defined. The ‘mxwo’ is a built in object structure used to define the WORKORDER object. If this OS had sub objects like workorder tasks, the resulting XML will show those as well. In our URL, we also passed in the login ID parameter (_lid) and the password (_lpwd). This is needed only in the first request to the server. These parameters can be removed in all of the following REST service requests as long as you don’t close your browser or your session hasn’t timed out. So the last parameter ‘wonum’ is the QBE or ‘query by example’ criteria that we want to use to search. The ‘wonum’ is obviously the Maximo field name you want to search by.

You can add as many parameters to the QBE as you want. So your URL could look something like this:

http://server/maxrest/rest/os/mxwo?wonum=1683&worktype=em&siteid=beford

Operators

You can add operators like ‘equal to’, ‘less than or equal to’ and more to these queries list so:

http://server/maxrest/rest/os/inventory?issueytd=~gt~1&orderqty=~gt~5

Here is the full list of operators:

• Equals : ~eq~
• Not Equals : ~neq~
• Greater Than : ~gt~
• Greater Than Equals : ~gteq~
• Less Than : ~lt~
• Less Than Equals : ~lteq~
• Ends With : ~ew~
• Starts With : ~sw~

So this URL will take all the field names and use an ‘AND’ operator between the fields, so it will find records that meet all of the criteria. To use an ‘OR’ you would add the ‘_opmodeor’ parameter:

http://server/maxrest/rest/os/inventory?issueytd=~gt~1&orderqty=~gt~5&_opmodeor=true

You can get the full list here.

Result set and maximum records

The more you play with this, the more data you probably want to query, so one rule of thumb is to always use these two parameters: ‘_rsstart’ and ‘_maxitems’ like so:

http://server/maxrest/rest/os/inventory?issueytd=~gt~1&orderqty=~gt~5&_rsStart=0&_maxItems=20

What this does is query the data, but only returns the number of records you specify in the ‘_maxitems’ parameter and the first item in the payload will start with the index you specify in the ‘_rsstart’ (stands for ‘result set start’) parameter. So this is saying that you want a maximum number of records returned is 20 and start at the 0 (zero) index. In the second line of the XML payload, you can find the _rsCount attribute. You can use this count in combination with _rsStart and _maxItems to page through the record list. Another rule of thumb is to not set the _maxItems paramter to anything higher than 200. Otherwise you will have performance issues. **Note: these two parameters ARE case-sensitive.

Other important parameters that you might be interested in are:

• _orderbydesc
• _orderbyasc
• _dropnulls

If you are familiar with XML, you need to be familiar with JSON. It’s basically another way of formatting data that can be consumed by the client. To change the payload from XML to JSON, simply add the ‘_format=json’ to your url. My recommendation is to also use the ‘_compact=1’ as well, which will compact the payload.

http://server/maxrest/rest/os/mxwo?wonum=1683&_format=json&_compact=1

The resulting payload will be this:

{ "QueryMXWOResponse" : { "MXWOSet" : { "WORKORDER" : [ { "ACTFINISH" : "2001-04-15T19:01:12-04:00",
                "ACTINTLABCOST" : 180.0,
                "ACTINTLABHRS" : 2.2000000000000002,
                "ACTLABCOST" : 180.0,
                "ACTLABHRS" : 2.2000000000000002,
                "ACTMATCOST" : 65.25,
                "ACTOUTLABCOST" : 0.0,
                "ACTOUTLABHRS" : 0.0,
                "ACTSERVCOST" : 0.0,
                "ACTSTART" : "2001-04-12T13:10:26-04:00",
                ...
                "WOGROUP" : "1638",
                "WOISSWAP" : false,
                "WONUM" : "1638",
                "WOPRIORITY" : 2,
                "WORKORDERID" : 1,
                "WORKTYPE" : "EM"
              } ] },
      "rsCount" : 1,
      "rsStart" : 0,
      "rsTotal" : 1
    } }

Query MBO’s instead of Object Structures

So this whole time we have been querying OS. This is great because you can create your own OS and you can structure it so that you can get work order records along with the labor hours and materials used when you query that workorder. But sometimes you may just want to query a single record and the OS doesn’t exist or you don’t want to create one. You can then use MBO’s to query instead. If you aren’t too familiar with MBO’s then this may not make too much sense to you. But here is what the URL looks like when you query an MBO set.

http://server/maxrest/rest/mbo/workorder?wonum=1683

As you can see, we replaced the ‘os’ in the URL with ‘mbo’ and the added the ‘workorder’ MBO value. This will query the work order MBO set and return the following payload:

<?xml version="1.0" encoding="UTF-8" ?>
<WORKORDERMboSet rsStart="0" rsTotal="1" rsCount="1" xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <WORKORDER xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <WONUM>1638</WONUM>
    <STATUS>CLOSE</STATUS>
    <STATUSDATE>2001-04-24T01:40:24-04:00</STATUSDATE>
    <WORKTYPE>EM</WORKTYPE>
    <DESCRIPTION>Check Leaking Condensate Return Pump</DESCRIPTION>
    <ASSETNUM>11430</ASSETNUM>
    <LOCATION>BR430</LOCATION>
    ...
    <PLUSCLOOP>0</PLUSCLOOP>
    <USEMBODATA>1</USEMBODATA>
    <INCTASKSINSCHED>1</INCTASKSINSCHED>
  </WORKORDER>
</WORKORDERMboSet>

As you can see, the XML is a bit different but still very useful.

So there you have it. Maximo REST API’s are great and very easy to use.