Level 7 · 15 levels · Practitioner · about 80 minutes
Level 7 — How software development is done in the Maximo world
By the end: Choose the lightest layer for a Maximo change (configuration, script, integration, report, mobile or Java), explain how DEV, TEST, UAT and PROD fit together, and move each kind of change the right way: Migration Manager, DBC scripts and updatedb, customisation archives and rebuilds, or data loads.
A stack from light to heavy: configuration at the top, then automation scripts, then integration, reports and mobile, then Java at the bottom. Two meters show effort and upgrade risk growing as you go down.
Lesson 1
The layers of change, from lightest to heaviest
In most software projects you write code for almost everything. Maximo is different. It is a product that customers configure. A large part of the change a customer asks for is made inside Maximo's own administration applications, by filling in records, not by writing code. Code comes second, and Java comes last.
Think of the change options as a stack of layers. Configuration sits on top: new fields, value lists, screen changes, approval routes, scheduled checks. Below it are automation scripts: small programs stored in the database. Then integration, reports and mobile apps, which each have their own tools. At the bottom is Java: custom classes compiled against Maximo's own code and built into the application.
| Layer | Where you make it | Typical change | How it ships |
|---|---|---|---|
| Configuration | Database Configuration, Domains, Application Designer, Workflow Designer, Escalations, Cron Task Setup, Conditional Expression Manager | A new field, a value list, a screen tab, an approval route, a scheduled check | Migration Manager package; no rebuild |
| Automation scripts | Automation Scripts application (Jython or JavaScript) | A rule on save, a default value, a field that must be filled in | Migration Manager package or REST; no rebuild |
| Integration | Object Structures, Enterprise Services, Publish Channels, External Systems, End Points | Send work orders to finance, receive assets from GIS | Migration Manager package; endpoints set per environment |
| Reports | BIRT Report Designer, Report Administration | A printed work pack, a backlog report | Import the report design; no rebuild |
| Mobile | Maximo Mobile apps built on the Maximo Application Framework (Graphite) | What a technician sees and fills in on a phone | Application configuration tools |
| Java | Custom MBO, field and bean classes in an IDE | Deep rules no script can reach | EAR rebuild (7.6.1) or customisation archive and image rebuild (MAS) |
A stack from light to heavy: configuration at the top, then automation scripts, then integration, reports and mobile, then Java at the bottom. Two meters show effort and upgrade risk growing as you go down.
Why lighter is better. Configuration and scripts live in the database as records. They upgrade with the product, they can be read in the screens, and they move between environments without a rebuild. Java is compiled against IBM's classes, so when IBM changes a class in an upgrade your code may stop compiling or behave differently. Every Java class is a line in the next upgrade's risk register.
The mistake: Reach for Java first because it is "real code" and you know Java. Do this instead: Configuration first, then scripts, then Java. Ask what would happen to this change in the next upgrade, and choose the layer that keeps that answer short.
Remember: Configuration before scripts, scripts before Java. The heavier the layer, the harder the next upgrade.
Lesson 2
Configuration in depth: data, values, screens and rules
Configuration is real development work in Maximo, and most of a Maximo team's changes live here. Five administration applications do most of it.
- Database Configuration: objects (tables) and attributes (columns). You add a field such as WORKORDER.CUSTREF, set its type and length, make it required, link it to a domain, or set the Java class behind an object. Changes wait as pending until you apply them.
- Domains: lists of allowed values. ALN domains hold plain codes, numeric domains hold numbers, table domains read values from another table, crossover domains copy values across, and synonym domains map your words to Maximo's internal values, such as AWAITPARTS for WMATL.
- Application Designer: the screens. Every classic Maximo application is an XML document called a presentation. You add a field to a tab, a new tab, a table, a button or a dialog by editing it, either by dragging controls or by exporting and importing the XML.
- Conditional Expression Manager: named conditions, written as SQL expressions or backed by a Java class or a condition script, that other tools reuse. A condition can hide a field, make it read-only or required, or decide a workflow route.
- Workflow Designer, Escalations and Cron Task Setup: processes and schedules. Level 8 covers them up close.
The WORKORDER object drawn as a card of attributes: WONUM, DESCRIPTION, STATUS, ASSETNUM, LOCATION, SITEID, WORKTYPE. STATUS opens a list of allowed values from its domain, WOSTATUS.
Applying database changes. When you save a change in Database Configuration it is stored as pending. You then run Apply Configuration Changes, which changes the real tables. IBM's documentation says some changes need administration mode: the system stops the other cluster members while the structure changes and restarts them when admin mode is turned off. An IBM page on configuring a new system also warns that if you do not turn admin mode off again, cron tasks fail. So a structure change is planned like a small outage.
A customer value such as AWAITPARTS maps to Maximo's internal value WMATL. The screen shows the customer's word; the business rules use the internal value.
A screen change is XML in the presentation
<!-- Application Designer presentation: one new field on the work order main tab -->
<section id="main_grid3_1">
<textbox id="main_custref" dataattribute="custref" label="Customer reference"/>
</section>The mistake: Make a field required only on the screen, then wonder why the integration still creates records without it. Do this instead: A screen setting applies to that screen. A rule that must hold everywhere (screens, REST, integrations) belongs in the data model or the business rules: Database Configuration, or a script on the object.
Remember: Every configuration change is a record. Records can be listed, compared, packaged and moved. That is what makes configuration the lightest layer.
Lesson 3
When configuration is not enough: scripts, integration, reports, mobile and Java
Automation scripts. A script is a small program stored in the database and run by Maximo when something happens: a record is saved, a field changes, a button is pressed, a message arrives. It runs inside the server and uses the same business objects as the screens, so its rules apply everywhere. Scripts are written in Jython (Python 2.7 syntax on the Java platform) or JavaScript. Because a script is a record, it ships without rebuilding the application. Level 8 is about scripts.
Integration. When Maximo must talk to another system you use the Integration Framework: object structures describe the data, enterprise services bring it in, publish channels send it out, and endpoints say where and how. Most of it is configuration. Scripts plug into it for reshaping and filtering.
Reports. Maximo's reporting engine is BIRT, an open-source report designer. You build a report design in the BIRT Report Designer and import it into Maximo. The BIRT version moves with Manage: IBM lists BIRT 4.8.0 for Manage 8.3, 4.16 for Manage 9.1 and 4.21 for Manage 9.2, so a customised report is re-tested on every upgrade.
Mobile. Maximo Mobile and the newer role-based apps are built on the Maximo Application Framework, also called Graphite: apps described in XML with JavaScript controllers. You change them with IBM's application configuration tools. IBM notes that configuration changes made to apps on the previous Maximo Asset Management framework cannot be migrated to Maximo Application Framework apps, so those changes are rebuilt in the new tools.
Java. Under every Maximo object is a Java class: WORKORDER is psdi.app.workorder.WO, for example. A Java customisation extends that class, overrides a method such as init(), appValidate() or save(), and is registered on the object in Database Configuration. It can do anything, and that is the danger: it depends on IBM's internal classes, it needs a build and a restart to ship, and IBM's upgrade checklist expects it to be recompiled for new Java versions (Java 17 for Manage 9.1).
| Automation script | Java MBO class |
|---|---|
|
|
Screens, the REST API and integrations all send changes through the MBO business rules layer, which checks them before they reach the database. A direct SQL arrow that tries to skip the rules is blocked with a red cross.
How a Java MBO customisation fits in, drawn
The mistake: Write directly to the database with SQL to "fix" data quickly. Do this instead: SQL skips every business rule, status history and integration event. Change data through the application, the REST API or a data load, so the MBO rules run.
Remember: If a script can do it, do not write Java. If configuration can do it, do not write a script.
Lesson 4
Environments: DEV, TEST, UAT, PRE-PROD and PROD
Nobody changes production directly. A Maximo customer runs several copies of the system, called environments. Each is a full Maximo with its own database, its own users and its own connections to other systems. In MAS each one is usually its own Manage workspace, often on its own cluster.
| Environment | Who uses it | What it is for |
|---|---|---|
| DEV | Developers and configurators | Build and try changes. Things break here, and that is fine. |
| TEST (or SIT) | Testers and the integration team | Check the change works, including with the other systems' test copies. |
| UAT | Planners, supervisors, storeroom staff | User acceptance testing: the people who will use it say yes or no. |
| PRE-PROD | Administrators | A rehearsal on a recent copy of production: same data volume, same steps, timed. |
| PROD | Everyone at work | The real system. Changes arrive only in an agreed window, after sign-off. |
A change package moves from DEV to TEST to PRE-PROD to PROD. At each gate a check runs and someone signs off before it moves on.
Refreshes. Every few months the lower environments are refreshed: PROD's database is copied down so testers work with realistic data. A refresh wipes any change that was built in DEV but not yet captured, which is a good reason to package changes as you go. Copied data often holds personal details, so many customers mask names and addresses after a refresh.
Drift. Over time environments drift apart: someone fixes a domain value in PROD by hand, a script in TEST is a version ahead, an endpoint points at the wrong server. Drift is why "it worked in TEST" is not proof. Good teams compare environments regularly and treat every difference as a question.
What must differ. Some settings must not travel: endpoint addresses, external system flags, system properties with host names, email servers and keys. Each environment points at its own partners. A change package that copies DEV's endpoint into PROD can send real purchase orders to a test finance system.
The mistake: Change PROD "just this once" and plan to copy it back to DEV later. Do this instead: Make the change in DEV, move it up through the gates, and let PROD receive it the same way as everything else. If it is urgent, run the same path faster.
Remember: Same change, same steps, every environment. That is what makes a release boring, and boring is the goal.
Lesson 5
Moving change: Migration Manager, DBC scripts, archives and data loads
Each kind of change has its own way of travelling. Learn the four lanes and you will always know how a change reaches PROD.
Four lanes: configuration moves in Migration Manager packages, database structure moves in DBC scripts run by updatedb, Java moves in a customisation archive and a rebuild, and data moves in data loads.
Lane 1: configuration in Migration Manager. IBM describes the Migration Manager application as the tool to migrate configuration content between product environments: in the source you define, create and distribute packages, in the target you deploy them. Content is grouped into migration groups (built from object structures). A package definition is a reusable template that names the groups. A snapshot package takes the configuration as it is now; a change package records inserts, updates and deletes made after it is turned on. Migration Manager is built for environments at the same release level, and IBM states it does not support packages from different versions of Manage. Since 7.6.1.3 and 8.x, IBM also offers Migration Manager REST APIs to move packages from source to target.
- Define the package (groups, type)
- Create it in DEV (manifest)
- Distribute it as a file
- Deploy it in TEST, then UAT, then PROD
The Migration Manager path
Lane 2: database structure in DBC scripts. A DBC script is an XML file of database statements in Maximo's own format. Its structure statements, such as add_attributes, work on Db2, Oracle and SQL Server alike; raw SQL goes in a freeform statement, which can carry a separate version for each database. The updatedb tool runs scripts in version order and records the last one it ran, so each script runs exactly once in each database. Customer scripts sit in a cust folder and are named by a product XML file, a_customer.xml, whose dbversion entry tells updatedb how far to go.
tools/maximo/en/cust/V7612_01.dbc
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE script SYSTEM "script.dtd">
<script author="assetize" scriptname="V7612_01">
<description>Add a customer reference to work orders</description>
<statements>
<add_attributes object="WORKORDER">
<attrdef attribute="CUSTREF" maxtype="UPPER" length="20" persistent="true"
required="false" userdefined="true" haslongdesc="false"
title="Customer ref" remarks="Customer reference number"/>
</add_attributes>
</statements>
</script>Lane 3: Java in a rebuild. On 7.6.1 you rebuild the EAR in the SMP folder and redeploy it. On MAS you put the classes, DBC scripts and a_customer.xml in a customisation archive; the operator builds new images, updatedb runs, and the pods roll (Level 6). Either way it is a planned window.
Lane 4: data in data loads. Assets, locations, items and people are data, not configuration. They travel through the REST API or Integration Framework, with tools such as MXLoader spreadsheets or the Data Workbench, which checks every row, previews every create, change and delete, loads, and reconciles what landed.
A spreadsheet becomes a load in steps: add your Maximo, pick the object structure, map columns, run the checks and one-click fixes, preview every create, change and delete, load, read each row's result, and reconcile against Maximo.
Order matters. A typical release runs the lanes in order: DBC and Java first (the new field must exist), then Migration Manager (screens and scripts that use it), then data. Doing this by hand from a checklist is slow and easy to get wrong. That pain is why mxR exists: it reads the Git diff, decides whether a change is HOT, RESTART or REBUILD, and runs the same steps on each site. You will meet it in Level 10.
Changed file paths drop into three bins: hot/ and tests/ go to HOT, site file settings go to RESTART, archive/ and build settings go to REBUILD. REBUILD carries a backup reference and a window.
The mistake: Deploy a Migration Manager package from a 9.1 DEV into a 9.2 PROD halfway through an upgrade. Do this instead: Migration Manager is for environments at the same release level. Upgrade the target first, or rebuild the package on a source at the same version.
Lesson 6
Who does what in a Maximo project
A Maximo change passes through many hands. Knowing who does what tells you who to ask, who signs off and who will call you when it breaks.
| Role | What they do | What they need from you |
|---|---|---|
| Business owner | Asset manager or maintenance manager who wants the change and pays for it | A clear answer on what it will do and when |
| Functional consultant or business analyst | Turns "planners need X" into a written requirement and test cases | Questions early; a demo in DEV |
| Maximo administrator | Users, security groups, system properties, cron tasks, Migration Manager deploys, admin mode | A package and clear deployment steps |
| Maximo developer | Configuration, automation scripts, Java when needed | You, most days |
| Integration developer | Object structures, channels, endpoints, the other system's side | Message samples and error handling |
| Report developer | BIRT reports and KPIs | The fields and relationships the report needs |
| Platform engineer | OpenShift, the ManageWorkspace, databases, backups, certificates (on MAS) | Archive versions, rebuild windows, resource needs |
| Testers and UAT users | Run the test cases and say yes or no | A working TEST and UAT, and known test data |
| Change manager or CAB | The change advisory board approves PROD windows | Risk, rollback plan, backup reference |
Maximo in the middle, with seven people around it: planner, supervisor, technician with a phone, storeroom clerk, buyer, reliability engineer and administrator, each with one line on what they do.
How a change flows through them. The business owner asks. The analyst writes it down with acceptance criteria. You build it in DEV, on the lightest layer, and package it as you go. Testers check it in TEST, users accept it in UAT, the administrator rehearses the deployment in PRE-PROD, and the change board approves the PROD window. After go-live, someone checks it in PROD and closes the change.
The mistake: Hand over a change with "it is in DEV, should be fine". Do this instead: Hand over the package, the steps, the test cases and the evidence each passed. The administrator deploys what you give them, not what you meant.
Remember: Write every change so someone else can deploy it at 10 pm without calling you.
Real practice on the Maximo SIM
Tasks you do by hand on the training Maximo, with the evidence your trainer checks.
- Change DEV, prove UAT and PROD are untouched (DEV). Environments are separate copies. A change made in DEV exists nowhere else until it is moved on purpose.
- Read a screen in Application Designer (DEV). Most screen changes are configuration, not code. Learn where a field on a screen comes from.
Check yourself: the Level 7 quiz
16 questions. Pass mark 70%.
- A planner wants a new field on the work order screen. Which layer do you try first?
- Configuration: Database Configuration and Application Designer
- Custom Java
- Direct SQL
- A new mobile app
- Look at the lit layer. What does a change on this layer need before it can ship? (picture: The layers of change)
- Nothing, it is live as you type
- A Migration Manager package only
- A build: an EAR rebuild on 7.6.1, a customisation archive and image rebuild on MAS
- An email to IBM
- Which change needs Manage to be rebuilt?
- A new domain value
- A new saved query
- A change to a workflow process
- A custom Java class
- Which picture shows how configuration such as screens, domains and scripts moves between environments?
- Picture A
- Picture B
- Picture C
- What runs DBC scripts in order and records the last one it ran?
- The browser
- The database update tool, updatedb
- Workflow
- The REST API
- What is the difference between a snapshot package and a change package in Migration Manager?
- None
- Snapshots are for data, change packages for Java
- A snapshot takes configuration as it is now; a change package records inserts, updates and deletes made after it is turned on
- Change packages work across versions
- Look at the picture. A planner sees "AWAITPARTS" on screen. Which value should a script compare against? (picture: Synonym domains)
- The internal value, WMATL
- AWAITPARTS
- Whatever the planner typed
- The domain description
- An administrator turns admin mode on to apply a structure change and forgets to turn it off. What does IBM warn will happen?
- Nothing
- All users become administrators
- The database is deleted
- Cron tasks fail
- Look at the picture. Where is the change package stopped? (picture: From DEV to PROD)
- At the DEV gate
- At the TEST gate, waiting for checks and sign-off
- Already in PROD
- It skipped every gate
- Someone fixes a domain value directly in PROD. Three weeks later the fix disappears. What most likely happened?
- A later release moved the old value up from DEV, where it was never fixed
- IBM reverted it
- The database ran out of space
- Cron tasks deleted it
- You need 5,000 assets from a spreadsheet in PROD. How should they travel?
- Type them in one by one
- A DBC script
- A data load, for example with the Data Workbench, checked and reconciled
- A Java class
- Which layer does the picture warn about, the one that skips every business rule? (picture: Every change goes through the rules)
- The REST API
- Integrations
- Automation scripts
- Direct SQL
- Which tool changes what a technician sees in Maximo Mobile?
- BIRT
- The Maximo Application Framework (Graphite) application configuration tools
- Migration Manager
- updatedb
- Your team is halfway through an upgrade: DEV is on 9.2, PROD is on 9.1. Can you deploy a Migration Manager package from DEV to PROD?
- Yes, always
- Only on Fridays
- No: Migration Manager is for environments at the same release level
- Only for Java
- Look at the picture. Which path does mxR sort into REBUILD? (picture: The path rule sorts every change)
- archive/java/MyWO.java
- hot/scripts/WOGATE.yaml
- tests/smoke.yaml
- jobplans/default.yaml
- Who approves a PROD release window?
- The newest developer
- The BIRT report
- Nobody
- The change manager or change advisory board
Remember it as a picture
- The layers of change: Configuration, scripts, integration, reports and mobile, then Java. Pick the highest layer that does the job.
- Configuration first: Database Configuration, Domains, Application Designer, conditions, workflow: records that upgrade with the product.
- Java MBO customisation: Extends classes such as psdi.app.workorder.WO. Needs a rebuild and a recompile on upgrades.
- Database Configuration: Objects and attributes. Save stores changes as pending; Apply Configuration Changes builds them.
- Synonym domain: Your word on screen, Maximo's internal value underneath. Scripts compare the internal value.
- Environments: DEV, TEST, UAT, PRE-PROD, PROD. Every change starts in DEV and moves up through gates.
- Migration Manager: Define, create and distribute a package in the source; deploy it in the target. Same release level only.
- DBC script and updatedb: Maximo's XML database statements. updatedb runs them in version order, once per database.
- Archive and rebuild: 7.6.1: rebuild the EAR. MAS: customisation archive, operator builds images, updatedb runs, pods roll.
- Data loads: Assets, locations, items: data travels through the business rules, checked, previewed and reconciled.
- No direct SQL: SQL skips the business rules, status history and integration events. Use the app, REST or a data load.
- The administrator: Deploys your package. Give them the package, the steps and the test evidence.
- mxR path rule: hot/ is HOT, site settings are RESTART, archive/ is REBUILD. The diff decides how a change ships.
Where these facts come from
- IBM Docs: Migration Manager application
- IBM Docs: Configuring the database in administration mode
- IBM Docs: Customization archive guidelines
- IBM Docs: Migrating customizations using customization archives
- IBM Docs: What's new in Maximo Manage 9.2 (BIRT 4.21, Java 25)
- IBM Docs: Maximo Application Framework Configuration application
- Assetize record: Migration Manager does not support packages from different versions of Manage
- Assetize record: Migration Manager APIs
Try it on the real tools
How did Level 7 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.