Level 13 · 15 levels · Builder · about 75 minutes
Level 13 — The Data Workbench and Workbench 3: load data you can prove
By the end: Say why data loads go wrong, run a load from sheet to Maximo in Workbench 3, choose AddChange, Sync or Delete with care, read row results, retry safely, reconcile what landed, and explain how campaigns, approvals, environment files and the Studio fit together.
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.
Lesson 1
Why data loads go wrong
Every Maximo project loads data. A new Maximo needs its organisations and sites, then locations, then assets, then preventive maintenance records (PMs), job plans, items, storerooms and people. An upgrade moves data too, and every year someone loads a few thousand meter readings or a new set of assets bought with a new plant. Almost all of it arrives in spreadsheets, because that is how the business keeps its lists.
A data load is not a copy into a table. Maximo loads through its object structures, the same bundles of objects the REST API uses (Level 4 and Level 5). Every row goes through the business rules: the MBO layer checks the site exists, the status is allowed, the asset number is unique, the required fields are filled. That is good. It means bad rows are refused instead of quietly corrupting the system. It also means a sheet that looks fine in Excel can fail row after row.
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 load goes wrong | What you see | What stops it |
|---|---|---|
| A column mapped to the wrong field | Data in the wrong place, or refused | Columns matched to the object structure's own fields, with unmatched columns listed |
| A value not in the domain (ACTVE instead of ACTIVE) | The row is refused with a BMXAA message | Cell checks against the allowed values before anything is sent |
| A date or number in the wrong format (31/02, 1,200.00) | Refused or misread | Format fixes: dates to YYYY-MM-DD, numbers without separators |
| A child loaded before its parent (an asset before its location) | The row is refused because the parent does not exist yet | A load order: locations before assets, assets before PMs |
| Rows loaded twice | Duplicate records, or the same change applied twice | Committed rows are sent once; retry sends only the failed rows |
| Nobody knows which rows landed | Arguments, re-loads, and a register nobody trusts | Per-row results, and reconcile against Maximo |
For years the common tool has been MXLoader, an Excel workbook by Bruno Portaluri. In its author's words, it "allows to quickly and easily query and load data into IBM Maximo" and "brings together the power of the Maximo Integration Framework and the flexibility of Excel". Its newer versions talk to Maximo over REST, which is what MAS Manage expects. Many teams have years of MXLoader workbooks, so any tool that replaces it has to read them.
The mistake: Load straight into the database with SQL because it is faster. Do this instead: Load through the object structures, so every row goes through Maximo's business rules, audit and record versions. Speed comes from bulk calls, which IBM recommends for REST-based import, not from going around the rules.
Remember: A load is finished when you can prove what landed, not when the progress bar ends.
Lesson 2
The Data Workbench: a grid that knows Maximo
The Assetize Data Workbench is a web app at /workbench. Its own one-line job: "Get Maximo data right before Maximo sees it. Bring a spreadsheet, fix it in a grid that knows Maximo, check the request, rehearse the load, retry only what failed." Home has one job too: Load data into Maximo. You drop an .xlsx or .csv file, and the Workbench works out the object structure, maps the columns and opens the grid.
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 Grid Editor is the heart of it. The sheet looks like Excel, but every column is matched to a Maximo field, and every cell is checked: type, length, required, allowed values and the rules for your Maximo version. A red cell tells you what is wrong and what is allowed. Above the sheet, a problem list names each problem with its row, column, value and what is expected, with Go to cell. A required field that is not mapped, such as SITEID, is a link that takes you to the column that should hold it.
| Grid feature | What it does for you |
|---|---|
| Fix problems | Rewrites formats only: hidden characters, dates to YYYY-MM-DD, Yes and No to 1 and 0, numbers without separators or currency signs. A value like ACTVE stays red for you to decide. |
| One button | Check until this exact sheet passes, then Load (Run simulation on the simulator). A load into a live Maximo asks you to type its host first. |
| Result column | Frozen beside the row numbers, as in MXLoader: a tick for a row that passed or loaded, or Maximo's message with its BMXAA code. |
| Action | AddChange by default, or Add, Update or Delete, sent with each record as _action in Maximo's own words: Add, Change, Delete. |
| Get from Maximo | MXLoader's Query: a where clause such as siteid="BEDFORD" and status="OPERATING" reads up to 5,000 rows into a new sheet with the keys locked. |
| Big sheets | Over 500 rows, Check and Load use Maximo's async import and fill each row's result as it comes back. |
| Export | Writes an MxLoader workbook back, with a RESULT column holding each row's last answer. |
A Maximo error answer with its parts labelled: the HTTP status 400, the reason code starting with BMXAA, the message in words, and the extended error link.
The Workbench also knows the order things must go in. The Load Plan sets which sheet loads first and checks parents exist: locations before assets, assets before PMs. Version Setup asks which Maximo you are loading into, so checks use that version's rules. A Migration mode compares a source version with a target, for example 7.6.1.3 to 9.x, and scores what breaks in the objects you choose.
Before a single request leaves, Preview shows it: which sheet, how many rows, where it goes (Simulator, or Live with the host name), and under Technical details the URL, the headers with secrets masked, and the body. Runs can go to a simulator inside the Workbench, which answers like Maximo and writes nothing, so a whole load can be rehearsed with fictional data. Three profiles change the words, not the task: Data loader (plain words), Maximo admin (sites, organisations and security), Maximo developer (Maximo's own names, requests and payloads).
An MxLoader workbook, as the Workbench reads and writes it (sample data)
Row 1 object structure and action MXAPIASSET AddChange
Row 4 attribute headers ASSETNUM SITEID DESCRIPTION LOCATION STATUS
Row 5+ data P-1001 BEDFORD Feed pump 1 BR-PLANT OPERATING
Child columns are written CHILD.FIELD; a blank parent cell continues the record above.The mistake: Press Load on a sheet you have not checked, and read the errors afterwards. Do this instead: Press Check first. It runs Maximo's preview and writes nothing. Fix the rows the Result column names, Check again, and only then Load.
Remember: Check is free; Load is not. Check until the sheet is clean, then load once.
Lesson 3
Workbench 3, step by step
Workbench 3, at /workbench3, puts the whole job into three steps. Its own line: "Map a spreadsheet to Maximo, check it, see exactly what will change, load it, and prove what landed." Walk through it as if you were loading 400 new pumps for a water plant (sample data).
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.
Step 1, Add your Maximo. You paste the address of the Maximo and an API key. In MAS, an API key is created for a given Maximo user, and every call made with it runs as that user, with that user's security. The key stays in the workspace credential store. It never goes into a package or a file. If a colleague already set the connection up, you import an environment file instead, then add the key yourself.
A request walks up to a locked Maximo door. Without a key it bounces back with 401. A valid key for a user without permission gets past the door and stops at the security gate with 403. A good key with the right access gets 200 and the records.
Step 2, Pick what to load. Choose the object structure, for example MXAPIASSET. Download its Excel template if you are starting fresh, or upload what you have: Excel, CSV or an MxLoader workbook. The columns are matched for you, and any column that does not match is shown, so nothing is dropped in silence. You can also go the other way: query Maximo into a worksheet. A query copies rows into the sheet and leaves Maximo as it is. You edit the copy and load the changes back.
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.
Step 3, Check, run and reconcile. Checks run in seconds. Where a fix is safe, such as a date format, it is one click. The preview then lists every create, change and delete before anything is written. Delete and Sync run only when you turn them on and confirm. You run the load and read the result for every row. If some rows fail, you fix them and retry the failed rows: committed rows are sent once. Finally you reconcile: the records are read back from Maximo and compared with what you meant to load.
- Add your Maximo
- Pick what to load
- Map columns
- Check and fix
- Preview every change
- Load
- Row results and retry
- Reconcile
Workbench 3 from sheet to proof
| Step | What you do | What you get |
|---|---|---|
| 1. Add your Maximo | Address and API key, or import an environment file | A connection; the key held in the workspace credential store |
| 2. Pick what to load | Object structure, template, upload (Excel, CSV, MxLoader) or query Maximo into a sheet | A sheet with columns matched to Maximo fields |
| 3. Check, run and reconcile | Checks and one-click fixes, preview, load, retry failed rows, reconcile | Every row's result, and proof of what landed |
The mistake: Type the API key into a column of the spreadsheet, or into a shared environment file, so the next person can use it. Do this instead: Keep the key in the workspace credential store. Share the environment file, which never holds a key, and let each person add their own key.
Remember: Three steps, one rule each: connect with a key you never share, pick the object structure before you map, and never load what you have not previewed.
Lesson 4
AddChange, Sync and Delete: choose the action with care
Every load has an action: what Maximo should do with each record in the sheet. The action matters most when a record has children. An asset can have spare parts. A job plan has tasks, labour and materials. A work order has planned labour and materials. The question is always: what happens to the child rows on the target that your sheet does not mention?
The same sheet loaded three ways onto a record with child rows. AddChange adds and updates. Sync adds and updates and also removes the child rows missing from the sheet. Delete removes the records.
| Action in Workbench 3 | What it does | Children missing from the file | Take care |
|---|---|---|---|
| AddChange | Adds new records and updates existing ones | Left as they are | The everyday choice |
| Sync | Adds and updates, and also removes child records on the target that are missing from the file | Removed | Runs only when you turn it on and confirm |
| Delete | Removes the records | Removed with their parent | Runs only when you turn it on and confirm, after the preview |
The same sheet loaded three ways onto a record with child rows. AddChange adds and updates. Sync adds and updates and also removes the child rows missing from the sheet. Delete removes the records.
This is not an Assetize invention. IBM's integration framework has the same idea. Its action domain, INTACTION, holds Add, AddChange, Change, Delete and Replace. IBM's Integration Guide says AddChange "adds or updates existing records" and "existing child records that are not specified in the inbound message are not deleted". For Replace it says "any existing child record that is not explicitly mentioned in the message is deleted". Workbench 3's Sync is the action that removes missing children; IBM's word for that behaviour is Replace.
Watch the words, because the same word means different things in different tools. In MXLoader, Sync is the name of the load operation, and the action (such as Add, Change, AddChange, Replace or Delete) is chosen beside it. In the Data Workbench grid the actions are AddChange, Add, Update and Delete, and Update is sent to Maximo as Change. In Workbench 3, Sync is an action that also removes children missing from the file. When a customer says "we'll just sync it", ask which one they mean.
The same sheet loaded three ways onto a record with child rows. AddChange adds and updates. Sync adds and updates and also removes the child rows missing from the sheet. Delete removes the records.
The mistake: Pick Sync because it sounds like "make Maximo match my sheet", on a sheet that only carries the fields you wanted to change. Do this instead: Use AddChange to add and update. Use Sync only when the sheet holds the complete set of children you want to keep, and read the delete lines in the preview before you confirm.
Remember: AddChange adds and updates. Sync also removes children missing from the file. Delete removes. Only the first is safe without a second look.
Lesson 5
Preview, row results and safe retry
A preview is the list of what the load will do, row by row, before it does it. In Workbench 3 it lists every create, change and delete before anything is written. This is your last cheap moment. A wrong column found in the preview costs a minute. The same mistake found after the load costs a clean-up project.
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.
Then you load, and every row gets its own result. A row that loaded gets a tick. A row Maximo refused gets Maximo's own message with its BMXAA code, next to the record's key. In the Data Workbench Run Console, when more than five rows share a message, they collapse to one line, for example "79 rows · BMXAA4195E · A value is required…", with Show rows to open them. Seventy-nine copies of one error are one problem, not seventy-nine.
Row results after a half-finished load (sample data)
ASSETNUM SITEID RESULT
P-1001 BEDFORD ✓
P-1002 BEDFORD ✓
P-1003 BEDFORD BMXAA4195E - A value is required for the Organization field on the ...
P-1004 BEDFORD ✓
P-1005 BEDFORD (not sent yet: the connection dropped here)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.
Now the connection drops halfway, or ten rows fail. What do you do? You retry. The Workbench's rule is that committed rows are sent once. Retry failed sends only the rows whose last answer was a failure, fixed or not, and their results update in place. A failed batch in the Load Plan offers Retry only the failed rows, as a preview first. Queueing the same plan again asks before it runs. This is the idea of idempotence from Level 3: pressing the button twice must give one result, not two.
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.
Why does the Workbench need to remember? Because Maximo cannot tell your retry from a new request. If a row's key is blank and Maximo numbers it (the Workbench lets you put NEW or leave the number blank, and Maximo gives the record its next number), sending that row again makes a second record with a second number. Only the tool that sent the row knows it was already committed. That memory is what makes a retry safe.
The mistake: A load stopped halfway, so start it again from row 1. Do this instead: Retry the failed rows only. Committed rows are sent once, so nothing is duplicated, and rows that never ran are sent for the first time.
Remember: A good load can always answer three questions for any row: was it sent, what did Maximo say, and is it safe to send again?
Lesson 6
Reconcile, approvals and campaigns: proving a go-live
A green result column says Maximo accepted each row. It does not yet prove the register is right. A business rule may have changed a value on save. Another person may have edited the record afterwards. A default may have filled a field you left blank. Reconcile closes that gap: the records are read back from Maximo and compared, row by row and field by field, with what you meant to load.
The rows you meant to load sit next to the records read back from Maximo. Matching rows tick green; one row that differs is flagged amber, with the field that differs.
Reconcile turns "I think it worked" into evidence you can hand to someone else. A go-live sign-off is far easier when the data owner sees "4,212 rows meant, 4,212 read back, 4,211 match, 1 differs on LOCATION" than when they are told the load ran without errors.
Some loads are too important to run on one person's say-so. In Workbench 3 a package can require approval. A package that requires approval runs only once its exact plan is approved. The word exact matters: if anyone changes the sheet after approval, the plan has changed, so the approval no longer covers it. The Data Workbench uses the same idea for review: a reviewer reads the evidence pack and matches its fingerprint to the fingerprint on the request, because a review of one snapshot does not cover a later edit.
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.
A go-live is never one load. It is a sequence: organisations and sites, then locations, then assets, then job plans, then the PMs that use them, then open work. Workbench 3 groups loads into a campaign: a go-live sequence with rehearsals and cutover sign-off. A rehearsal runs the whole sequence against a test system first, so you learn how long it takes and what fails while it is still cheap. Cutover is the real run into production, in a planned window. Sign it off only when the reconcile is clean.
| Stage of a campaign | What happens | What you learn |
|---|---|---|
| Rehearsal 1 | The full sequence on a test Maximo | Which rows fail, and why |
| Rehearsal 2 | Again, after the fixes, timed | How long the window must be |
| Cutover | The same sequence into production, after approval | The real result, row by row |
| Sign-off | Reconcile is clean, and the owner signs | The proof that the register is right |
Upgrading to MAS: where data migration sits
The mistake: Run the go-live load for the first time on go-live night. Do this instead: Rehearse the whole campaign on a test system until it runs clean and you know how long it takes. Then cut over the same sequence, and sign off on a clean reconcile.
Remember: Rehearse until it is boring. A boring cutover is a successful cutover.
Lesson 7
Environment files, the Studio, and how the pieces fit
Assetize has three Workbench pieces, and you will hear all three names. The Data Workbench (/workbench) is the full web app: the grid, the load plan, the simulator, run history, an Excel edition for Windows and a self-hosted edition that runs inside a customer's own network. Workbench 3 (/workbench3) is the three-step path from sheet to proven load, with approvals and campaigns. Workbench 2.0, the Engineering Studio (/studio), is the upgrade project: mxH findings, workflows, reports, scripts and data in one place.
IBM documentation and other sources flow into the Assetize evidence base of source-backed records. From it come the free tools and ASK, and three products: mxH for upgrades, mxR for shipping changes and the Data Workbench for loading data, each pointing at a customer Maximo.
An environment file is how a connection moves between them. Its format is called assetize-environment/1. It holds the Maximo address, the type of login, whether it is Development, Test or Production, the version and the system's fingerprint (the Manage version, installed components, products and add-ons, database and base language), and the object structure schemas that environment has read. It never holds the key. You export it from one tool, import it into another, and open Edit to add your key.
An API key typed into code is committed, pushed and copied to clones, build logs and forks. Deleting it in a new commit leaves it in the old one, so the key is rotated. On the safe side the code holds only the name, the value sits in a secret store, only the running program reads it and logs mask it.
The Studio sits beside the data load, not on top of it. A Studio project is an upgrade project, and the Studio says so beside its versions. It can add the sheet that is open in the Grid Editor to the project, up to 500 rows; a bigger sheet is refused with the reason, never cut short. It can capture your Maximo with GET requests only: automation scripts (MXAPIAUTOSCRIPT), launch points (MXAPILAUNCHPOINT), workflow processes (MXAPIWFPROCESS) and applications (MXAPIMAXAPP).
| Data Workbench and Workbench 3 | Workbench 2.0, the Studio |
|---|---|
|
|
- A customer moving to MAS 9.2: mxH finds what breaks, the Studio fixes it, mxR ships the fix, and the Workbench loads and proves the data.
- A customer standing up a new Maximo: the starter pack opens organisation and site sheets first, then the rest in load order.
- A partner delivering for several customers: a project can be copied from a template with the mapping and order, and none of the first customer's rows, keys or run history.
- A team that must keep data inside its own network: the self-hosted edition runs as one Node process with one SQLite file, and saved credentials are sealed with the server's own secret.
The mistake: Copy an environment file into the project's Git repository with the API key added "to save time". Do this instead: Commit nothing with a key in it. The environment file is built to travel without one; each person adds their own key where they work.
Remember: Data goes through the Workbench. Fixes go through the Studio. A connection travels between them in an environment file, without its key.
Real practice on the Maximo SIM
Tasks you do by hand on the training Maximo, with the evidence your trainer checks.
- Load five locations into the SIM with Workbench 3 (DEV). A real load end to end: connect, map, check, preview, load, read each row, reconcile.
Check yourself: the Level 13 quiz
18 questions. Pass mark 70%.
- What has been the most common tool for Maximo data loads, and what does it run in?
- MXLoader, an Excel workbook
- Workflow Designer, a web page
- BIRT, a report designer
- mxR, a command line
- Look at the picture. Why does a data load go through the object structures and not straight into the database? (picture: Every change goes through the rules)
- Because SQL is slower
- So every row passes the business rules, audit and record versions; a direct SQL write skips them
- Because Maximo has no database
- Because Excel cannot write SQL
- Look at the highlighted step. What must you have before anything can be checked? (picture: A data load you can prove)
- A finished spreadsheet
- A connection: the Maximo address and an API key, or an imported environment file
- An approved campaign
- A reconcile report
- Where does the Maximo API key live in Workbench 3?
- In the environment file, so it travels
- In the workspace credential store; it never goes into a package or an environment file
- In a hidden column of the sheet
- In the URL
- Which picture shows the action that also removes child records missing from your file?
- AddChange
- Sync
- Delete
- You want to update 50 job plan descriptions and keep every task. Your sheet has no task columns. Which action?
- Sync
- Delete
- AddChange
- Any of them
- In IBM's integration framework, which action deletes existing child records that the message does not mention?
- AddChange
- Replace
- Add
- Change
- What does the preview in Workbench 3 show?
- Nothing until the load is done
- Every create, change and delete, before anything is written
- Only the errors
- The database schema
- Look at the picture. A load half-failed because the connection dropped. What does a safe retry do? (picture: Safe to press twice)
- Sends every row again
- Sends only the failed rows and the rows never sent; committed rows are sent once
- Deletes everything and starts over
- Waits for a manager
- A row's work order number is blank, so Maximo numbers it. The row loaded. Someone loads the whole sheet again. What happens to that row?
- Nothing, Maximo ignores it
- Maximo creates a second work order with a new number
- The first work order is updated
- The load stops
- Look at the picture. What does the amber row tell you? (picture: Reconcile: prove what landed)
- The load failed completely
- That one record read back from Maximo differs from what you meant to load, and which field differs
- That the row was never sent
- That the API key expired
- A package that requires approval is approved. Then someone edits one row. What happens?
- It runs anyway
- It runs only once its exact plan is approved, so the changed plan needs approving again
- The edit is ignored
- The approval moves to the next package
- What is a campaign in Workbench 3?
- A marketing email
- A go-live sequence of loads with rehearsals and cutover sign-off
- One row of a sheet
- A report template
- Which picture shows where the key belongs when a connection moves between tools?
- Typed into code and committed
- In a store that only the running program reads
- What does "Get from Maximo" (query into a worksheet) do to Maximo?
- Locks the records
- Nothing: it copies rows into the sheet and leaves Maximo as it is
- Deletes the records it copies
- Changes their status
- Look at the picture. Which tool would a customer use to load a spreadsheet of assets? (picture: Which tool answers which question)
- mxH
- mxR
- The Workbench
- ASK
- Your sheet has assets and the locations they sit in. Which loads first?
- Assets, then locations
- Locations, then assets
- Either, at the same time
- PMs first
- Fix problems is pressed. Which of these does it change for you?
- ACTVE to ACTIVE
- 31/12/2026 to 2026-12-31
- A wrong site code to the right one
- A missing asset number
Remember it as a picture
- 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.
Where these facts come from
- IBM Maximo 7.6.1 Integration Guide: Action attributes (AddChange, Replace and child records)
- IBM Docs: Data import best practices (use bulk APIs)
- IBM Maximo REST API: interfacing with REST APIs using API keys
- IBM Docs: Migration Manager application
- Assetize record: MxLoader
- Assetize record: the INTACTION domain values (Add, AddChange, Change, Delete, Replace)
- Assetize: Data Workbench documentation
- Assetize: Workbench 3
Try it on the real tools
How did Level 13 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.