Object Structure Design Patterns for Maximo

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 labor 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: optimized for external systems requesting data. These should be shallow, focused, and performant. Example: ASSET_QUERY for mobile lookups.

Publish structures: optimized 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 organizations running managed application support will find that cleanly separated structures significantly reduce troubleshooting time when integration issues arise.

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 customizations 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 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 organizations. 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.