June 13, 2017

MxLoader now supports attachments

I have just implemented the capability to upload attachments straight from MxLoader. This is in response to some requests on my blog and MxLoader support forum.

Starting from Maximo 7.1.1.6 it is possible to import attachments to an object through MIF using Base64 encoding.
MxLoader has the capability to read files from the filesystem, encode them in Base64 and upload them on Maximo. This can be done on any Maximo object that supports attachments but the integration object structure has to be modified to include the DOCLINK object.

In this example the MYASSET object structure has been created with the DOCLINKS child object.



To specify a file to be uploaded you have to prefix the full path of the file with the ‘file:///’ string. Look at the screenshot below for an example of how to add two attachments to an asset.




June 2, 2017

Is your Maximo database in good health?

We all know Maximo is a complex product. It has plenty of features and is very flexible but sometimes complex to manage especially when system performances are poor.
A lot of things may affect the perceived performances of Maximo and it may be hard to have an overview of the entire system configuration.

What are the largest tables in the database that may need archiving?
Are database statistics updated to optimize database queries?
How much data is stored for each site?
Has the workload of system increased over the last years?
What are the most heavy reports users execute?
What are the most resources-consuming crontasks and escalations?
How is the reports/crontasks/escalations workload spread across the day?

These and many other questions have an answer in the Maximo Health Check report.
Maximo Health Check report is a utility for IBM Maximo and IBM Control Desk that can help identify and analyze issues, errors, or incorrect configurations that can lead to unsatisfying system performances.

Adding more JVMs to your application server cluster seldom solves Maximo performance issues. In our experience, the most effective performance improvement techniques are on the database side.
For large Maximo systems data archiving may be needed. This is because, after several years of usage, large volume of data accumulated into some tables slowing down database inserts and updates. Moving unnecessary data out of those  tables can greatly improve overall system performances.
When specific application queries, reports or escalations have unsatisfying execution times database indexes optimization could be the answer. Adding the right indexes and removing the wrong ones is a complex activity that requires deep skills but can produce outstanding results in many cases.
Sometimes index optimization is not enough to fix a badly written SQL query. In this case SQL queries optimization is the right technique. SQL queries are everywhere in Maximo: start center portlets, application queries, escalations and reports. By simply refactoring those SQL statements I have obtained impressive results in many cases.
Database tuning is the last chance. Assuming IBM suggested settings have been applied, this is 'brute force' approach can bring some incremental improvement to overall performances.


Download and run the Maximo Health Check report and you may find interesting information about your Maximo system.


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

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.



References

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