Assetize

Learning Lab

Learning Lab · Picture memory

Learn it as pictures, test it as pictures.

Every picture card from every level in one deck. See the picture, say what it is, flip it. Test me shuffles the deck and keeps score.

Level 0: Start here

  • Enterprise asset management (EAM): Looking after physical assets: raise work, approve and plan it, do it, record it, learn from the history. Maximo is IBM's EAM system.
  • Asset and location: An asset is the thing (boiler feed pump B). A location is the place (the boiler room). They are separate records.
  • History moves with the asset: When a pump moves, its own repair history goes with it. The location keeps the history of work done at that spot.
  • Preventive maintenance (PM): Work on a schedule, before something breaks. A PM record makes a new work order each time it falls due.
  • Classic Maximo 7.6.1: One Java application on WebSphere. Regular support ended 30 September 2025; Dual Support ends 30 April 2027.
  • Maximo Application Suite and Manage: MAS runs as containers on Red Hat OpenShift. Manage is the application inside it that does the classic Maximo work.
  • The support clock: IBM's support dates drive upgrades: 7.6.1 regular support ended 30 September 2025, MAS 8.x is Extended Support only since 1 May 2026.
  • Technician and Maximo Mobile: The technician does the work and records hours, parts and the failure, often in Maximo Mobile on a phone or tablet.
  • The people around Maximo: Planner, supervisor, technician, storeroom clerk, buyer, reliability engineer and administrator: one system, seven views.
  • Assetize: An evidence base of source-backed Maximo records, free tools and ASK on top, and three products that work on a customer's Maximo.
  • AI at build time, facts at run time: AI helps build and check records. Answers are built from stored facts and ranked records; no AI model decides them.
  • mxH: Your Maximo upgrade is a diff. mxH shows which IBM changes touch your own customisations.
  • mxR: Ship Maximo changes the way Maximo ships work: each change is a work order, deployed and tested one site at a time.
  • Data Workbench and Workbench 3: Map a spreadsheet to Maximo, check it, see exactly what will change, load it, and prove what landed.

Level 1: How software talks

  • Request and response: A client sends a method, an address, headers and maybe a body. The server answers with a status code and a body.
  • POST with a body: Creates something new. In Maximo, a POST to the object structure with JSON creates a record and answers 201.
  • 200 OK: It worked. The data is in the body.
  • 401 Unauthorized: You did not prove who you are: no API key, or a wrong one. Maximo never answers an anonymous call with data.
  • 403 Forbidden: The server knows who you are, but you may not do this. Fix it with permissions, not with a new key.
  • 429 Too Many Requests: Slow down. Wait, then retry, waiting longer each time with a little randomness.
  • JSON: Text data with six kinds of value. Curly brackets: an object. Square brackets: a list. Maximo puts records in member.
  • curl: A command-line tool that sends HTTP requests. -H adds a header, -d sends a body, -i shows the status line.
  • API key: A secret tied to one Maximo user, sent as the apikey header. Calls run with that user's permissions.
  • Keep keys out of code: Keys live in an environment variable or a secret store. If one leaks, revoke it and make a new one.
  • Idempotent: Safe to send twice: the second request leaves the system exactly as the first one did.
  • oslc.select, oslc.where, oslc.pageSize: Choose the fields, filter the rows on the server, and set how many come back per page.
  • Object structure: A named bundle of Maximo objects the API serves, such as MXAPIWODETAIL: a work order with its tasks, labour and materials.

Level 2: Maximo for beginners

  • Organisation and site: An organisation shares money settings and vendors; sites are plants or depots. Assets, locations and work orders belong to one site.
  • Location: A place: where assets work (OPERATING), where stock is kept (STOREROOM), workshops (REPAIR) and more.
  • Moving an asset: Moving records an asset-move transaction. The asset keeps its number and its whole history.
  • Work order: Maximo's record of one job: what, on what, how urgent, who, when, with what, and what really happened.
  • WAPPR: Waiting for approval. The default status for work orders created in Work Order Tracking.
  • No cancelling once work starts: IBM: you cannot cancel a work order once work is in progress or actuals are reported.
  • COMP to CLOSE: From COMP the only move is CLOSE. A closed work order is a history record.
  • Synonym status: A customer's own status word maps to IBM's internal value. The rules work on the internal value.
  • PM: A template for scheduled work. An ACTIVE PM raises a work order each time it falls due.
  • Job plan: The recipe: tasks, labour, materials and tools for a kind of job, copied onto each work order.
  • Current and available balance: Current: everything on the shelf. Available: current minus reserved minus expired.
  • Purchase requisition (PR): "We need this." Internal: transfer from another storeroom. External: buy from a vendor.
  • Purchase order (PO): A commitment to one vendor, at a price, by a date. It waits for approval before it goes out.
  • Invoice matching: The invoice is matched against the purchase order and the receipts before it is approved for payment.

