Level 8 · 15 levels · Practitioner · about 85 minutes
Level 8 — Automation scripts, integrations, cron tasks and workflow up close
By the end: Read and write a Maximo automation script, pick the right launch point and event, raise a proper error with service.error, explain how the Integration Framework sends and receives messages through queues, and know how cron tasks, escalations and workflow run work on their own.
Five triggers each firing a script: a record being saved (object), a field changing (attribute), a button or workflow step (action), a message passing through integration (integration), and a condition being checked (custom condition).
Lesson 1
Automation scripts: small programs that live inside Maximo
An automation script is a short program stored as a record in the Maximo database and run by the Maximo server when something happens. IBM describes it as a small, targeted piece of code that extends the product, made of three parts: a launch point (when it runs), variables with their bindings (what it reads and writes), and the source code. You build all three in the Automation Scripts application, with wizards such as Create Script with Object Launch Point.
Languages. Maximo runs scripts written in Jython or JavaScript. Jython is the Python language running on the Java platform, at the 2.7 level, so you write Python 2.7 syntax and can call Java classes directly. Most Maximo teams write Jython, and most examples you find will be Jython. Both languages see the same Maximo objects.
Why scripts matter. A script runs inside the server and works through the same business objects (MBOs) as the screens, so its rule holds for a planner at a desk, a technician on Maximo Mobile, a REST call and an integration message. It ships as a record, in a Migration Manager package or through the REST API, with no rebuild. IBM introduced scripting in the Integration Framework as an approach that "removes the need to rebuild and redeploy the Maximo EAR file".
Implicit variables. Maximo hands every script a set of variables for free. You do not declare them.
| Variable | What it holds |
|---|---|
| mbo | The current record, for example the work order being saved |
| mboname | The name of that record's object, such as WORKORDER |
| onadd, onupdate, ondelete | True when the record is being added, updated or deleted |
| app | The Maximo application that started the script, such as WOTRACK |
| user | The user id of the person whose action started it |
| interactive | True when a person in a screen started it, false for REST, cron or integration |
| service | Helper methods: error(), log() and more |
| scriptName, launchPoint | The names of the script and the launch point that ran it |
| evalresult | The answer a condition script returns (true or false) |
Five triggers each firing a script: a record being saved (object), a field changing (attribute), a button or workflow step (action), a message passing through integration (integration), and a condition being checked (custom condition).
Implicit variables at work
# Jython. mbo, mboname, onadd, interactive, app, user and service arrive without any import.
if onadd and interactive:
service.log("New " + mboname + " " + mbo.getString("WONUM") + " created in " + app + " by " + user)The mistake: Write a script with no logging, test it once in DEV and call it done. Do this instead: Add service.log lines, set the script's log level, and test every path: add, update, through the screen and through REST. Scripts fail quietly when nobody looks at the log.
Remember: A script is a record. It has an owner, a version and a status (Draft or Active), and it moves between environments like any other configuration.
Lesson 2
The five launch points, and the events inside them
The launch point decides when your script runs. Picking the right one, and the right event inside it, is most of the skill. IBM's own overview maps each launch point to the Java class it replaces.
| Launch point | Runs when | Replaces | Example |
|---|---|---|---|
| Object | A record is initialised, validated, created, saved or deleted | A custom MBO class | Refuse to complete corrective work with no failure code |
| Attribute | One field is initialised, validated or changed, or its lookup list is opened | A field class | When the work type becomes EM, set priority 1 |
| Action | A workflow action node, an escalation, a button or a menu calls it | An action class | Email the supervisor when a PM is skipped |
| Integration | The Integration Framework processes an inbound or outbound message | Processing and exit classes | Reshape a finance message before Maximo reads it |
| Custom condition | A workflow condition, a security restriction or conditional UI asks a question | A condition class | Show a field only for certain work types |
Object launch point events. Initialize runs when a record is loaded, good for read-only flags and defaults. Validate Application runs while the record is checked before it is saved; IBM's scripting guide recommends it for validation. Allow Object Creation and Allow Object Deletion decide whether a record may be added or deleted at all. Save runs on add, update or delete, at one of three moments: Before Save (the record can still be changed), After Save (the SQL has run but nothing is committed, so a failure still rolls everything back) and After Commit (the data is safely in the database, the place for notices to other systems).
Attribute launch point events. Initialize Value sets a starting value, Initialize Access Restriction sets required, read-only or hidden, Validate checks a new value, Run Action reacts to a change, and Retrieve List fills a lookup. IBM's overview lists the order Maximo runs them in: Initialize Value, Initialize Access Restriction, Validate, Run Action, Retrieve List.
Five triggers each firing a script: a record being saved (object), a field changing (attribute), a button or workflow step (action), a message passing through integration (integration), and a condition being checked (custom condition).
An attribute launch point in Jython
# Attribute launch point: WORKORDER.WORKTYPE, event Run Action
# Emergency work always starts at the top priority.
if mbo.getString("WORKTYPE") == "EM":
mbo.setValue("WOPRIORITY", 1)A condition script sets evalresult
# Custom condition launch point: tell workflow whether the cost needs a manager
evalresult = mbo.getDouble("ESTTOTALCOST") > 10000Scripts without a launch point. A cron task can run a script on a schedule; IBM says such a script does not need a launch point. A script can also be called over REST at /maximo/oslc/script/ followed by its name, which makes a small custom API endpoint. Both are handy and both deserve the same care as any other code.
Order between scripts. If two scripts hang on the same event, IBM's support note is blunt: Maximo "does not provide a solution to run the scripts sequentially, instead it runs the scripts randomly". When order matters, put the steps in one script, or call them from one place in a fixed order.
The mistake: Hang the same rule on a work order Before Save in one script and on the STATUS attribute in another, and expect them to run in a set order. Do this instead: One rule, one launch point, one script. If you need steps in order, put them in one script.
Remember: Ask "is this rule about one field or the whole record?" One field: attribute launch point. The whole record: object launch point.
Lesson 3
A worked example: the completion gate
Here is a real request, built start to finish. The reliability engineer says: "Corrective work orders must have a failure code before anyone can complete them. We cannot learn from failures we never recorded." In Maximo a work order is completed when its status moves to COMP. Corrective work has the work type CM in the sample data most systems start from.
Step 1: the message. The user needs to know what went wrong and what to do. Create a message in Database Configuration (Messages): group custom, key failurecodeRequired, text "Work order {0} needs a failure code before it can be completed. Pick one on the Failure Reporting tab." The {0} is filled in by the script.
Step 2: the script and launch point. Create an object launch point on WORKORDER. Use the Validate Application event, which IBM recommends for checks (Save with Add and Update, Before Save, also works). Only check when the status is actually changing, compare the internal status value so a synonym such as a customer's own "DONE" status still counts, and raise the error with service.error, which stops the save at once.
The completion gate
# Script WOCOMPGATE (Jython)
# Launch point WOCOMPGATE_LP: Object, WORKORDER, event Validate Application
# Message: group "custom", key "failurecodeRequired"
# "Work order {0} needs a failure code before it can be completed."
if mbo.isModified("STATUS"):
status = mbo.getTranslator().toInternalString("WOSTATUS", mbo.getString("STATUS"), mbo)
if status == "COMP" and mbo.getString("WORKTYPE") == "CM" and mbo.isNull("FAILURECODE"):
service.error("custom", "failurecodeRequired", [mbo.getString("WONUM")])A technician sets a work order to COMP with no failure code. The save triggers the automation script, the script raises an error, and the save is stopped with a message. With a failure code filled in, the save goes through.
Why service.error. IBM's scripting docs give three ways to raise an error. service.error(group, key, params) is the one to use: it throws at once, so nothing after it runs. Raising MXApplicationException yourself works the same way. Setting the old errorgroup and errorkey variables is deprecated, because the error was only thrown after the script finished.
Step 3: test every path. The rule lives in the business objects, so it must hold everywhere. Test it in the Work Order Tracking screen, through Maximo Mobile and through the REST API, and test the passing case too.
| Test case | Expected result |
|---|---|
| CM work order, no failure code, set to COMP in the screen | Refused with the message, status stays INPRG |
| CM work order, failure code filled in, set to COMP | Saved as COMP |
| PM work order, no failure code, set to COMP | Saved: the rule is for corrective work only |
| CM work order, no failure code, changeStatus through REST | HTTP 400 with the custom message in the error body |
| CM work order already COMP, description edited | Saved: the status did not change |
A technician sets a work order to COMP with no failure code. The save triggers the automation script, the script raises an error, and the save is stopped with a message. With a failure code filled in, the save goes through.
The mistake: Check mbo.getString("STATUS") == "COMP" on every save, without isModified, and compare the word on the screen. Do this instead: Check only when STATUS is modified, and compare the internal value through the WOSTATUS domain. Otherwise old records cannot be edited and synonym statuses slip past.
Remember: Assetize's Script Test Harness runs a WORKORDER object script against a release's real MXAPIWODETAIL dictionary and checks every field it names exists on that version.
Lesson 4
The Integration Framework: how Maximo talks to other systems
Big customers connect Maximo to finance (ERP), maps (GIS), sensors, contractors and HR. The Integration Framework, often called MIF, does it with a few building blocks. All of them are configuration records, built in their own Maximo applications.
- Object structure: the shape of the data. IBM calls it "the common data layer that the integration framework components use". The MXAPI structures, such as MXAPIWODETAIL (a work order with its tasks, planned labour and planned materials), are the ones the REST API uses.
- Enterprise service: the way in. IBM: "a pipeline for querying and importing data from an external system", synchronous or asynchronous.
- Publish channel: the way out, asynchronous. IBM: "used for sending asynchronous messages, through a JMS queue, to an external system", fired by an event (an event listener on the object) or by a data export.
- Invocation channel: the way out when you need the answer straight away (synchronous), for example asking a tax system for a rate.
- External system: the partner, with its own settings, the services and channels it uses, and its queues.
- Endpoint and handler: where and how to deliver. IBM: "An endpoint and its associated handler routes outbound messages to an external system." Handlers cover HTTP, web services, JMS, XML and flat files, and interface tables.
The MXAPIWODETAIL object structure drawn as a box holding WORKORDER with its children: tasks (WOACTIVITY), planned labour (WPLABOR) and planned materials (WPMATERIAL). An API call reads the whole bundle in one answer.
An ERP and a GIS on the left, Maximo on the right. Every lane passes through an object structure. Messages come in through an enterprise service and its inbound queue, and go out through a publish channel and its outbound queue to an endpoint when a work order changes. An invocation channel calls out and waits for the answer, and the REST/OSLC API sits beside them.
Formats. MIF speaks XML and JSON, and can deploy enterprise services and object structure services as SOAP web services. IBM gives the address form as /meaweb/services/ followed by the web service name. The contract for a SOAP service is its WSDL (Web Services Description Language), a machine-readable file that lists the operations and message shapes. Older integrations were often generated from that WSDL. Pull one in the mission on this level.
Where scripts plug in. In the Automation Scripts application, Script for Integration attaches a script to an object structure, publish channel, invocation channel, enterprise service or endpoint. A publish channel has three places to hook in: the event filter (should this event be published at all?), the user exit (runs before and after the main step) and the external exit (the main reshaping step). Enterprise services and invocation channels have the user exit and external exit. In these scripts the message is irData (Maximo's format) and erData (the external format). There is no mbo variable; in an event filter IBM's docs use service.getMbo() instead.
An integration script, adapted from IBM's examples
# Script PUBLISH.MXASSETINTERFACE.EXTEXIT.OUT (external exit on a publish channel)
# Fill in the description for operating assets before the message leaves Maximo.
if irData.getCurrentData("STATUS") == "OPERATING":
irData.setCurrentData("DESCRIPTION", "Operating asset")
service.log("MXASSETINTERFACE: description set")Logging in. On MAS, an integration calling in sends an API key in the apikey header, tied to an integration user whose security groups allow exactly what it needs (Level 6). Outbound endpoints keep their own credentials, and those differ in every environment.
The mistake: Copy DEV's endpoints into PROD in a release package. Do this instead: Endpoint addresses, credentials and enabled flags belong to each environment. Leave them out of the package and set them per environment, so PROD never posts to a test finance system.
The Integration Framework, drawn
Remember: In: enterprise service. Out, no answer needed: publish channel. Out, answer needed now: invocation channel.
Lesson 5
Queues, errors and reprocessing
Asynchronous messages wait in queues. IBM: "Asynchronous messages are processed through the Java Message Service (JMS) queues." JMS is the standard Java way to pass messages between programs. Maximo ships with a set of queues, named by their JNDI names: an inbound sequential queue (jms/maximo/int/queues/sqin), an outbound sequential queue (sqout), an inbound continuous queue (cqin) and an error queue for it (cqinerr). From Manage 8.7, outbound continuous queues are available too, with JMS or Kafka. Kafka topics can be registered as Maximo queues through a Kafka message provider in the External Systems application.
| Sequential queue | Continuous queue |
|---|---|
|
|
Two queues receive the same messages, one of them bad. The sequential queue keeps order and stops at the bad message. The continuous queue processes in parallel, retries and parks the bad one, and keeps going. Both list the failure in Message Reprocessing, where it is fixed and sent again.
What happens to a bad message. IBM's queue-based error management says the framework tries the message several times, then flags it as an error, creates a record you can view and manage in the Message Reprocessing application, and sends a notice to an email address. The address comes from the mxe.int.admintoemail system property, unless the queue has its own address, which then wins. For continuous queues, an error queue keeps failing messages out of the main queue so it does not clog.
Message Tracking. Turn on message tracking on a publish channel or enterprise service and the Message Tracking application records each message and its state: received, processed or in error. Message Reprocessing then lets you see the error, fix the data or the message, and send it again, or delete it. In Manage 9.2, IBM added consumer details to tracking; messages from before the upgrade show the Consumer Name blank and "Processed by MDB?" off.
- Message arrives on the queue
- Processing fails
- Retried
- Flagged as an error
- Email to the integration admin
- Fix it in Message Reprocessing
- Reprocess or delete
The life of a failed message
A request is sent, the network drops the answer, and it is sent again. On the left, without protection, two records are created. On the right, with an idempotent request, there is still one record.
The mistake: Put every integration on a continuous queue "because it is faster". Do this instead: Choose by the data. If message 2 depends on message 1 (create, then update), keep order with a sequential queue. Use continuous queues for independent, high-volume messages.
Remember: Sequential: order, stops on error. Continuous: throughput, keeps going. Know which one each integration uses before go-live.
Lesson 6
Cron tasks, escalations and workflow: work that runs on its own
Cron tasks. A cron task is a job the Maximo server runs on a schedule. In the Cron Task Setup application each cron task has a definition (the Java class that does the work) and one or more instances, each with its own schedule, parameters, run-as user and an Active tick. Familiar ones: PMWOGENCRONTASK generates work orders from preventive maintenance records, JMSQSEQCONSUMER reads the sequential queues, ESCALATION runs escalations, and the XML file and interface table consumers read inbound files and tables. To run your own script on a schedule, IBM's steps are: create a cron task with the class com.ibm.tivoli.maximo.script.ScriptCrontask, set its SCRIPTNAME parameter to your script, set the schedule on an instance, and tick Active. On MAS, cron tasks run in the cron server bundle (or the all bundle).
Escalations. An escalation watches records over time and acts when they are overdue. You build it in the Escalations application: the object (for example WORKORDER), a condition in SQL that picks the records, a schedule, and escalation points. Each point names an elapsed-time attribute (such as REPORTDATE or TARGSTARTDATE) and can add its own condition. When a record matches, the escalation runs its actions (change status, set a field, start a workflow) and sends notifications from communication templates. Escalations run through the ESCALATION cron task.
A priority 1 escalation, as you would fill it in
Escalation WOP1LATE on WORKORDER
Condition wopriority = 1 and status = 'WAPPR' and istask = 0 and historyflag = 0
Schedule every 15 minutes
Point 1 elapsed time from REPORTDATE: 2 hours
Action none
Notification communication template WOP1LATE to the supervisorA clock ticks. Cron tasks run jobs on schedule: generate PM work, read queues, run escalations. An escalation checks for priority 1 work still waiting after two hours and sends the supervisor a notice.
Workflow. Workflow routes one record through people and decisions: approve, reject, wait, escalate. You draw it in the Workflow Designer from node types: Start, Task (a person must act), Condition (a yes/no question, which can be a condition script), Manual input (the person picks a path), Interaction (opens a screen), Subprocess, Wait (for an event) and Stop. Lines leave a node as positive or negative paths, and actions can run on a line. A process is enabled and activated before records can enter it, through the Route Workflow button, automatically on create, or from an escalation action. A workflow assignment goes to a role, so it reaches whoever holds that job today.
A workflow drawing: Start, a supervisor approval task, a condition on cost, then approved or rejected paths ending at Stop. A record token travels the route.
The mistake: Escalate on a condition with no time limit, every minute, on a million work orders. Do this instead: Narrow the condition (status, priority, site, not history), set a sensible schedule and use escalation points with elapsed time. Escalations are SQL on a timer, and slow SQL on a timer slows everyone.
Escalations and cron tasks, drawn
Remember: Every script, channel, queue, cron task, escalation and workflow is something a release must deploy and a test should check. Hold on to that for Levels 9 and 10.
Level 8 missions in the Maximo sim
- Pull a SOAP contract. Fetch the WSDL for the MXWODETAIL web service: the contract an older integration is built from.
Real practice on the Maximo SIM
Tasks you do by hand on the training Maximo, with the evidence your trainer checks.
- Write your first automation script (DEV). A completion gate is the classic first script: stop a work order being completed without a failure code.
- Find an integration message (DEV). When an integration breaks, Message Tracking is where you start. Know where it is before you need it.
Check yourself: the Level 8 quiz
18 questions. Pass mark 70%.
- Which languages can Maximo automation scripts be written in?
- Jython and JavaScript
- C and C++
- Only SQL
- COBOL
- Look at the lit trigger. A planner sets the work type to EM and the priority should jump to 1 straight away. Which launch point is this? (picture: Five ways a script starts)
- Object
- Integration
- Attribute
- Custom condition
- In a script, what is mbo?
- A database connection
- A log file
- The logged-in user
- The record the script is running for
- Look at the picture. A technician sets COMP on corrective work with no failure code. What happens? (picture: A completion gate in action)
- The save goes through
- The script raises an error and the save stops with a message
- The work order is deleted
- Maximo fills in a failure code by itself
- Which picture shows the save going through?
- Picture A
- Picture B
- How should a script stop a save with a clear message?
- print("error")
- Set errorkey and errorgroup and carry on
- service.error(group, key, params) with a message defined in Maximo
- Delete the record
- Your completion gate checks STATUS == "COMP" on every save without isModified. What goes wrong?
- Every later edit to an old COMP work order with no failure code is refused
- Nothing
- The script runs faster
- Workflow stops
- Two scripts hang on the same save event. In what order do they run?
- Alphabetical order
- The order they were created
- Longest first
- IBM says there is no set order
- Look at the picture. Which MIF part builds and sends this message out of Maximo when the work order changes? (picture: The Integration Framework)
- Enterprise service
- Publish channel
- Domain
- Job plan
- Maximo must ask a tax system for a rate and use the answer straight away. Which MIF part fits?
- Invocation channel
- Publish channel
- Enterprise service
- Cron task
- Look at the picture. One bad message reaches this sequential queue. What happens to the messages behind it? (picture: Sequential and continuous queues)
- They are processed in parallel
- They are deleted
- They wait until the bad one is fixed or removed
- They skip to PROD
- Which picture shows a continuous queue?
- Queue A
- Queue B
- Where do you find, fix and resend a failed integration message?
- Application Designer
- BIRT
- The Assets application
- The Message Reprocessing application
- Look at the picture. What runs this two-hour priority 1 check? (picture: Cron tasks and escalations)
- A person with a stopwatch
- An escalation, run by the ESCALATION cron task on its schedule
- Migration Manager
- updatedb
- How do you run your own automation script every night?
- Ask a user to press a button
- A publish channel
- A cron task with class ScriptCrontask and the SCRIPTNAME parameter, on an active instance
- A DBC script
- Look at the picture. The supervisor rejects the request. Where does the record go? (picture: A workflow route)
- Down the reject path to Stop
- Straight to CLOSE
- Back to DEV
- Into a queue
- What describes a SOAP web service's operations and message shapes?
- A JSON comment
- A cron task
- A domain
- A WSDL
- In an integration script on a publish channel, how do you read the message?
- Through mbo
- Through irData (Maximo format) and erData (external format)
- Through the clipboard
- Through a BIRT report
Remember it as a picture
- Automation script: A launch point, variables and source code, stored as a record and run by the server. Jython or JavaScript.
- Object launch point: Runs when a record is initialised, validated, saved or deleted. Save has Before Save, After Save and After Commit.
- Attribute launch point: Runs for one field: Initialize Value, Initialize Access Restriction, Validate, Run Action, Retrieve List.
- Action launch point: Called by a workflow action node, an escalation, a button or a menu.
- Custom condition: Answers a yes/no question for workflow, security or conditional UI by setting evalresult.
- service.error: Stops the save at once with a message from Database Configuration. The old errorkey way is deprecated.
- Object structure: The shape of the data: a main object and its children, read or written as one bundle.
- Enterprise service: The way in: a pipeline for querying and importing data from an external system.
- Publish channel: The way out: asynchronous messages through a JMS queue to an endpoint when something changes.
- Sequential queue: One at a time, in order, read by JMSQSEQCONSUMER. Stops at the first error.
- Continuous queue: Many at once, read by MDBs. Sets errors aside and keeps going.
- Cron task and escalation: Cron tasks run jobs on a schedule. An escalation finds overdue records and acts, run by the ESCALATION cron task.
- Workflow: Routes one record through people and decisions: Start, Task, Condition, Manual input, Wait, Stop.
- WSDL: The contract of a SOAP web service, served by Maximo at /meaweb/services/<name>?wsdl.
Where these facts come from
- IBM Docs: Framework for data exchange (Integration Framework components)
- IBM Docs: Queue-based error management
- IBM Docs: Examples of using automation scripts during processing by channels and services
- IBM Support: Overview of automation script launch points and sequentially ordered scripts
- IBM Maximo automation scripting guide: object launch points and raising errors
- IBM Docs: Creating cron tasks that run automation scripts
- Assetize record: Script with an object launch point
- Assetize record: Message Reprocessing works with Message Tracking
Try it on the real tools
How did Level 8 go?
Rate the level and say what worked, what did not, what you liked and what you did not. Send it now, or with your full report.