AmatuerMAX: April 2020

Maximo as a product is always emerging and evolving in the space of enterprise asset management and the recent versions of Maximo, like 7.6.1, is by far the most impressive version available in the market. It delivers and caters to client and industry driven needs. Availability of Maximo SaaS versions on cloud has exposed the developer community to a more demanding and fastest growing segment where in he/she is expected to explore out of his/her comfort zone of relying into Java Customization or Automation Scripting for that purpose. Because Maximo SaaS public/standard version is all changing the game plan for a developer. In this changing paradigm, a developer is supposed to understand that MBR is the only scripting language supported available in IBM Maximo EAM SaaS. Also, integration is supported mostly through REST APIs in the Maximo Public SaaS variant. Through this blog I want to throw some light on the same subjects with a few practical examples.

Maximo Business Rules Scripting Language

The latest versions of Maximo on cloud necessitate a Maximo developer to be familiar with MBR. This scripting language provides cloud-safe way to extend application business logic and is evolving gradually. The Maximo Business Rules scripts are text files that are made up of expressions. These expressions contain operators, functions and variables. Supported launch points that can be associated with MBR scripts are for Maximo business objects, attributes, conditions and actions. These MBR scripts cannot access Maximo framework’s Java classes directly. MBR scripts allow you to create functions pre-fixing the function name with a “:”. You can write library scripts for reusable code and these library scripts can be invoked by any other script. You can add comments by pre-fixing with a “#”. But there are certain rules around these. You cannot call a function or a library script recursively from your script. You cannot define more than one expression in the same line. No expression can span multiple lines. You cannot add inline comments. MBR Scripts restrict looping capability to delimited strings known as tokens and to MBOs that are related to the MBO that owns the current artifact. Keeping all these in mind you have to write a script using MBR language. And, you should also be aware that MBR scripting cannot be used to support Integration in Maximo SaaS variants, at least not yet.

There is a list of mathematical and Boolean operators, and the common mathematical, String manipulation, Aggregation, Date Manipulation functions are available in MBR language. Control flow functions like if(), break, continue, foreachmbo() are available for use. Date manipulation functions like now(), date(), duration(), datetime() are for your use. There are two very important functions to manipulate the variables in the scripts, as getVar(var_name) to retrieve the value of a variable, and setvar(var_name, expr) to set the value of a variable. There are a number of Maximo business specific functions as invokescript(), newmbo(), setValue(), error(), tobeadded(), tobeupdated(), scriptvar(), invokeworkflow(), setvarresult(), setrequired(), etc. are also available. There are dollar notations to access the MBO attributes in the MBR script. You can use a notation like Relation1$Relation2$Relation3$...$RelationN$attr to traverse several relationships to reach the MBO that contains the desired attribute value. A complete list for all of these can be referred to in the pdf file available from the below URL.

Let us jump into a few examples to understand how easily you can adapt to this new language. For the very first example, let us throw an error to the user when user selects the required date less than the current system date in Create Requisition application. We will create the error message in the Database Configurations application with message group as “ErrMsgGrp”, key as “ErrMsgKey”, display method as MSGBOX and the value of the error message as say, “Please select a date greater than the current date.” So far so good. Next, we proceed to create an automation script with Attribute launch point on object MR and attribute REQUIREDDATE with event as Validate. We are still in our familiar conform zone. We select the script language as MBR and the desired log level. Then we write the source code, and you will be very happy to write a single line that will suffice our requirement. Refer the image below for the source code.

You can see for yourself, it is such a simple If statement; i.e., If(<condition expression>, <expression if true>, <expression if false>). Now() is a date function that returns the current system date and time.

For our next example, let us explore how to make use of use variables and how to access a MBO attribute value from a related object from the current MBO record. In Purchase Orders application, on adding a line record, if the user selects an item number and the selected item is of type KIT, a field, say ‘X’, need to become read only else, another field, ‘Y’, needs to become required. For this requirement, we will create an automation script with attribute launch point on object POLINE and attribute ITEMNUM. Please refer the image below for its source code.

You can see the dollar notation used here to fetch the value of ISKIT attribute from ITEM object using the relationship name “ITEM” which exists between parent object POLINE to child object ITEM. We are setting this value to a new variable “var_kititem” created for this script. You can see the If statement. If this variable “var_kititem” is true, attribute X is set as read only else attribute Y is made required. You can add the comment line starting with hash.

Let us also explore how to loop through a MBO set in MBR scripts. Let’s assume we have to update the actual cost of all issue transactions of active inventory records of all capitalized items that have happened between last Monday and Friday. Any issue of an inventory record in Maximo is written into MATUSETRANS object. Let us consider that we create a relationship from MATUSETRANS object to INVENTORY object with the name as “CAPITEMISSUES” and where clause as “siteid=:siteid and location=:storeloc and itemnum=:itemnum and itemsetid=:itemsetid and issuetype='ISSUE' and exists(select 1 from ITEM where itemnum=:itemnum and itemsetid=:itemsetid and CAPITALIZED) and (transdate betweek trunc(sysdate)-5and trunc(sysdate)-1)”. Then we proceed to create an automation script “CALCULATECOST” with Action launch point in Object MATUSETRANS. We will then create an escalation on MATUSETRANS object to call this action “CALCULATECOST” every Saturday. The source code that is written using MBR language is as shown in the image below.

