Maximo has an Email Listener and an Email Interaction application. I have seen the Email Listener being used quite effectively by some clients despite having some annoying bugs that require fixes using custom Java code. I haven’t seen the Email Interaction app used in a real production environment. Recently, I attempted to use the two applications without success. I ended up writing a simple email listener using Automation Script instead. This post outlines the detailed steps here in case someone will need it in the future.

Requirement: 

A major port uses workflow for their purchase requisition approval. The first-level approvers are first-line supervisors who often work in the field and do not have access to a computer most of the time. This causes some delays in the approval process. They asked if they could reply to an email from their mobile phones to approve the workflow assignment instead.

Analysis: 

To address this requirement, my first solution was to include two hyperlinks at the end of the workflow assignment emails. In the client’s current workflow, when a new PR is submitted to a supervisor, he already gets an email notification from Maximo. We can add at the end of this email an Approve and a Reject link which will trigger the respective action. However, this approach requires the user to enter a username and password to authenticate for Maximo to work. While we can hard-code the API key in the hyperlink, or remove the authentication requirement, it is unacceptable for security reasons.

My next solution was using the Email Interaction and Email Listener application. I followed this instruction provided by IBM. The article is quite detailed, however, it misses a few key pieces of information for which, I had to decompile the code to figure out. Despite that, after spending 8 hours, I couldn’t get it to work for this simple scenario. There were two issues:

• Email Interaction didn’t seem to populate the record ID correctly
• Email Listener cron gave me a NullPointerException error without any other intelligence to troubleshoot.

It looked like I needed to debug and write some Java custom code to address those issues and it will likely take another day at least. I decided to write a simple email listener instead. Below is the solution that I came up with.

Solution: 

Note: For this example, I used the standard Maximo Demo instance. It already has a simple approval workflow named “PRSTATUS”

First, I duplicated the standard WFASSIGN communication template to create a new template and named it PRAPPRASSIGN. I added the @@:OWNERID@@ placeholder to the email subject and added some additional instructions at the end of the email.

For the PRSTATUS workflow, I edited the SUP_APPR assignment node to enable sending emails when new assignments are created and set it to use the communication template created in the previous step.

As you can see, there is no crazy configuration here. The workflow will work exactly like before. The only change is the email sent out will also have a Record ID in the subject. When the user replies to the email, Maximo will use the ID to identify which PR record to approve.

The next step is to build a simple email listener. For testing, I created a new Gmail account and enabled App Password so it can be accessed from Maximo.

I created an Automation Script with the source code below and set up a cron task to execute it every 5 minutes. This simple script uses Java mail client library to access Gmail, and finds any unread emails that have an ID in the subject. If it can match the ID with a PR record that has an active WF assignment, it will approve or reject the request if the reply is 1 or 2 respectively. It also does a simple check to make sure the sender’s email matches the assignee’s email before routing the workflow.

Usage:

To test this, I set account Wilson to be Maxadmin’s supervisor and set Wilson’s email to be my own email. Then, with the Maxadmin account, I picked a PR in the WAPPR status and routed it through the workflow. The record was assigned to Wilson, and a notification was sent to my email inbox. To approve the assignment, I replied “1”. After a few minutes, Maximo Crontask will kick off the Automation Script which reads the reply and approves the workflow. As mentioned earlier, we can still use account Wilson to route and approve the workflow in Maximo. There is no change to the process.

For the HTTP End-point, we can set a fixed value in the request header. This doesn’t work for header values that must be generated on the fly like authorisation tokens. To override the headers of an end-point during runtime, the traditional approach is to write some custom Java code. This post explains how we can avoid Java by using an automation script end-point instead.

To illustrate the approach, I will use an example of an interface between Maximo and an application on Azure via the Azure Event Hubs. The API requires a SAS token to be provided in the request’s header.

First, we will create an automation script end-point by following this tutorial by Alex at A3J Group:

• Create an end-point:
  • Name: AZEVENTHUB
  • Handler: SCRIPT
  • Script: AZURE_EVENTHUB_ENDPOINT
  • Note: As explained by Alex, the SCRIPT handler is available OOTB from 7.6.1.1. From versions between 7.6.0.8 and 7.6.1.1, we’ll have to manually create a handler that utilises the java class: com.ibm.tivoli.maximo.script.ScriptRouterHandler

• Create an automation script:
  • Name: AZURE_EVENTHUB_ENDPOINT
  • Language: python
  • Source Code:

This is a bare minimum example. When the publish channel sends data to this end-point. It will call the automation script, which sets a Content-Type header and sends the payload (implicit variable requestData) by invoking an HTTP Handler.

In this case, we’ll use Webhook.site to test my request. To do it,  we’ll quickly set up a publish channel named AZWO from the standard MXWO object structure as follows:

Then we’ll set up an external system named AZEVENTHUB as follows:

To confirm the end-point is working, we update a work order. As a result, we should see a message posted to Webhook as follows:

