The Automation Script Warning Framework: A Pre-Upgrade Checklist for MAS 9.1

The Automation Script Warning Framework: A Pre-Upgrade Checklist for MAS 9.1If you have been running Maximo for more than a few years, you have automation scripts. You have Jython scripts that automate work order creation, JavaScript scripts that fire on attribute launch points, escalation rules that drive preventive maintenance, and integration scripts that call external systems. The script library that runs your operation is one of the most valuable assets in your Maximo deployment, and it is also one of the most fragile things you will touch during a MAS 9.1 upgrade.

The Automation Script Warning Framework is the tool that IBM built to surface the scripts that will break on Java 17, on the bundle separation changes, and on the new user management APIs. Most teams run it once, look at the output, and move on. The teams that run it well are the ones that treat the warnings as a triage backlog, work through the buckets in priority order, and validate the fixes against the Test Script harness before they cut over to MAS 9.1.

This article is a practitioner's guide to running the Warning Framework properly. We will cover what the framework actually checks, how to interpret the output buckets, the script patterns that show up as warnings, the Jython migration playbook that the field has settled on, and how to validate everything against the Test Script harness before you go live.

What the Warning Framework Actually Checks

The Warning Framework is a utility that ships with Maximo Manage. It scans your automation scripts, escalation rules, conditional expressions, and integration scripts against a set of patterns that IBM has identified as risky for current and future releases. The framework runs in the database, stores its findings in a result set, and produces a report that you can review in the application or export to a spreadsheet.

The checks fall into several categories. The most important ones for MAS 9.1 are Java 17 compatibility, memory leak patterns, direct SQL usage, network calls inside database transactions, missing cleanup, and use of deprecated APIs. Each check produces a warning with a severity (high, medium, low), a description, and a pointer to the script and launch point.

The Java 17 Compatibility Bucket

The highest-impact bucket for MAS 9.1 upgrades. The framework checks every script for patterns that work in JDK 8 but break in JDK 17. The most common offenders are:

• Nashorn-specific JavaScript extensions. Any script that uses Java.type(), Java.extend(), or Java.import() to instantiate Java classes from JavaScript. Nashorn supported these. The Nashorn-equivalent in JDK 17 is GraalVM JavaScript, which has different semantics.
• Browser-only JavaScript APIs. Any script that uses window, document, XMLHttpRequest, or other DOM APIs. These work in the browser, not in the server-side script engine.
• Rhino-only patterns. Some legacy scripts were written against Rhino (the older JavaScript engine). The patterns are subtly different from Nashorn and from GraalVM.
• JDK-internal class references. Any script that imports sun.* or com.sun.* classes. These are removed in JDK 17.

The framework flags these as high-severity warnings. Treat every high-severity warning in the Java 17 bucket as a script that needs to be rewritten in Jython before MAS 9.1.

The Memory Leak Bucket

The second-highest-impact bucket. The framework checks for patterns that allocate resources without releasing them. The most common offenders are:

• MboSet without cleanup. Every MboSet (the collection object that holds a query result) must be closed in a finally block. Scripts that open a MboSet and forget to close it leak memory and database cursors.
• Connection without close. Scripts that open a database connection directly must close it in a finally block.
• Stream without close. Scripts that read from a file or network stream without closing it.

The pattern is always the same: open in try, clean up in finally. The framework produces a warning for every script that violates this pattern. The cumulative effect of these leaks shows up in the JVM heap after weeks of operation and is one of the leading causes of slow MAS deployments that suddenly tip into instability.

# Pattern that passes the Warning Framework
# Properly cleaned-up MboSet usage
def main():
    try:
        assetSet = mbo.getMboSet("ASSET")
        assetSet.setWhere("LOCATION=:loc and STATUS='ACTIVE'")
        asset = assetSet.moveFirst()
        while asset is not None:
            # ... do work ...
            asset = assetSet.moveNext()
    finally:
        # Always run, even on exception
        if assetSet is not None:
            assetSet.cleanup()
            assetSet.close()

The Direct SQL Bucket

The third bucket, and the most controversial one. The framework flags any script that uses executeQuery or update to run SQL directly against the database. The reason is that direct SQL bypasses the Maximo business object layer, which means it bypasses the validation rules, the audit trail, the security model, and the MIF integration points.

Direct SQL is not illegal in Maximo. There are legitimate use cases (mass data migrations, custom reports, performance-critical batch jobs). But it is risky, and the framework treats it as a warning because most teams that use direct SQL are using it when they should be using a Maximo business object API.

