Assetize

Learning Lab

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 ways a script starts: a record is saved, a field changes, a button or workflow step calls it, a message passes through integration, or a condition is checked. Every script you write hangs on one of these.

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.

VariableWhat it holds
mboThe current record, for example the work order being saved
mbonameThe name of that record's object, such as WORKORDER
onadd, onupdate, ondeleteTrue when the record is being added, updated or deleted
appThe Maximo application that started the script, such as WOTRACK
userThe user id of the person whose action started it
interactiveTrue when a person in a screen started it, false for REST, cron or integration
serviceHelper methods: error(), log() and more
scriptName, launchPointThe names of the script and the launch point that ran it
evalresultThe answer a condition script returns (true or false)
Five ways a script starts. Five triggers, one script engine. Watch each trigger fire its script in turn: save, field change, action, message, condition.

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.

Automation scripts, drawn

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 pointRuns whenReplacesExample
ObjectA record is initialised, validated, created, saved or deletedA custom MBO classRefuse to complete corrective work with no failure code
AttributeOne field is initialised, validated or changed, or its lookup list is openedA field classWhen the work type becomes EM, set priority 1
ActionA workflow action node, an escalation, a button or a menu calls itAn action classEmail the supervisor when a PM is skipped
IntegrationThe Integration Framework processes an inbound or outbound messageProcessing and exit classesReshape a finance message before Maximo reads it
Custom conditionA workflow condition, a security restriction or conditional UI asks a questionA condition classShow 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 ways a script starts. The attribute trigger is lit: a single field changing. Use it when a rule is about one field, not the whole record.

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") > 10000

Scripts 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 completion gate in action. Watch the technician set COMP with no failure code. The save triggers the script, the script raises the error, and the save stops with the message.

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 caseExpected result
CM work order, no failure code, set to COMP in the screenRefused with the message, status stays INPRG
CM work order, failure code filled in, set to COMPSaved as COMP
PM work order, no failure code, set to COMPSaved: the rule is for corrective work only
CM work order, no failure code, changeStatus through RESTHTTP 400 with the custom message in the error body
CM work order already COMP, description editedSaved: the status did not change
A completion gate in action. The passing case: a failure code is filled in, the script finds nothing wrong, and the save goes through.

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.
An object structure bundles objects. The MXAPIWODETAIL object structure: the work order with its tasks, planned labour and planned materials, read or written as one bundle.

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.

The Integration Framework. Follow the outbound message: a work order changes, the publish channel builds the message, a queue holds it, and the endpoint delivers it to the ERP.

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 queueContinuous queue
  • One message at a time, in order
  • Read by the JMSQSEQCONSUMER cron task (instances such as SEQQIN and SEQQOUT)
  • A failing message stops the queue: IBM says only a single error can exist in it
  • Use when order matters: a work order must exist before its status change
  • Many messages at once, on several threads
  • Read by message-driven beans (MDBs) as messages arrive
  • A failing message is set aside and the rest keep going; many errors can build up
  • Use for volume: meter readings, bulk asset updates
Sequential and continuous queues. The same messages, one of them bad, go into both queues. The sequential queue keeps order and stops at the bad one. The continuous queue sets it aside and keeps going.

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.

  1. Message arrives on the queue
  2. Processing fails
  3. Retried
  4. Flagged as an error
  5. Email to the integration admin
  6. Fix it in Message Reprocessing
  7. Reprocess or delete

The life of a failed message

Safe to press twice. Reprocessing sends a message again. If the first attempt half-landed, only an idempotent design keeps it to one record. Design every integration to be safe to send twice.

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 supervisor
Cron tasks and escalations. The clock ticks and the cron tasks run: PM work generation, queue readers, escalations. Watch the escalation find a priority 1 work order still waiting after two hours and notify the supervisor.

A 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 route. A work order enters the route: supervisor approval, then a condition on cost. Follow the token down the approve path to Stop.

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

  1. 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.

  1. Write your first automation script (DEV). A completion gate is the classic first script: stop a work order being completed without a failure code.
  2. 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%.

  1. Which languages can Maximo automation scripts be written in?
    • Jython and JavaScript
    • C and C++
    • Only SQL
    • COBOL
  2. 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
  3. In a script, what is mbo?
    • A database connection
    • A log file
    • The logged-in user
    • The record the script is running for
  4. 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
  5. Which picture shows the save going through?
    • Picture A
    • Picture B
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. Which picture shows a continuous queue?
    • Queue A
    • Queue B
  13. Where do you find, fix and resend a failed integration message?
    • Application Designer
    • BIRT
    • The Assets application
    • The Message Reprocessing application
  14. 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
  15. 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
  16. 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
  17. What describes a SOAP web service's operations and message shapes?
    • A JSON comment
    • A cron task
    • A domain
    • A WSDL
  18. 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

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.