Introduction

Maximo domains provide an effective way to implement simple lookups for based either on a static list with ALN and Numeric domains or based on values from another table with the Table domain. Combined with conditional expressions, this covers almost all use cases. However, sometimes all the configurations can become very complicated and difficult to understand because of the number of layers and different components at play.

As an alternative to using the standard Maximo domains and conditional expressions, in this post we are going to review using an automation script with an Attribute Launch Point using the Retrieve list event to provide and filter look up value lists. For the most part, using an automation script in this manner does not provide a unique capability, but make clearly implementing complex logic easier.

Implicit Variables

The Retrieve list event provides the following implicit variables that are used for displaying the list, returning values and validating the values mapped. These implicit variables are output type variables, intended to be set within the script and then read by the Maximo framework to provide the list. The following table details the available variables.

NOTE: In developing the example for this post we discovered that the domainid implicit variable in the IBM documentation does not work as described. Setting the domainid implicit variable has no effect. Our testing was done with Maximo 7.6.1.2 and MAS Manage 8.6.

Related Table List Example

For our example we are going to add a list to the RISK attribute on the WORKORDER object and then add the look up to the Work Order Tracking application. We will be using an ALN domain for simplicity and ease of setting up the example. This same technique can be used in more complex cases with one or more Maximo objects or even using a custom non-persistent object to provide the list.

Configure Risk Domain

First we are going to create a new ALNDOMAIN value list. From the main navigation menu, select System Configuration, Platform Configuration and then the Domains application. From here click the Add New Domain button and then select Add New ALN Domain .

Next enter RISK for the Domain, ALN for the Data Type and 10 for the Length. Then enter the following values for domain values.

Here is what your domain entry should look like when complete.

Click the Save button to save the domain.

Add Lookup to Work Order Tracking

From the main navigation menu, select System Configuration, Platform Configuration and the Application Designer application. Search for the WOTRACK application and select the record, then select the Work Order tab and locate the Risk attribute under the Priority section. Select the attribute's properties and then enter VALUELIST for the Lookup property.

Click the Save button to save the application configuration.

Automation Script

From the main navigation menu, select System Configuration, Platform Configuration and the Automation Scripts application. From the More Actions menu select Script with Attribute Launch Point.

Create a new launch point with the name WORKORDER.RISK.LIST, a description of Work Order Risk Assessment List, then select the WORKORDER object and RISK attribute and finally, select the Retrieve list event then click Next.

For the script name and description use the WORKORDER.RISK.LIST and select Nashorn for the Script Language value then click Next. For the script enter the following script.

The scriptConfig variable is included in this example for those of you using our VS Code plugin: https://marketplace.visualstudio.com/items?itemName=sharptree.maximo-script-deploy

Copy
Arrays = Java.type("java.util.Arrays");

// Set the implicit variables to return the details of the list
// and to specify the values to be copied
relationObject = "ALNDOMAIN";
relationWhere = "domainid = 'RISK' and value =:risk";
listWhere = "domainid = 'RISK'";

// provide the source and target attributes
srcKeys = Arrays.asList(["VALUE"]);
targetKeys = Arrays.asList(["RISK"]);

// Script configuration for deployment
var scriptConfig = {
    "autoscript": "WORKORDER.RISK.LIST",
    "description": "Work Order List for Risk Assessment",
    "version": "1.0.0",
    "active": true,
    "logLevel": "ERROR",
    "scriptLaunchPoints": [
        {
            "launchPointName": "WORKORDER.RISK.LIST",
            "launchPointType": "ATTRIBUTE",
            "active": true,
            "description": "Work Order List for Risk Assessment",
            "objectName": "WORKORDER",
            "attributeName": "RISK",
            "retrieveList": true
        }
    ]
};

NOTE: The underlying com.ibm.tivoli.maximo.script.AttributeLaunchPoint class requires the srcKeys and targetKeys to either be an instance of the Java type List or a String array. For our example we are using the java.util.Arrays utility to ensure our values are a Java type List the JavaScript ["VALUE"] does not convert to a Java String array. In Jython / Python the ["VALUE"] notation is valid.

That is all that is required. The relationObject variable specifies the AlNDOMAIN table as the source object, the listWhere variable filters the list to only values where the domainid is RISK and the relationWhere includes the :risk attribute bind variable that will be used to validate the value entered.

Returning to the Work Order Tracking application, we can see that the Risk attribute now has a lookup icon and when we click the list is displayed.

If we enter an invalid value, such as badvalue an error message is displayed.

MboSet List Example

Instead of using a related MboSet we can directly specify the list MboSet using the listMboSet implicit variable.

The listMboSet implicit variable is not in the official IBM documentation, found here https://www.ibm.com/docs/en/control-desk/7.6.1.2?topic=scripts-implicit-variables, but we have verified it is in Maximo 7.6.0.9 and greater.

In the example below, we implement the same functionality as before, but this time provide the list MboSet directly. Note that we leave the relationWhere implicit variable set to provide validation and that we are using the psdi.mbo.SqlFormat class as described in our post here. We are also using the setOrderBy method to order by the value in descending order.