Now to get this end-point to work with Azure Event Hub, we’ll have to populate a “ContentType” and an “Authorization” header for the request following the examples by Microsoft on how to generate SAS token. To avoid having to import third-party libraries to Maximo, when there is no suitable OOTB python library available, I’ll use Java code instead. Below is the source code for the end-point:

To test it, we’ll make another update to a work order. On webhook, we should see the result as follows:

Earlier I provided an example of how to extract and send data as CSV to a user via email. A friend asked me about a requirement he is dealing with. In this case, he has an escalation which sends an email when there is an error with integration. The problem with this approach is if there are many failed transactions, the administrator will receive a lot of emails.

The alternative approach is setting up a scheduled BIRT report which lists all errors in one file. However, this approach also has a problem. On the days when there are no failures, the admin would still receive an email and still have to open the file to see whether there is an error or not.

This is actually a common requirement. Below are some examples:

• Operation managers like to monitor a list of critical assets. Maximo should send out a maximum of one email per day with the list of active SR and WOs when the asset is down. Do not send emails if there are no issues.
• Operators like to receive a list of all high-priority work orders reported daily in one email, such as work orders that deal with water quality issues or sewer overflow.
• The system admin wants to get a list of suspicious login activities daily.
• System owners like to monitor data quality issues. Only send out a report if there are issues.

Below is an example of how we extract all P1 work orders in site BEDFORD, and save the data to an Excel file. I didn’t include the code to attach the file and send out an email as it has already been provided in my previous post

As usual, I test the script by calling it via API. Below is how the data looks when opened in Excel.

For data aggregation or when complex joins are required, we can also run an SQL query to retrieve data. Below is an example that provides a list of locations and the total number of work orders for each location.

Below is the data exported by the script

A client asked me to set up Maximo to automatically export work order data in CSV format and send it out via email. Initially, I suggested using the scheduled report function. We can build a simple BIRT report which has one data table. It can be scheduled to run automatically and send out an email with the data attached in Excel format. The user will simply have to open the file and save it in CSV format.

The solution was not accepted due to two reasons:

• It involves some manual intervention.
• BIRT Excel format has a limitation of 10,000 rows. If there are more rows, the data is split into multiple worksheets.

To address this requirement, I wrote an automation script that does two things:

• First, it fetches the MboSet and generates the CSV content using the csv library.
• Send an email with the CSV file attached.

Below is the simplified version as an example. It works with the OOTB Maximo demo instance. Notice that the csv python library I used was included in Maximo out-of-the-box but it is not available to autoscript by default. Thus, we have to append the Lib folder to the library path at line 7.

I created it as a script without a launch point:

To confirm that it works, I call the script by accessing this URL from the browser:

Once confirmed working, I created a cron task to run the script on a schedule. We can also modify this script to address some simple file-based integration requirements by changing the delivery method to SFTP or HTTP POST.

Update: We can also use Apache POI library (included in Maximo OOTB) to export data in Excel format and send as email attachments

Introduction

In an earlier post, I talked about how to use Automation Script to send an HTTP request by invoking a pre-configured End Point. That approach has some flexibility as we can override various properties during runtime like URL, Headers, or HTTP Method. Despite that, it is still quite limited and only suits simple scenarios.

In a recent task, I had to port an ArcGIS interface from Java to Autoscript. I improved the approach a little bit to address this real-world requirement. I document the simplified version here as it can be handy for me in the future. I hope that it is useful to some of you out there too.

Note: I use Webhook.site to test the code. It is free to use. If you like to test the code yourself, you will need to visit the site first to generate your own Webhook URL

Example 1: GET Request

I need to send a request to ArcGIS to get details of a Control Valve. It is a simple GET request with some parameters. Below is a basic example.

I created this as a script on the Asset Save launch point. It lets me to trigger the code easily by updating an asset record. When a request is sent to Webhook, it shows the request details including Parameters and Headers. Notice that in this case, it correctly decoded the basic authentication to a username/password pair for the MAXADMIN account.

Now, if I update the URL to point to a sample ArcGIS online server as in the code below, I can retrieve the details of an asset.

Below is what we see in Maximo.

Example 2: POST request with form data

In this example, I want to send a Service Request to ArcGIS. To add or update a feature, we need to send a POST request and the content should be in form-data format. Below is a basic example. It includes building a JSON object, converting it to string, and then sending it in form-data format.

I created it as a script on the “Save” event of the “SR” object. In this initial version, we send it to Webhook first to ensure the request is formatted correctly. As shown in the screenshot below, the form data is read correctly.

Now to make it real, I updated the code to send it to ArcGIS online server. In this case, I hardcoded the coordinate value to the Naperville  City Hall. Determining the X and Y coordinate of a Service Request based on Asset or Location is out-of-scope of this post.

To trigger the script, I update a random Service Request in Maximo. If a new feature is created successfully, we will get a message with an Object ID as follows.

We can open ArcGIS Online map, zoom into the area near Naperville City Hall and we should be able to see the new SR as a green point on the map