August 4, 2017

Security groups and application authorizations

We all know how flexible Security Groups are when dealing with user roles and granting application authorizations. However, flexibility often brings complexity.
You have carefully designed user's roles defining what applications and actions they are allowed to access in Maximo and implemented all using Security Groups application. The system goes live and after one or two years everything is messed up. Is too hard to check who has access to what and you no longer sure if the young electrician that was just hired 2 months ago has access to Database Configuration or Application Designer  :-)

Maximo has a built-in report called Security Group Access that can help but I hardly find it useful. In my opinion it is too detailed to get an overall idea of the security configuration. For example, I'm now working on a medium-sized Maximo solution with 20 security groups and around 250 users. Well... the 'Security Group Access' report is 89 pages long!


That was not going to work. I needed I better solution for my purpose so I decided to open my preferred SQL client and Eclipse BIRT Designer to have some fun. Results were pretty good so I have decided to share them with the Maximo community.

I came up with two custom reports that give me a quick grasp of the setup of user's authorizations. The first one is called Security Overview and simply lists all the Security Groups and Start Centers counting how many users are assigned to them.


The second report is called Application Security Overview. It tries to represent which security groups provide access to applications. It is not an easy task to represent so many information in a single report but I'm finally proud of the results so here is what I have achieved to get.


The report lists all the applications in the rows and the security groups in the columns. The cell is yellow if read access is granted, orange if write access is granted, the number is the count of sigoptions granted.
The report can easily get too big if more than 20 security groups are defined so I decided to accept a list of security groups as filter so I can analyze smaller sets of data separately.

Download and installation instruction is available here.

Any feedback is highly appreciated.

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