Copy
Arrays = Java.type("java.util.Arrays");
MXServer = Java.type("psdi.server.MXServer");
SqlFormat = Java.type("psdi.mbo.SqlFormat");

var sqlf = new SqlFormat("domainid = :1");
sqlf.setObject(1, "ALNDOMAIN", "DOMAINID", "RISK");

// set the list MboSet directly by getting the MboSet as a named related set with provided where clause.
listMboSet = mbo.getMboSet("$alndomain", "ALNDOMAIN", sqlf.format());

// order the list by value descending
listMboSet.setOrderBy("value desc");

// set the validation clause, where it will be validated based on relationWhere returning a value.
relationWhere = "domainid = 'RISK' and value =:risk";

// provide the source and target attributes
srcKeys = Arrays.asList(["VALUE"]);
targetKeys = Arrays.asList(["RISK"]);

// Script configuration for deployment
var scriptConfig = {
    "autoscript": "WORKORDER.RISK.LIST",
    "description": "Work Order List for Risk Assessment",
    "version": "1.0.0",
    "active": true,
    "logLevel": "ERROR",
    "scriptLaunchPoints": [
        {
            "launchPointName": "WORKORDER.RISK.LIST",
            "launchPointType": "ATTRIBUTE",
            "active": true,
            "description": "Work Order List for Risk Assessment",
            "objectName": "WORKORDER",
            "attributeName": "RISK",
            "retrieveList": true
        }
    ]
};

Non-Persistent MboSet List Example for Manual Ordering

Ordinarily the only option for ordering lists is by a value using ascending or descending order. In our example case this is High, Low, Medium or Medium, Low, High. But what if we want to order the list by Low, Medium, High instead?

I have seen many creative ways implementing custom ordering, such providing a prefix on the description to order by or even adding a custom attribute to set a numeric value to order by. Below we will create a non-persistent Maximo object and manually populate the values in the desired order.

Create Non-Persistent Object.

From the main navigation menu, select System Configuration, Platform Configuration and the Database Configuration application. Click the new record button and then enter a Object value of Risk, a Description of Risk Table and then uncheck the Persistent? checkbox or toggle button.

Then click the Attributes tab and add two attributes, Value and Description with a type of ALN and a length of 10 and 50 respectively.

Save the record and return the List tab, then select the Apply Configuration Changes and then click the Start Configuring the Database button. Because the changes are non-structural Admin Mode should not be required.

Automation Script

We will now use the non-persistent object that we just created to dynamically provide the list values in the desired order. This example is relatively simplistic, but this same strategy could be used to merge multiple object values or otherwise aggregate values from multiple sources.

Two things to note are that I am getting the MboSet independently from the MXServer and not through the current mbo variable via a relationship. This is so the new additional records do not get added to the current transaction and will not be saved. Second, I am using the try / finally pattern to close the MboSet and ensure there are no leaks. For details on closing MboSet you can review our post on this here.

Copy
Arrays = Java.type("java.util.Arrays");
MXServer = Java.type("psdi.server.MXServer");
SqlFormat = Java.type("psdi.mbo.SqlFormat");

// Get the non-persistent MboSet
var riskSet = MXServer.getMXServer().getMboSet("RISK", mbo.getUserInfo());

try {
    // Populate the non-persistent MboSet with values in the desired order.
    var riskMbo = riskSet.add();
    riskMbo.setValue("VALUE", "High");
    riskMbo.setValue("DESCRIPTION", "High Risk")

    riskMbo = riskSet.add();
    riskMbo.setValue("VALUE", "Medium");
    riskMbo.setValue("DESCRIPTION", "Medium Risk")

    riskMbo = riskSet.add();
    riskMbo.setValue("VALUE", "Low");
    riskMbo.setValue("DESCRIPTION", "Low Risk")

    listMboSet = riskSet;

} finally {
    riskSet.close();
}

// set the source and target attributes.
srcKeys = Arrays.asList(["VALUE"]);
targetKeys = Arrays.asList(["RISK"]);

// Script configuration for deployment
var scriptConfig = {
    "autoscript": "WORKORDER.RISK.LIST",
    "description": "Work Order List for Risk Assessment",
    "version": "1.0.0",
    "active": true,
    "logLevel": "ERROR",
    "scriptLaunchPoints": [
        {
            "launchPointName": "WORKORDER.RISK.LIST",
            "launchPointType": "ATTRIBUTE",
            "active": true,
            "description": "Work Order List for Risk Assessment",
            "objectName": "WORKORDER",
            "attributeName": "RISK",
            "retrieveList": true
        }
    ]
};

The list should return with the values in the order of Low, Medium, High as shown below.

Conclusion

In this post we demonstrated using and Attribute Launch Point with the Retrieve list event to provide and filter a value list. We showed using a linking simple value list from the implicit variables. We then reviewed a more complex version using the listMboSet implicit variable. Finally, we explored custom ordering by adding Mbo objects to a non-persistent MboSet in a determined order.

If you have any questions or comments please reach out to us at [email protected]