For MAS 9.1, the recommendation is to inventory every script that calls executeQuery or update and decide whether each one needs to move to an integration object, an automation script with the MIF framework, or a direct MBO API call. Direct SQL is increasingly a non-starter for new code.

The Network Call Bucket

The fourth bucket. The framework flags any script that opens an HTTP, SOAP, or REST connection inside an object or attribute launch point. The risk is that the script holds a database transaction open over a network call. If the network is slow, the database transaction is held open, which blocks other users and creates lock contention.

The recommended pattern is to move these scripts into a publish channel, an external system call, or an outbox event. The publish channel pattern in MAS 9.1 is the most common replacement.

OUTBOUND_INTEGRATION Outbound integration to ERP system 3 60 https://erp.example.com/api/workorder OAUTH2

Running the Warning Framework Properly

The Warning Framework is not a fire-and-forget tool. The way you run it determines the quality of the output. The pattern that works is to run it on a non-production snapshot of production data, then triage the results in a structured way.

Step 1: Snapshot Production Data

Take a database snapshot of production (or a recent production backup) into a non-production environment. The Warning Framework is read-only, but it runs queries against your script library and your script execution history, so it needs realistic data.

Step 2: Run the Framework

Run the Warning Framework from the Maximo application or from the database command line. The framework stores its findings in a result table that you can query and export. Most teams export to CSV and load into a spreadsheet for triage.

Step 3: Triage by Bucket

Sort the warnings by bucket. Start with the Java 17 bucket because those are the scripts that will break on MAS 9.1. Then move to the memory leak bucket because those are the scripts that will cause JVM instability. Then direct SQL, then network calls, then everything else.

Step 4: Assign Owners

Each warning should have an owner and a target date. The bucket determines the priority. Java 17 warnings get the highest priority. Memory leak warnings get the next priority. Direct SQL and network calls are medium priority. Everything else is low priority and can be batched.

Step 5: Track in a Backlog Tool

Do not track the warnings in a spreadsheet after the initial triage. Push them into your normal backlog tool (Jira, Azure DevOps, ServiceNow) so they get the same visibility as any other defect.

The Jython Migration Playbook

The single biggest task that comes out of the Warning Framework is the Jython migration. Scripts written in JavaScript that need to be ported to Jython. The migration is mechanical but tedious, and there are several patterns that show up over and over.

Pattern 1: Variable Type Declarations

JavaScript is loosely typed. Jython is strongly typed. Every script that uses untyped variables needs to be reviewed. The common offenders are variables that hold a string but are sometimes used as a number, or variables that hold a list but are sometimes used as a dictionary.

