Maximo object structure design is the single biggest determinant of whether an integration succeeds or becomes a maintenance liability. If you have built more than a handful of Maximo integrations, you have seen the pattern: a structure that seemed reasonable during development degrades six months into production. Performance drops. Schema changes break downstream systems. A simple field addition requires regression testing across three external applications.
The problem is not the integration technology. It is the object structure.
The Two Failure Modes
Object structures in Maximo fail in predictable ways.
Over-flattening: cramming everything into a single structure to “keep it simple”. This produces brittle integrations that expose unnecessary data, create tight coupling, and make versioning impossible.
Over-nesting: replicating the entire Maximo data model in hierarchical structures because “we might need it later”. This kills performance, complicates parsing, and creates maintenance overhead when unrelated schema changes ripple through the integration.
Both stem from the same mistake: designing the object structure around what Maximo has rather than what the integration needs.
Start with the Integration Contract
Define the integration contract first: not the object structure, but the actual business transaction.
If you are sending work orders to a mobile workforce system, the contract is “work assignment with location, asset, and task list”. It is not “work order with all possible relationships”.
The object structure should model the contract, not the database. Most teams skip this step. They open the Object Structures application, find MXWODETAIL, clone it, and start removing fields. The result reflects Maximo’s internal data model rather than the external system’s needs.
Instead:
- Document what the consuming system actually requires
- Map those requirements to Maximo objects
- Build the minimum structure that satisfies the contract
- Version it explicitly from day one
Nesting Depth Strategy
Each nesting level adds query complexity and payload size. Use this hierarchy as a guide.
Level 0 (Root): the primary business object (WORKORDER, ASSET, PM, etc.)
Level 1: direct relationships that define the transaction (WOACTIVITY, WPLABOR, LOCATIONS, etc.)
Level 2: reference data required for context (PERSON for labour assignments, ASSETSPEC for technical attributes)
Level 3 and beyond: treat this as a code smell. If you need data three levels deep, you are likely exposing implementation details rather than business concepts.
For example, if you need asset specification values in a work order integration, do not traverse WORKORDER → ASSET → ASSETSPEC. Evaluate whether those specifications should be denormalised into the work order itself via an automation script at creation time, or fetched separately through a dedicated asset query.
Exclude Everything by Default
Maximo’s object structure builder includes all fields by default. Reverse this approach.
Start with an empty structure. Add only the fields explicitly required by the integration contract. Every included field is a maintenance liability: something that could change, something that needs documentation, something that consumers might start depending on.
This applies especially to system fields (CHANGEBY, CHANGEDATE, ROWSTAMP, etc.). If the consuming system does not use them, exclude them.
The exception: primary keys and foreign keys required for relationship integrity. Include these even if the consumer does not explicitly use them, because they are necessary for processing.
Separate Query, Publish, and Sync Structures
Not all object structures serve the same purpose. Separate them by usage pattern.
Query structures: optimised for external systems requesting data. These should be shallow, focused, and performant. Example: ASSET_QUERY for mobile lookups.
Publish structures: optimised for outbound integration messages. These can be deeper because they are pushed asynchronously. Example: WORKORDER_COMPLETE for notifying external systems of closure.
Sync structures: bidirectional updates where external systems write back to Maximo. These must be minimal and strictly validated. Example: WORKORDER_STATUS for workflow updates.
Do not try to build one structure that serves all three patterns. The performance and security requirements differ, and organisations running managed application support will find that cleanly separated structures significantly reduce troubleshooting time when integration issues arise.
There is a fourth usage pattern that people rarely design for, and it is the one that hurts most when it goes wrong: the one-way load that brings history into Maximo during a migration. It is covered on its own below.
Handling Custom Extensions
Custom fields and extended objects are unavoidable. Build for them explicitly.
If your implementation uses extended attributes or custom tables, create dedicated child objects in the structure rather than mixing them with standard fields:
<WORKORDER>
<standard fields>
<WORKORDEREXT>
<CUSTOMFIELD1/>
<CUSTOMFIELD2/>
</WORKORDEREXT>
</WORKORDER>This isolates customisations from the standard schema, making upgrades to MAS cleaner. When IBM changes the base WORKORDER object in a new release, your custom extensions remain separate.
Versioning from Day One
Object structures have no built-in versioning. Add it yourself.
Use a naming convention that includes version: WORKORDER_MOBILE_V1, ASSET_QUERY_V2, etc. When requirements change, create a new version rather than modifying the existing structure. Run both in parallel during transition periods. Deprecate old versions explicitly with documented timelines.
This prevents the common scenario where a “small integration change” breaks three other systems that were quietly depending on the same object structure.
Testing Performance Early
Object structure performance problems do not appear during development with test data. They appear in production with 500,000 work orders.
Before deploying a structure to production:
- Test with realistic data volumes
- Measure payload size for typical queries
- Check query execution plans for the underlying SQL
- Profile integration endpoint response times
If a single work order query returns a 200KB JSON payload, the structure is probably over-specified.
The Migration Load Is a Contract Too
A data migration from SAP PM, an Oracle EAM estate or a decade of spreadsheets is where object structure design stops being an integration concern and becomes a business risk. The load is a one-way contract with no consumer on the other side to complain, which is exactly why bad decisions survive it.
The pattern that holds up:
- One load structure per business object, per source. Assets from the legacy system, locations, job plans, PMs, open work orders and closed history each get their own structure. Combining them because “it is all one migration” is the over-flattening failure mode with a deadline attached.
- Load in dependency order, and prove each layer before the next. Locations and classifications, then assets, then meters and specifications, then job plans and PMs, then open work, then history. A reconciliation count and a spot-check against source records at every layer.
- Validate on the structure, not after the load. Required fields, domain values and key integrity belong in the structure and its processing rules. Cleaning records inside Maximo afterwards is what turns a two-week load into a two-month one.
- Keep the legacy key. A dedicated field carrying the source system identifier, populated on every migrated record, makes reconciliation and the inevitable second pass possible. Dropping it to save a column is a decision people regret in week three.
- Decide the history boundary before you build anything. How many years of closed work orders come across, whether costs come with them, and whether attachments follow. This is an asset management decision, not a technical one, and it has to be signed off by the person who will be asked for that history in an audit.
Two things are worth separating here, because they get conflated in almost every programme. Moving records is an engineering problem with a testable answer. Deciding which records deserve to move, and which duplicate is the real one, is a judgement your own engineers have to make. We take on the first and support the second, which is how the data migration into Maximo work is scoped, and the same structures then serve the live interfaces described on Maximo integrations.
The Maintenance Test
Ask this question: if a developer unfamiliar with this integration needed to add one new field, how many places would they need to change?
The answer should be two: the object structure definition and the consuming system’s parser.
If the answer involves updating mapping logic, modifying a transformation script, and adjusting validation rules, the structure is too complex.
What a Well-Designed Object Structure Looks Like
A well-designed Maximo object structure:
- Models the business transaction, not the database schema
- Includes only fields required by the contract
- Nests no more than two levels deep for query operations
- Isolates custom extensions from standard objects
- Has an explicit version in its name
- Produces payloads under 50KB for typical operations
- Can be modified without cascading changes to unrelated systems
These patterns emerge from production Maximo implementations across utilities, transportation, manufacturing, and public sector organisations. The teams that follow them spend less time fighting integration defects and more time delivering business value.
Start with the contract. Build the minimum structure. Version explicitly. Test with real data.
What Good Structures Do Not Fix
Being honest about the boundary matters, because a clean object structure is often sold as the answer to problems it cannot touch.
- A contested data model stays contested. If two business units disagree about what an asset is, no structure resolves it. The disagreement simply arrives in the payload.
- Source data quality does not improve in transit. A structure can reject a bad record. It cannot decide what the right value was.
- The other system still has an owner and a release calendar. Versioning protects you from surprise, not from waiting.
- Volume still costs something. Shallow, well-scoped structures make large loads feasible. They do not make a decade of closed work orders free to move.
What to Bring If You Want a Second Opinion
If an integration or a migration is not behaving, three artefacts make the conversation short: an export of the object structure definition, one real payload with the values in it, and the reconciliation count that is not matching. Thirty minutes with a senior MaxIron engineer on those is usually enough to say whether the structure is the problem or the symptom.
Book a 30-minute review, or read how we scope the work on data migration into Maximo and Maximo integrations.