Level 3: Habits of a good developer

  • Commit: A snapshot of the project with your name, your message and a pointer to its parent. Its ID is a 40-character checksum.
  • Branch: A movable label pointing at a commit: a 41-byte file. Work on a branch, never straight on main.
  • Pull request: A proposal to merge your branch into main: the diff, the checks and the review, in one place.
  • A red check: Keeps the merge button grey until the cause is fixed. Read it; never delete the test to make it pass.
  • Merge conflict: Two branches changed the same lines. Write the final version, delete the markers, git add, git commit.
  • Small changes: About 100 lines is usually a good review; 1,000 is usually too many. One self-contained step at a time.
  • KISS: Keep it simple: the simplest design that does the job is the one people can read and fix.
  • DRY: Do not repeat yourself: one source for each fact, read by every place that needs it.
  • YAGNI: You aren't gonna need it: build features when they are needed. It never excuses skipping tests or tidy code.
  • Single responsibility: Each part does one job and has one reason to change. On our site: one page, one intent.
  • Fail closed: When unsure, stop and say why. Never guess and carry on.
  • Idempotent: Twice has the same effect as once. Make creates safe to retry by looking the record up first.
  • A committed secret: Git keeps it in history and every clone. Revoke or rotate the key first, then clean up.
  • Environment variable: A named value the running program reads, such as MAXIMO_APIKEY. The code holds the name, never the value.

Level 4: How Maximo stores data

  • MBO: Maximo Business Object: the Java layer that checks rules and writes history before anything reaches the database.
  • Never write SQL to Maximo: It skips checks, status history, security and mobile sync. Read with SQL if you must; write through the business layer.
  • Object and attribute: An object is a kind of record (WORKORDER); attributes are its fields (WONUM, STATUS, SITEID).
  • Nonpersistent attribute: No column; computed when read. CURBALTOTAL and AVBLBALANCE can be read, not filtered.
  • Domain: The allowed values for an attribute. STATUS on WORKORDER uses WOSTATUS.
  • Synonym domain: Your words mapped onto internal values. Users see AWAITPARTS; the rules see WMATL.
  • WPCOND means APPR: A synonym of APPR. Code must compare internal values, or it misses every synonym.
  • Relationship: A named where clause from parent to child: ASSET is assetnum = :assetnum and siteid=:siteid.
  • SITEID: Work orders, assets, locations, PMs and balances belong to one site. Keys are unique only within it.
  • Organisation and site: An organisation keeps one base currency; its sites track their own work and inventory.
  • "I cannot see that record": First question: which site is it on, and do this user's security groups grant it?
  • Object structure: A named bundle of related objects that programs read and write. MXAPIWODETAIL: work orders with plans.
  • MXAPI object structures: The ones IBM ships for the REST API: MXAPIWODETAIL, MXAPIASSET, MXAPIINVENTORY, MXAPIPM and more.

Level 5: The Maximo REST API

  • /maximo/api/os/<object structure>: Every REST call: the Manage application, the REST route, "object structure", then its name.
  • apikey header: One Maximo user's key, sent as a header, read from an environment variable. Runs with that user's access.
  • lean=1: Plain JSON names (wonum, member) instead of prefixed OSLC names. Put it on every call.
  • oslc.select: The fields to return. Braces for child lists, a dot for relationships: wplabor{craft}, asset.description.
  • oslc.where: Filter inside Maximo. Text and dates in quotes, numbers bare, and for lists, in [..]. Persistent fields only.
  • oslc.pageSize and nextPage: Small pages, then follow responseInfo.nextPage.href until there is none.
  • POST and properties: POST to the collection creates: 201 and a Location. properties: wonum,status,href sends fields back.
  • x-method-override: PATCH: POST to the record's href with this header to update it. Send only what changes.
  • patchtype: MERGE: Without it, a PATCH deletes child rows you did not send, like Sync. With it, it behaves like AddChange.
  • If-Match and 412: Send the ETag you read. 412 Precondition Failed means someone changed the record first: read again.
  • Actions: ?action=wsmethod:<name> on a record href, with x-method-override: PATCH. Workflows use workflow:<name>.
  • The rules guard the API too: Started work cannot be cancelled: INPRG to CAN is refused with a 400 that says why. Read it; never assume success.
  • BMXAA error: reasonCode, message, statusCode and a moreInfo link. Read the words twice, then look the code up.
  • Retry only 429 and 503: Wait longer each time, with a little randomness. Fix a 4xx instead of resending it.

