Creating an Automation Script End Point in IBM Maximo

The IBM Maximo Integration Framework offers a wide variety of capabilities for publishing or consuming information to or from external systems. Some of the available methods for communication are:

  • Flat File Exchange
  • XML File Exchange with XSLT Mapping
  • Database Table Exchange (both internal and external to Maximo)
  • HTTP or SOAP Service Consumption

However, there may be times when the available end point handlers do not fit exactly what you need. What options do you have to customize the way the data is exchanged (method, format, content, etc.)?

1. Java customizations: This is old and tired. However, it is possible to write your own Router Handler class to deliver an outbound message to its destination. It is also possible to deliver the message using one of the available handlers above, and then write a custom IBM Maximo cron task to move the message to its destination. For me, that is too many moving parts.

2. Third-party solutions: Implementing a third-party middleware solution, such as Node Red or MuleSoft, can be an option for removing specific system differences when exchanging information between two systems. This is especially useful in large enterprises where many systems are exchanging data. This can allow for a single source of business logic to exchange information across a wide range of systems. For smaller integrations however, this can just add another layer of management and skills necessary to support the organization.

3. Automation Scripts: This is an easy, simple way to build your own end point handler in IBM Maximo without introducing unnecessary Java customization. Luckily, IBM provides a hook that allows us to do just that.

To create an Automation Script End Point in IBM Maximo, you will first need to register the Script Router Handler class. Please note that this class was introduced in the IBM Maximo 7.6.0.8 release. In the 7.6.1.1 release, the SCRIPT handler was added by IBM, which means that these steps can be skipped if you are on 7.6.1.1 or later. If you are running a version between 7.6.0.8 and 7.6.1.1 you can follow these steps to create the Script Router Handler in IBM Maximo:

  1. Log into IBM Maximo as an administrator
  2. Navigate to the Integration > End Points application
  3. Under the More Actions menu, choose the Add/Modify Handlers option
  4. Click the New Row button
    a. Handler: SCRIPT
    b. Consumed by: INTEGRATION
    c. Handler Class Name: com.ibm.tivoli.maximo.script.ScriptRouterHandler
  5. Click the OK button

end point-autoscript-IBM Maximo-mif-automation scripting-integration-scripting-python-code-script-Maximo-customization

Once you have the SCRIPT handler, you can use it to register a new End Point in IBM Maximo:

  1. Log into IBM Maximo as an administrator
  2. Navigate to the Integration > End Points application
  3. Click the New End Point button
    a. End Point: TEST-SCRIPT
    b. Description: TEST SCRIPT HANDLER END POINT
    c. Handler: SCRIPT
  4. After populating the Handler with SCRIPT, a SCRIPT property will appear
    a. Value: <The name of your Automation Script>, e.g. TEST-SCRIPT
  5. Click Save

end point-autoscript-IBM Maximo-mif-automation scripting-integration-scripting-python-code-script-Maximo-customization

At this point, you have an End Point that calls an Automation Script that has not yet been created. The next step is to define that Automation Script and implement your own logic:

  1. Log into IBM Maximo as an administrator
  2. Navigate to the System Configuration > Platform Configuration > Automation Scripts Application
  3. From the More Actions menu, choose the Create > Script option
  4. In the ensuing dialog, enter the basic script information:
    a. Script: TEST-SCRIPT
    b. Description: TEST AUTOMATION SCRIPT FOR END POINT
    c. Language: python
  5. Enter the source code from below and press the Create button

end point-autoscript-IBM Maximo-mif-automation scripting-integration-scripting-python-code-script-Maximo-customization

Source Code:
# ------------------
# This script will write a message to the file system 
# and FTP the file to another server for processing.
# 
# Implicit Variables:
#   INTERFACE - the name of the triggered Publish Channel
#   requestData - the message payload
# 
# Alex Walter
# alex@a3jgroup.com
# 21 JAN 2021
# ------------------
from java.io import File
from java.io import FileWriter
from org.apache.commons.io import FileUtils
from org.apache.commons.net.ftp import FTPClient
from org.apache.commons.net.ftp import FTPReply
from psdi.util.logging import MXLoggerFactory

logger = MXLoggerFactory.getLogger('maximo.script.a3jtutorial')
if logger.isDebugEnabled():
    logger.debug('Starting TEST-SCRIPT script')
    logger.debug('INTERFACE: ' + str(INTERFACE))

# If the file exists, then delete it and create it new
ftpFileName = "C:\Temp\ftpfile.xml"
ftpFile = File(ftpFileName)
if ftpFile.exists():
	ftpFile.delete()
ftpFile.createNewFile()

# Write the file to disk
fileWriter = None
try:
	fileWriter = FileWriter(ftpFile)
	fileWriter.write(requestData)
finally:
	if fileWriter:
		fileWriter.close()

# Setup FTP variables - usually good idea to create System Properties
ftpHostName = "ftp.company.com"
ftpUserName = "username"
ftpPassword = "password"

ftpClient = None
fileInput = None
try:
	# Make an FTP connection
	ftpClient = FTPClient()
	ftpClient.connect(ftpHostName)
	reply = ftpClient.getReplyCode()
	if logger.isDebugEnabled():
		logger.debug('ftp reply: ' + str(reply))
	
	if not FTPReply.isPositiveCompletion(reply):
		if logger.isDebugEnabled():
			logger.debug('not a positive ftp reply')
		ftpClient.disconnect()
	else:
		if logger.isDebugEnabled():
			logger.debug('positive ftp reply!')
		# Log into the FTP server
		if ftpClient.login(ftpUserName, ftpPassword):
			if logger.isDebugEnabled():
				logger.debug('Logged into FTP site')
			# ftpClient.setFileType(2);
			fileInput = FileUtils.openInputStream(ftpFile)
			# Put the file in the default directory
			ftpClient.storeFile(ftpFileName, fileInput)
			if logger.isDebugEnabled():
				logger.debug('File sent to Server')
		# Log out
		ftpClient.logout()
		if logger.isDebugEnabled():
			logger.debug('Logged out of FTP site')