We have used foreachmbo() control function here and we are calling a function “capitemcost” for each record fetched from the relationship name “CAPITEMISSUES”. The function starts with its definition with the “:” and it finds the LASTCOST attribute value from the related INVCOST MBO record. This is fetched using the dollar notation for related MBO sets, CAPITEMISSUES being the relationship from MATUSETRANS to INVENTORY object and INVCOST being the relationship from INVENTORY to INVCOST. The LASTCOST attribute’s value we are setting in a variable “v_costvalue”. You can see that with the setvar function we have used a Boolean value TRUE. This is to make this variable global so that this can be used by outside the function “capitemcost”. ACTUALCOST attribute of the MATUSETRANS record by multiplying Quantity value to the value of the variable “v_costvalue”.

Maximo REST APIs using JSON format

The multi-tenant or public variant of Maximo SaaS, IBM Maximo EAM SaaS, provides integration support mostly through REST APIs. It allows inbound integrations, outbound events and data export by enabling a secure sharing of data between Maximo and external applications. In this variant of Maximo SaaS, you are not allowed to create or modify any Object Structure. You do not have support for integration scripting. There is no support for XML messages and web services. Only JSON and CSV formats are supported.

All these necessitate a developer to understand how to use REST APIs with JSON formats. The REST (Representational State Transfer) application programming interface (API) provides a way of querying and updating the Maximo application data by external applications. The REST API is part of the Maximo Integration Framework and can be used for CRUD (Create, Read, Update, Delete) functions on the data using either XML or JSON (JavaScript Object Notation) representation formats. In Maximo SaaS Public, however, JSON is only supported with REST API. REST is based on the concept of resources and hence, Maximo REST API exposes two types of resources, Maximo Business Objects (mbo) and Integration Object Structures (os). You can see two system properties for JSON format in Maximo which shows that Maximo REST API uses serializer classes, “mxe.rest.serializer.mbo.json” and “mxe.rest.serializer.os.json”.

Using REST API is actually very simple. First of all, you should know what is the URL of Maximo REST services. It is usually http://[HOSTNAME:PORT]/maxrest/rest. Say, we want to retrieve the list of all person records whose last name starts with “LAN”, using the integration object structure MXPERSON. We will simply use the URL as below.

http://[HOSTNAME:PORT]/maxrest/rest/os/mxperson/?LASTNAME=LAN%.

And, Maximo will perform a wildcard search so all person records that starts with the string LAN in the last name field will be returned. When you are using a REST API call with HTTP GET request like above, you may get an authentication error as “User name and password combination are not valid.” In such a case, the REST API call is expecting userid and password arguments with the HTTP GET request. So, we may use the below URL if we are using native authentication.

http://[HOSTNAME:PORT]/maxrest/rest/os/mxperson/?_lid=wilson&_lpwd=wilson&LASTNAME=LAN%.

Let us take another example to retrieve all the PO records sorted in descending order of total cost value. You will use the below URL to do so.

http://[HOSTNAME:PORT]/maxrest/rest/mbo/po/?_lid=wilson&_lpwd=wilson&siteid=BEDFORD&_orderbydesc=totalcost

Moving on from READ to CREATE or UPDATE functionality of CRUD, let us make some REST API calls with the HTTP POST request. Say, I want to change the description of an asset 1001 of BEDFORD site to New asset description. Here we are using an argument _action to specify a Change and ‘%20’ is used to encode spaces.

http://[HOSTNAME:PORT]/maxrest/rest/os/mxasset/?_lid=wilson&_lpwd=wilson&assetnum=1001&siteid=BEDFORD&_action=Change&description=New%20asset%20description

Next I want to change the status of all internal PO records of BEDFORD. Here the parameters with tilde prefix, status and memo, specify that these parameters belong to a web method.

http://[HOSTNAME:PORT]/maxrest/rest/mbo/po/?_lid=wilson&_lpwd=wilson&siteid=BEDFORD&internal=1&~status=APPR&~memo=Status%20change%20from%20REST%API

Let us create a new location ‘XYZ’ in BEDFORD site of storeroom type in OPERATING status. Note the use of argument _action with AddChange.
http://[HOSTNAME:PORT]/maxrest/rest/mbo/location/?_lid=wilson&_lpwd=wilson&_action=AddChange& location=XYZ&siteid=BEDFORD&type=STOREROOM&status=OPERATING&description=My%20location%20description