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:


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:


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:


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:



To retrieve the REVIS person record use the following REST call:


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:


To search with an exact match use the ~eq~ token as demonstrated in this examples:


Results can be sorted using the _orderby, _orderbyasc or _orderbydesc argument. Multiple attributes can be passed separated by a comma character.


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.


To update the same record we can use the PERSONUID returned from the create. In my example it's 161.


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.


Take note of your ASSETUID and query the new record with a GET request.


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:


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:


If you want to set a new classification here's an example:


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


IBM Documentation
Maximo REST APIs reference material

March 16, 2017

Load failure codes in Maximo with MxLoader

Creating and maintaining the hierarchy of failure codes in Maximo can be quite long and boring task using the standard Failure Codes application. The easiest and fastest way of importing Failure codes and the corresponding hierarchy is using MxLoader.

The example described in this post is available in this tailored in this sample MxLoader file. Please download it before proceeding.

Since there is no out-of-the-box object structure in Maximo to import failure codes, you first have to create the MxLoader custom object structures. This can be easily accomplished by clicking on the Create Custom Object Structures in the MxLoader ribbon in Excel.

The second step is to load the failure codes IDs and descriptions.
The FailureCodes worksheet on the example will load one failure class, two problems, two causes and three remedies.

Note that in the last column we have the language code. This is helpful if you want to transalate the failure codes in multiple languages.

We have just loaded a flat list of failure codes so now we need to create the hierarchical structure. The Failure Hierarchy template allows you to load failure class hierarchy using the custom MXL_FAILURELIST Object Structure. The example in the FailureHierarchy worksheet loads a small hierarchy using the failure codes defined previously.

Note how the failure hierarchy is specified in a flat table.
The object IDs in the square brackets will be generated dynamically by MxLoader during the import process. Do not enter those IDs manually.

This is how this failure tree will look in Maximo.

Note that the Failure Hierarchy template does not allow querying existing failure hierarchy. This can be a limitation if you want to copy a failure class hierarchy from one organization to another or from one server to another.
To extract an existing failure hierarchy you have use an SQL query like this.

SELECT f.orgid, f.failurelist classid, f.failurecode class,
  p.failurelist problemid, p.failurecode problem,
  c.failurelist causeid, c.failurecode cause,
  r.failurelist remedyid, r.failurecode remedy
FROM failurelist f
LEFT OUTER JOIN failurelist p ON p.parent=f.failurelist AND p.type='PROBLEM'
LEFT OUTER JOIN failurelist c ON c.parent=p.failurelist AND c.type='CAUSE'
LEFT OUTER JOIN failurelist r ON r.parent=c.failurelist AND r.type='REMEDY'
WHERE f.parent IS NULL
ORDER BY f.failurecode, p.failurecode, c.failurecode, r.failurecode;

MxLoader is also able to upload custom levels of failure codes in the hierarchy. For example, if you have a custom level called SYSTEM, you can simply add it to the columns and MxLoader will handle it.


Failure Codes in IBM Maximo Asset Management (SlideShare)
Failure codes (TechMCQ)
How to load failure code hierarchy using MIF

February 6, 2017

Maximo keyboard shortcuts

You know IBM Maximo has a lot of fields and sometimes can be boring entering data. Here are some keyboard shortcuts that can ease the pain. I have highlighted in bold the most common and useful ones.

  • Tab > The most important keyboard shortcut is the TAB key. It allows you to move across fields without using the mouse and also performs data validation and auto-completion.
  • Space > Select or clear a check box.
  • Alt + F1 > Display field help for field in focus.

There are few other useful shortcuts to move across applications.

  • Alt + C > Go to the Start Center.
  • Alt + G > Open the Go To menu. Use the arrow keys to choose the desired app.
  • Alt + B > Bulletins
  • Alt + R > Reports
  • Alt + P > Profile
  • Alt + S > Sign Out
  • Alt + H > Help
  • Alt + R > Return
  • Alt + W > Return with Value

Last but not least you can quickly create and save records with these Toolbar Buttons shortcuts.

  • Ctrl + Alt + I > Insert New Record
  • Ctrl + Alt + S > Save Record
  • Ctrl + Alt + A > Change Status
  • Ctrl + Alt + C > Clear changes
  • Ctrl + Alt + P > Previous Record
  • Ctrl + Alt + N > Next Record

This is a simplified list of the available keyboard shortcuts. For more information refer to the official documentation.

January 29, 2017

Maximo search operators

Maximo search features are quite advanced but often neglected. By using the advanced search techniques described in this post it is possible to find relevant records easier and faster.


The equal '=' operator can be used to find only records that match that a word or number exactly. In other words '=' means "exact match".
Example: Enter =123 to find any records with the exact characters 123 in the field. (Search results would not include numbers such as 0123 or 1234AB. If you enter just 123, without the =, search results would include 0123 and 1234AB.)

Not Equal

To search for all values that are not equal to a specific value enter '!='.
For example, typing !=WAPPR in the status field will retrieve all records that are not in WAPPR status.


The '<' and '>' characters can also be used to search for records that are bigger or smaller than a specific value.
  • Greater than '>': searches for any date after or number/word greater than the specified value.
    Example: Enter >1172 finds records of occurrences that have work order number greater than 1172.
  • Less than '<': searches for any date before or number/word smaller than the specified value.
    Example: Enter <1172 finds records of occurrences that have work order number smaller than 1172.

List of values

You can use comma ',' operator to list the records that match with either of the values specified. It basically acts as the OR operator.
For example, typing WAPPR,COMP in the status field will retrieve all records that are in WAPPR or COMP status .


You can use a "wildcard" characters with letters or numbers to indicate you want to find records that begin with, end with, or contain those letters/numbers.
There are four characters you can use as a wildcard:
  • Asterisk '*' or percent sign '%': stand for any number of characters (zero, one, or multiple) in the specified position.
    Example: Enter 123* to find records that start with 123, such as 123, 12345, 123ABC.
    Example: Enter *123 to find records that end in 123, such as 123, 5123, PUMP123.
    Example: Enter *123* to find records that contain 123, such as 123, 1234, PUMP123xy.
  • Underscore '_' or question mark '?': stand for a single character in the specified position.
    Example: Enter 123_ to find any four‐character records that start with 123, such as 1234, 1230, 123g.
    Example: Enter or _18 to find any three‐character records that end with 18, such as 418, J18.

NULL Values

You can search for null and not null values by entering the following values into a search field on the Find tab:
  • To search for a null value enter: ~null~
  • To search for not null values enter: != ~null~

If your keyboard does not have the tilde '~' character you may type enter this character by typing 126 on your numeric keypad while pressing the 'Alt' key.


A small additional tip for searching dates in the current month.
If you want to search for WO's with scheduled start date less than today, you don't need to type or select the whole date into the search field because Maximo automatically appends the current month and year in the where clause.
For example, if you search with <15, system will return all WO's where scheduled start date before the 15th of the current month.


Understanding Search Methodologies
To Search For Records in a Maximo Database
Search for NULL values in Maximo applications