finally:
	if ftpClient:
		ftpClient.disconnect()
	if fileInput:
		fileInput.close()

 

NOTE: If you need help installing this automation script in your IBM Maximo, or have questions with other Maximo CMMS configurations don’t hesitate to reach out! Leave a comment below, or email info@a3jgroup.com

 

Run an Automation Script from a Cron Task in Maximo

Cron tasks are jobs that run automatically on a fixed schedule within Maximo. They include important jobs such as the PM Work Order Generation Cron Task, the Inventory Replenishment Cron Task, and others.

There may be times when you come across some requirements where creating your own Cron Task provides the best solution. In previous releases of Maximo, it was required to write a custom Java class to perform the action of the Cron Task when the schedule came due. Therefore, many times we turned to Escalations to provide solutions where scheduled tasks were required.

In Maximo 7.6, you can now run an Automation Script directly from a Cron Task. This article will walk through how to configure this.

Step 1: Create a new Automation Script

  1. Log into Maximo as an administrative user.
  2. Navigate to the System Configuration > Platform Configuration > Automation Scripts application.
  3. From the Select Action menu, choose the Create > Script option.
  4. Populate the appropriate fields on your new script:
    1. Script: CRONSCRIPT
    2. Description: Automation Script called from a Cron Task
    3. Script Language: python
    4. Log Level: ERROR
    5. Source: print ‘Automation Script called from a Cron Task’
    6. Click the Create button to create the new script
  5. Press the Close button on the ensuing dialog
  6. Locate the new CRONSCRIPT script in the list, and open the script
  7. Update the Script Source as follows, and press the Save button when finished:
#######################
# Script to generate an SR for a monthly equipment audit
#######################
from psdi.server import MXServer

# Get the variables from the cron task arguments
srDesc = 'Monthly Equipment Audit'
srOwner = 'WILSON'
if arg:
    srDesc,srOwner = arg.split(',')

# Create the SR
srSet = None
try:
    srSet = MXServer.getMXServer().getMboSet('SR', runAsUserInfo)
    srMbo = srSet.add()
    srMbo.setValue('DESCRIPTION', srDesc)
    srMbo.setValue('OWNER', srOwner)
    srSet.save()
finally:
    if srSet:
        srSet.close()

#######################
# End of Script
#######################

 

A few things to note with this source code:

  • This script will create a new Service Request and populate the Description and Owner fields
  • Notice that there are a few implicit variables that Maximo creates for use in the script:
    • arg: This is a delimited list of arguments that you wish to pass into the script. We will show below how to populate the arguments when we create our Cron Task.
    • runAsUserInfo: This variable gives the script access to the user profile that the cron task is running as. This will allow you to fetch Mbo Sets or perform other tasks with a set of credentials.
    • instanceName: While this variable is not utilized in the above script, it represents the Cron Task Instance Name that the script is being called from. This could be useful in the cases where you have multiple cron task instances and need to distinguish which one is actively running.
  • You can utilize the MXServer.getMXServer().getMboSet() method to fetch MBO sets of any record set that the runAsUserInfo profile has access to. Please note the strategy for closing MBO sets when you are finished with them. This alerts the JVM that the object is ready to be garbage collected. It’s important to follow this strategy, or a similar strategy, to avoid potential memory leaks with the JVM.

Now that we have a script, we can create a Cron Task to call it.

Step 2: Create a new Cron Task

  1. Log into Maximo as an administrative user.
  2. Navigate to the System Configuration > Platform Configuration > Cron Task Setup application.
  3. Click the New Cron Task Definition button on the toolbar or under the Common Actions menu.
    1. Cron Task: MYCRON (give your cron task an appropriate identifier)
    2. Description: My Cron Task (give your cron task an appropriate description)
    3. Class: com.ibm.tivoli.maximo.script.ScriptCrontask (this is the key to the setup, the value is case sensitive and must be exact)
    4. Click the Save button
  4. Click the New Row button under the Cron Task Instances table
    1. Cron Task Instance Name: MYCRON01 (give your cron task instance an appropriate identifier)
    2. Description: My Cron Task Instance 01 (give your cron task instance an appropriate description)
    3. Schedule: 1M,0,0,0,1,*,*,*,*,* (this will schedule the task to run on the first of every month; use the schedule builder to select the schedule that you want your cron task to run on)
    4. Run as User: MAXADMIN (select the user that you want the cron task to run as)
    5. Active: Yes
    6. Click the Save button
  5. There should be two new parameters in the Cron Task Parameters table at the bottom of the page.
    1. SCRIPTARG: This parameter is used to pass in variables to the script. You can separate variables by a comma or other delimiter in order to pass in more than one variable to the script.
    2. SCRIPTNAME: This parameter tells Maximo which Automation Script to trigger when the cron task runs.
    3. Fill out the above parameters and click the Save button. The SCRIPTNAME parameter is required, but the SCRIPTARG parameter is optional.

At this point, the Cron Task is configured and ready to go. When the cron task runs it will call the script with the arguments specified in the parameters table.

If you have any trouble, or have questions on how this works, please leave feedback in the comments below.