Level 6: Versions and MAS

  • Classic Maximo 7.6.1: One EAR on WebSphere, built in the SMP folder. Regular support ended 30 September 2025.
  • Maximo Application Suite: A core (users, login, AppPoints) and applications such as Manage, running as pods on Red Hat OpenShift.
  • Manage: The MAS application that does the classic Maximo work, with the same MBO business rules underneath.
  • Operator and ManageWorkspace: The Manage operator reads the ManageWorkspace custom resource and changes pods until reality matches it.
  • Customisation archive: A zip that mirrors SMP/maximo. The operator builds it into new images and updatedb runs its DBC scripts.
  • maxauth: The 7.6.1 native login header: user:password in base64. Easy to read back, and refused by the MAS API.
  • API key: How programs call MAS: an apikey header tied to one Maximo user and that user's security groups.
  • 401 after go-live: The classic sign of an integration still sending maxauth to MAS. Test every caller's login in rehearsal.
  • Every fact has a version: An upgrade is the overlap of what IBM changed and what you customised. Name both versions before you answer.
  • The support clock: 7.6.1 regular support ended 30 Sep 2025. Dual Support ends 30 Apr 2027. MAS 9.0 moves to Extended Support from 1 Jul 2027.
  • Know the route: n-1: Step one of every upgrade. IBM moves one release line at a time: 8.11 to 9.0, 9.0 to 9.1, 9.1 to 9.2.
  • Where the API key lives: In a secret store or environment variable only the running integration reads. Never in code, never in a URL.

Level 7: How Maximo software is built

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

Level 8: Scripts and integrations

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

Level 9: Testing you can trust

  • Unit test: One small piece of code, checked on its own in milliseconds. Most of your tests live in this wide base.
  • UI / end-to-end test: A real browser walks a user journey. Realistic and slow, so keep a few for the journeys that matter.
  • Stub: Gives "canned answers to calls made during the test", and asks no questions back.
  • Mock: Answers like a stub and also verifies the calls: was save() called once, with these values?
  • Why not the real Maximo?: Slow to get, shared with other teams, full of data you must not change, and on one release only.
  • Lens: The release line a stub answers as: 761, mas811, mas90, mas91 or mas92. MAS lenses take an API key only.
  • Script Test Harness: Runs a launch point script against a mocked Mbo per release: passes, breaks, or skipped. No server needed.
  • Backoff with jitter: After each failure, wait longer, with a little randomness, and stop after a set number of tries.
  • 429 Too Many Requests: Rate limiting: slow down. Read Retry-After if it is there, then back off.
  • Idempotent write: Doing it twice has the same effect as once. In Maximo REST, x-method-override: SYNC is an upsert.
  • Flaky is a symptom: A test that passes only on retry has a real cause: timing, shared data, order, environment or a real bug.
  • Golden baseline: A saved known-good copy. Later runs are compared with it, and any difference is named.
  • A red check is a shut door: The merge stays blocked until the cause is fixed. Never switch a gate off to get past it.

Level 10: CI/CD/CT and mxR

  • Continuous integration: Merge small changes often; every change is built and tested automatically.
  • Continuous delivery: Every passing change is ready to ship. A person presses release.
  • Continuous deployment: Every passing change goes to production on its own, with no approval step.
  • Continuous testing: Tests run at every stage, and a failing gate stops the change.
  • Gate: A stage that can stop the change. Fast gates first, so mistakes are caught in seconds.
  • Why runners need teaching: Each kind of Maximo change moves its own way. A runner sees files; mxR knows the lanes.
  • mxR work order: Every change is a work order: WAPPR, APPR, INPRG, COMP, or CAN. It lives in Git, not in Maximo.
  • HOT: hot/, tests/, jobplans/: applied through the API in a fixed order while Manage runs. Minutes.
  • REBUILD: archive/ or build keys: a customisation archive and a rebuild, behind a backup reference, a window and an approval.
  • RESTART: A site-file key such as JVM options: merged into the ManageWorkspace, and the operator rolls the pods until Ready.
  • MXR.AGENT: One Jython script per site. Runs as the caller, writes only hot artefact tables, one audit line per call.
  • Job plan and golden screens: The pipeline as data. Golden screens check every touched screen still opens with its title, toolbar and tabs.
  • Promotion: The same work order and the same commit, started on the next site, through that site's gates.
  • Failure code and runbook: CAN carries one code, such as TEST/GATE, and prints its runbook: fix forward, resume or revert.

