If you are interested to subscribe to my new course, please use the below URL link with my referral code.
Friday 17 June 2022
Friday 13 August 2021
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.
Friday 24 July 2020
Thursday 16 April 2020
Monday 6 April 2020
Friday 3 April 2020
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.
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.
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.
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%APILet 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
Monday 1 July 2019
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:
- CM Items are the Inventory
Part Numbers available to use for a Build Item.
- 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.
- 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:
- Creation and management of system-generated items
that represent models and configuration of models.
- Creation of such items that are produced locally on a
temporary basis.
- 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:
- To
create a purchase order for and receive configuration managed assets in
Maximo, few things need to be configured first:
- Create
a CM Item and associate it with a standard rotating item in inventory.
- 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.
- Creation
of PO
- In
the PO lines tab, after selecting the rotating item, the ‘CM Item?’
checkbox needs to be selected.
- 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.
- Approval
of PO
- The
user that is used to approve the PO record should have the PO Limits
defined in its security group.
- Receiving
the Ordered Items
- Receipt
of the CM item is allowed if a holding location is available for the site
in which PO is created
- 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.
- 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
Subscribe to:
Posts (Atom)