Integrating With Maximo - A ready course now live in Udemy

If you are interested to subscribe to my new course, please use the below URL link with my referral code.

Udemy Course with Referral Code

Maximo - Architecture, Infrastructure, Implementation - A ready course l...

When you decide to subscribe to my course in Udemy.com, please use the below referral link.

https://www.udemy.com/course/maximo-architecture-infrastructure-and-implementation/?referralCode=B59631BDEC0E478805B9

Maximo Configurations - Practical Guide - Ready Course Available in Udemy

My new published course on Udemy.com Maximo Configurations - Practical Guide

Working with Maximo Workflows - A ready course live in Udemy.Com

Automation Scripting in Maximo - A ready course in Udemy.Com

Exploring MBR Language scripting and REST APIs using JSON Format with examples

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

References

Downloadable MBR Scripting Rules PDF

Maximo REST API examples

REST API Details

Integration for Maximo Public SaaS

Record creation and status change example

Maximo Asset Configuration Manager - Management of Inventory, Purchasing and Receiving of Assets

Since last six or seven months I have been working in a project where we are supporting a client who are using Maximo Asset Configuration Manager. While trying to understand the functionalities and the applications around this Industry Solution add-on to standard Maximo Asset Management, I have gone through many PDFs and browsed through IBM websites.  The references are cited at the end of this blog. I had been struggling to find the materials in one place to try for a hands-on. I have discussed with some of the folks who have been supporting this project from a long time. A few of them could explain the How’s, then failed to answer my Whys. Through this blog, I am trying to collectively put the topics in one place about what is ACM and how to manage the configuration-managed items in inventory and procure the assets. Please feel free to leave your comments, would love to hear your thoughts.

Introduction

Maximo Asset Configuration Manager is used to manage complex and regulated assets, like air crafts, rail vehicles, engines, etc. This follows a rules-based configuration management system. This industry solution add-on has introduced 10+ new applications in Maximo, a few CM versions of existing applications and added 50 new ‘PLUSA’ tables to Maximo database. Let’s not think about those as of now.

Let us first understand what this Configuration Management Process is. This is the specification of allowable as-designed asset assemblies ("models") and/or as-maintained physical builds. This is also referred to as the process of ensuring that actual physical build of an asset meets the requirements of an allowable configuration. There are three main phases in Asset Life Cycle, ‘As Designed’, ‘As Built’ and ‘As Maintained’.  Maximo ACM is used in ‘As Maintained’ phase. Maximo ACM uses information and data from the ‘as designed’ and ‘as built’ phases to compare assets in service against Design Standards.

Maximo Asset Configuration Manager (ACM) is designed specifically to address the needs of organizations managing complex assets within highly regulated, safety-critical and dynamic environments. It uses information and data from the ‘as designed’ and ‘as built’ phases as referenced data in Maximo to create and maintain the operational data. Maximo ACM separates the referenced data and operational data as shown in the image below. 

The build data interpreter(BDI) is a multi-threaded Java service which is independent from the main Maximo enterprise application and can be installed and configured on the same physical hardware as the Maximo application, the Maximo database server or on a separate dedicated server. BDI provides comprehensive status derivation for configuration-managed assets and reports the status of non-compliant assets. For example, it checks an actual aircraft, position by position, to ensure that its configuration rules comply with its nominated configuration.

Configuration Managed Assets and Items

Configuration Managed (CM) assets are different from other product assets as they can be composed of other assets or components defined within a hierarchy that have associated CM rules. Primary entity involved in CM is a Model. Models are primarily used as templates to maintain the ‘As Maintained’ information. Models define assembly rules and the hierarchical relationship of parts in an assembly but not the Spare parts.

The different components of a Model are as listed below:

1. CM Items are the Inventory Part Numbers available to use for a Build Item.
2. Build Items – Represent the building blocks to build a model and are a collection of CM items and labels with the same description that can be associated with the model's build position.
3. Build Positions - are used to create the model’s hierarchical relationship. Rules are applied to build positions, like allowable CM Items, Mandatory positions, etc.

Configuration Managed item is a part number that is under configuration management control, or in other words, a part number with catalog number which is associated with the model that is used to validate operational changes to an asset. Configuration-Managed Items are automatically created when models are created. CM items can also be created in CM Item Master application. CM Items can be managed in inventory and can be issued to work orders, locations or assets.

Maximo ACM maintains a cross-referenced catalog of item records for following purpose:

1. Creation and management of system-generated items that represent models and configuration of models.
2. Creation of such items that are produced locally on a temporary basis.
3. Changing the part number of an item or adding a local part to a catalog.

Now what is all this supposed to mean? Let me simplify this by using an example and let us consider an example to define a model of Car Chassis/body as in the image below. 

Creation of CM Items and Models

Before creating a model, CM item needs to be created. CM Item Master (CM) application can be used to create the CM Items. Models are created in the Models (CM) application. For creation of a model the first step is to create the build items for use in the model. The second step is to identify the CM items for each build item. Please see the below image for our example. 

Next step is to build the model hierarchy and the below image defines the model hierarchy for our example.

Once a model is created and you have defined the model hierarchy and you need to activate two important model components, its variation and revision.

Creation of Configuration Managed Assets

The configuration managed assets are created from the New Asset Assemblies (CM) application. 

Management of CM Items in Inventory and Purchase and receiving of CM Assets

How the inventory management of CM items is achieved in Maximo, is summarized in the image below. 

Points of consideration for procurement of CM Assets:

1. To create a purchase order for and receive configuration managed assets in Maximo, few things need to be configured first:
1. Create a CM Item and associate it with a standard rotating item in inventory.
2. A model should be created and associated with the above CM item and a label system. The variation status of the model configuration needs to be activated after clearing the abstract checkbox. Also, a revision of this model needs to be active.
2. Creation of PO
1. In the PO lines tab, after selecting the rotating item, the ‘CM Item?’ checkbox needs to be selected.
2. When the above checkbox is checked, in the CM Details section, the CM Item, Model and Variation fields become Mandatory. Label needs to be specified too.
3. Approval of PO
1. The user that is used to approve the PO record should have the PO Limits defined in its security group.
4. Receiving the Ordered Items
1. Receipt of the CM item is allowed if a holding location is available for the site in which PO is created
2. After receiving the ordered items and saving the record in Receiving (CM) application, one must go to New Asset Assemblies - Receiving (CM) application from the Assets module to create the configuration managed asset and complete the receipt.
3. In the New Asset Assemblies - Receiving (CM) application, asset can be created by adding the PO Number and the line number.

See the image below with an example to set up a CM item in Inventory and procure the asset associated with it.

References

• https://www.ibm.com/support/knowledgecenter/en/SSLKSJ_7.6.2/com.ibm.acm.doc/c_prod_overview.html
• https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20Maximo%20Asset%20Management/page/BDI%20Overview%20and%20Administration%20Guide
• https://www-01.ibm.com/support/docview.wss?mhq=Asset%20Configuration%20Manager&mhsrc=ibmsearch_a&uid=swg21967991
• https://www-01.ibm.com/support/docview.wss?mhq=Asset%20Configuration%20Manager&mhsrc=ibmsearch_a&uid=swg21968895
• https://www-01.ibm.com/support/docview.wss?mhq=Asset%20Configuration%20Manager&mhsrc=ibmsearch_a&uid=swg21965975
• https://www.ibm.com/support/knowledgecenter/en/SSLKSJ_7.6.6/com.ibm.acm.doc/plusacm/c_cm_items.html
• https://www-01.ibm.com/support/docview.wss?uid=swg21967694