# JavaScript (loosely typed) - WILL NOT WORK IN JDK 17
var count = 0;
var items = [];
for (var i = 0; i JavaScript uses `object.property` notation. Jython uses `object.getString("property")`, `object.getInt("property")`, etc. for Maximo business objects, and `object["key"]` for Python dictionaries.

The mechanical translation is straightforward but verbose. A typical 100-line JavaScript script becomes a 130-line Jython script when the property accesses are spelled out.

Pattern 3: Null Handling

JavaScript uses null and undefined. Jython uses None. The semantics are similar but not identical. Scripts that check for null and undefined separately need to be collapsed to is None.

Pattern 4: List Comprehensions

Jython supports list comprehensions, which are more concise than the JavaScript equivalent. If you are migrating a script that builds a list by iterating, consider rewriting it as a list comprehension. The result is shorter and faster.

# Jython list comprehension
active_assets = [a for a in asset_set if a.getString("status") == "ACTIVE"]

Pattern 5: Exception Handling

JavaScript uses try-catch-finally. Jython uses try-except-finally. The translation is mechanical. The key is to make sure every try block has a matching finally block that closes any MboSet or connection that was opened.

The Test Script Harness

The Test Script harness is the built-in tool for validating automation scripts. It lets you run a script with controlled inputs and inspect the outputs. Every script that comes out of the Warning Framework triage should be validated against the Test Script harness before it goes back into production.

The pattern is straightforward. You create a test case for the script. You specify the input parameters (the MBO, the attribute values, the launch point context). You run the script. You inspect the result. You save the test case so you can re-run it on future upgrades.

The teams that have the highest success rate with MAS 9.1 upgrades are the ones that have built a regression suite of test cases against their critical scripts. When IBM ships a new fixpack or a new release, they run the regression suite, see what breaks, and fix it before the upgrade touches production.

# Example test script for validating a Jython migration
def test_asset_status_filter():
    # Setup
    asset_set = mbo.getMboSet("ASSET")
    asset_set.setWhere("STATUS='ACTIVE'")
    asset = asset_set.moveFirst()

The test script pattern above is simple but illustrates the key principles: explicit setup, explicit execution, explicit assertion, explicit cleanup. Run this against your migrated Jython script. If it passes, the migration is correct. If it fails, you have a concrete error to debug.

Common Pitfalls

The teams that have published the worst MAS 9.1 upgrade post-mortems share several common patterns.

The first pitfall is treating the Warning Framework output as advisory rather than as a backlog. The output is not a list of suggestions. It is a list of scripts that will fail or degrade in production. Treat every high-severity warning as a P1 incident.

The second pitfall is turning on mxe.script.allowBeanScript globally. This flag allows automation scripts to access Maximo bean classes, which is convenient but dangerous. The flag is off by default for a reason. Turn it on per-environment, audit which scripts actually use it, and disable it once the dependent scripts are migrated.

The third pitfall is migrating scripts without testing them. The Jython migration is mechanical, but the semantics are not identical. A script that worked in JavaScript may behave differently in Jython (especially around null handling, type coercion, and list semantics). Run every migrated script through the Test Script harness before it goes to production.

The fourth pitfall is keeping direct SQL scripts in production after the MAS 9.1 upgrade. The framework warns about them for a reason. Even if a script works, it bypasses the validation rules, the audit trail, and the security model. Move direct SQL scripts to integration objects or MBO API calls over time.

The fifth pitfall is ignoring the small warnings. The Warning Framework produces low-severity warnings for things like deprecated API usage, unused variables, and inefficient queries. These are not urgent, but they accumulate. Address them as part of the upgrade cycle to keep the script library healthy.

Field-Tested Patterns

The teams that have the cleanest MAS 9.1 upgrades share several patterns that are worth replicating.

Pattern one is the dedicated script audit sprint. After running the Warning Framework, the team schedules a two-week sprint dedicated to script triage and migration. The sprint has clear ownership, clear priorities, and clear acceptance criteria.

Pattern two is the regression suite first. Before migrating any scripts, the team builds a regression suite of test cases against the existing scripts. The suite runs the scripts, captures the output, and stores it as the baseline. The migration is validated against this baseline.

Pattern three is the staged rollout. The migrated scripts go to a non-production environment first. The team runs a full integration test cycle against the migrated scripts. Then the scripts go to a staging environment that mirrors production. Then the scripts go to production.

Pattern four is the script ownership matrix. Every script has an owner. The owner is responsible for the script's correctness, its documentation, and its test coverage. The ownership matrix is maintained in the Maximo application and reviewed quarterly.

Pattern five is the deprecation policy. When a script is no longer needed, it is removed. When a script is replaced by a newer pattern, the old script is removed. The Warning Framework runs against a clean script library, not against a library full of dead code.

Practical Implications

The Automation Script Warning Framework is the single most valuable tool you have for a MAS 9.1 upgrade. The teams that run it well are the teams that upgrade on schedule and on budget. The teams that run it poorly are the teams that discover critical script failures in production.

For developers, the implication is that the script library is a first-class artifact. It needs to be version-controlled, tested, documented, and owned. The era of "scripts that someone wrote five years ago and nobody understands" is over.

For managers, the implication is that the Jython migration is a real cost. Budget for it. The teams that have budgeted for it have completed MAS 9.1 upgrades in six months. The teams that have not have taken twelve to eighteen months.

For architects, the implication is that the direct SQL and network call patterns need to be replaced. The publish channel pattern, the MIF framework, and the MBO API calls are the right tools for the MAS 9.1 era.

Bottom Line

The Warning Framework is not a one-time tool. It is a regular practice. Run it on every non-production snapshot. Triage the output. Track the warnings as defects. Migrate the high-severity warnings first. Test every migration. Deploy in stages.

The Java 17 transition, the bundle separation, and the new user management APIs are all stable. The risk is in your script library, not in the platform. The Warning Framework tells you exactly where that risk is. Use it.

If you have not yet run the Warning Framework, run it this week. If you have run it and ignored the output, the time to act is now. MAS 9.1 is the platform. Your scripts need to be ready.