Level 11: Assetize from the inside

  • Assetize: A base of source-backed Maximo records, with free tools, ASK, mxH, mxR and the Data Workbench on top.
  • IBM official: IBM documentation and support pages: the strongest evidence a record can carry.
  • Practitioner evidence: Approved named experts. Strong, and always under its own label, never as IBM.
  • Community: Forums and user groups: a lead to check, carrying the least weight.
  • Versions on every fact: Every record and every date belongs to a release. Read the Versions line first.
  • One name, many releases: 7.6.1 on WebSphere, MAS 8 and 9 on OpenShift. A fact without its version could belong to either.
  • AI at build time: AI helps shape records at build time. At run time, answers come from typed facts and ranked records.
  • ASK and MCP: Cited answers with [R#] markers, or a decline. The same tools reach AI assistants through assetize.com.au/mcp.
  • Compare and the Upgrade Desk: "What changes between two releases?" A cited report, a staged plan and a checklist.
  • The Workbench: "How do we load this sheet?" Map, check, preview, load and reconcile.
  • site-map.ts: The one registry: header, footer, directory, docs, tour and the Worker's pages all read it.
  • Fail closed: When unsure, the gate shuts: no guessed facts, no guessed stub answers, no guard test edited to pass.
  • Merge and deploy yourself: Local checks pass, you merge, you run scripts/deploy-production.sh, you prove the deploy.
  • Any failure you find, you fix: Reproduce, fix the cause, rerun, report. Even when you did not cause it.

Level 12: mxH: upgrade intelligence

  • Your upgrade is a diff: mxH reports only where IBM's changes between two releases touch the customer's own lines.
  • BLOCKING: Will not compile, will not load, or throws on first use. Fix before cutover.
  • REVIEW: A real difference whose consequence depends on what the code does with it. A person reads the line.
  • ENVIRONMENT: Differs between the two systems, not because of the release. Confirm it on the target itself.
  • NOT ASSESSED: Stated on every report, so a clean result means exactly what was checked.
  • A1: IBM upgrade-script stated: State it as what the release does, and name the script.
  • A2: bytecode or API confirmed: The type or member is gone at the target release. Check inheritance first.
  • A3: target registry confirmed: The target does not accept it; name the registry. Do not generalise to the product.
  • B1: dictionary observed and corroborated: A release change, naming the dictionary difference and the IBM script that corroborates it.
  • B2: dictionary observed only: Say "between these two dictionaries", and name both. Never "IBM changed".
  • C: modelled behaviour: Credit it to the model and link its assumptions. Never present it as measured.
  • Custom Java at upgrade: Rebuild against the target classes (Java 17 from 9.1; 9.2 supports Java 25) and ship it in a customisation archive.
  • mxH in the upgrade: Step 2, find what breaks: a graded fix list with owners and closure tests.
  • Why launch points matter: A script with unchanged code still breaks when the field its launch point watches is gone.

Level 13: The Data Workbench

  • A load you can prove: Connect, pick, map, check, preview, load, read each row, reconcile.
  • AddChange: Adds new records and updates existing ones; children missing from the file stay.
  • Sync: Adds, updates, and removes child records missing from the file. Turn it on and confirm.
  • Delete: Removes the records named by their key. Only after reading the preview.
  • Reconcile: Read the records back from Maximo and compare them with what you meant to load.
  • Safe retry: Committed rows are sent once; retry sends only the rows that failed.
  • Preview: Every create, change and delete is listed before anything is written.
  • Row results: A tick, or Maximo's own BMXAA message, on every row next to its key.
  • Add your Maximo: The address and an API key; the key stays in the workspace credential store.
  • Environment file: assetize-environment/1 moves a connection between tools. Keys never go in the file.
  • Approval and cutover: A package that needs approval runs only once its exact plan is approved.
  • Loads go through the rules: Every row passes Maximo's business rules, so bad rows are refused, never written around.
  • A refused row: HTTP status, BMXAA reason code and the message: fix the row it names.

Level 14: Put it together

  • Step 1: understand the move: Compare and the Upgrade Desk: what IBM changed, the dates, the route and the checklist.
  • Step 2: find what breaks: mxH: which of IBM's changes touch the customer's own lines, with owners and closure tests.
  • Step 3: fix: Open the finding in the Studio; test scripts in the Script Test Harness; scripts before Java.
  • Step 4: build the pipeline: mxR: every change a work order, a tier from the path rule, DEV then TEST then PROD.
  • Step 5: test: Unit, API, integration, UI and golden screens in the job plan; a failing gate stops the change.
  • Step 6: load the data: A Workbench campaign, rehearsed until it is boring, cut over after approval.
  • Step 7: go live and prove it: Smoke tests, reconcile, verify-closure, sign-off, and the classic system retired.
  • The clock: 7.6.1.x regular support ended 30 September 2025; Dual Support ends 30 April 2027.
  • Classic to Manage: A MAS install plus a migration, not an in-place upgrade. Integrity Checker first.
  • Logins at MAS: Programs use an API key for their own integration user; maxauth gets 401.
  • REBUILD: A change under archive/: backup reference and window before approval.
  • Cutover: PROD is the last gate: written go or no-go criteria, then sign-off on the proof.