Loading a Maximo location hierarchy

Updated August 7, 2026 · Mathias, LLC

PARENT is not a column

Open the Locations application and look at a location. There is a Parent field, and it behaves like every other field on the screen. The reasonable assumption is that it is a column on the LOCATIONS table, which you can set the way you set DESCRIPTION. The object metadata says otherwise:

PARENT and SYSTEMID are non-persistent. Maximo presents them on the location record, but it stores the relationship in a separate structure, and the location does not own its own position in the hierarchy. Sixteen of the ninety attributes on LOCATIONS work this way.

Systems, and what the hierarchy hangs off

A Maximo location hierarchy is always scoped to a system. The system is the named tree. One location can belong to several systems and hold a different parent in each.

This answers a question people ask often: yes, you can have more than one location hierarchy. A plant might run a physical system of site, building, floor, and room, alongside an electrical distribution system and a process system. The same pump can appear in all three at a different position in each.

A location's parent therefore means nothing on its own. Every hierarchy operation has to name a system:

• Systems are held on their own object and are listed independently of locations.
• The top of a tree is reached through the system's topleveloc relationship to locations. The system knows its roots; the roots do not know the system.
• Descending a level uses syschildren from a location, and it has to be told which system it is descending.

Through the integration APIs, listing the systems and then drilling into one looks like this:

GET /os/mxapilocsystem?oslc.select=systemid,description

GET /os/mxapilocsystem/{id}/topleveloc.mxapioperloc
      ?oslc.select=systemid,description

GET /os/mxapioperloc/{id}/syschildren.mxapioperloc
      ?ctx=systemid=<systemid>

The primary system default

Every location has a primary system, which Maximo uses when you have not said which system you mean. The default is convenient in the user interface and risky through the API.

Apply the same thinking to removing a primary system. Establish what currently depends on the default first. Every drill-down, integration, and report that does not name a system explicitly is relying on it.

Loading a hierarchy

Split the work in two, because Maximo does. Loading location records and loading hierarchy relationships are separate operations with separate failure modes. Running them as one step is what produces a half-built tree.

Step 1 — load the locations

A location is identified by LOCATION plus SITEID. Both are required and both are UPPER, and LOCATION is capped at 25 characters. A workable minimum adds a description, which Maximo cuts at 100 characters, a type, a status from the LOCASSETSTATUS domain, and the organization.

Load every location before you load a single relationship. A parent that does not exist yet cannot be referenced.

Step 2 — load the hierarchy, parents first

A relationship row names the child location, its parent, and the system the relationship belongs to. The ordering rule is absolute: a parent must exist in the hierarchy before any child can attach to it. Sort the file so that each level loads before the level beneath it, starting at the roots.

Sheets exported from another system usually arrive in alphabetical or arbitrary order. That order interleaves the levels and produces failures that look random. They are not random. Every one of them is a row whose parent did not exist yet.

Step 3 — let Maximo derive the rest

Maximo maintains a denormalized ancestry table, so that "everything under this location" is a fast query rather than a recursive walk. Do not populate it directly. Maximo derives it from the relationships you loaded, so correct the relationships if the ancestry looks wrong.

Mass-changing parents

Bulk re-parenting comes up in a reorganization, a site merge, or a correction after a bad load. It is the most common reason people look for a loading tool, and it is one of the few Maximo operations where a single mistake moves a very large amount of data.

1. Extract the current hierarchy first, naming the system explicitly. That extract is your rollback, and without it there is no undo.
2. Build the target state as data rather than as a series of edits. One row per relationship: child, new parent, system.
3. Check for cycles before you load. Sort the target list and walk each chain to a root. A chain that does not terminate is a loop. Maximo will reject a loop row by row without telling you the shape of it.
4. Order the file by depth, parents before children, as in the initial load.
5. Move a subtree by its top node. Re-parenting the head of a branch carries everything under it, while re-parenting each descendant separately does more work and creates more opportunities for a partial move.
6. Preview, then commit. Compare each proposed parent against the current one, and read the count of rows that would change before anything is written. A run that reports many more changes than you expected has usually matched on the wrong key.

The errors everyone hits

"A location cannot be its own descendant"

This means you have created a cycle: A under B and B under A, possibly through several intermediate locations. Maximo checks the whole ancestry chain rather than the immediate parent, so a loop can span many levels and stay invisible in a spreadsheet. Trace the chain upward from the rejected location until you reach a root or return to where you started.

A partial re-parenting run is the version of this that causes most trouble. Half the moves apply and half are rejected, which leaves a structure containing loops that were in neither the original nor the intended state.

"Created two locations and cannot add one as parent of the other"

There are four usual causes. The two locations are in different sites, and the hierarchy is site-scoped. The parent exists as a location but has not been added to the system you are working in. The location type does not permit children in your configuration. Or the parent already sits somewhere above this location, which makes the request a cycle.

The hierarchy loaded but the drill-down looks wrong

Check which system you are viewing before you conclude the load failed. If the location belongs to several systems, the tree on screen may be a different one from the tree you loaded. This is the ctx default described above.

"The action Add is not allowed on object …"

This is BMXAA0024E, and it is a missing security grant rather than a data problem. It fails every row identically until the grant exists. See the error guide.

Verifying the load

Do not treat "no errors" as proof that the hierarchy is right. A load can report complete success and still produce a tree nobody wants. Five checks:

• Count the roots, meaning the locations with no parent in the system. The number should be small and you should be able to name every one. A hierarchy load that has gone subtly wrong shows up as dozens of unexpected roots, which are the rows whose parent reference did not resolve.
• Count the nodes in the system and compare that against the number of rows you loaded.
• Check the maximum depth. A depth greater than your physical reality means a chain attached in the wrong place, and a depth of one means only the roots landed.
• Spot-check both ends. Drill from a root down to a leaf, then take a leaf and walk it back up, naming the system explicitly in both directions.
• Re-extract the hierarchy and compare it against your target file. This is the only check that proves the outcome rather than sampling it.

Where a loading tool fits

None of the above needs a product. It is Maximo behavior, and it applies equally to a MIF load, an automation script, or Application Import. A tool changes how much of the checking is automatic rather than remembered.

MaxQuickLoad is built around the two habits that matter most here. It retrieves current Maximo values, so a re-parenting run can be compared against them before it is committed, and it keeps parent and child structures together through a sequenced run, so the ordering is handled rather than hand-sorted. Every transaction goes through Maximo's REST APIs with the loading user's own permissions, so the security model above applies exactly as described.

If you are loading a hierarchy this month, ask for a demo. It takes about thirty minutes, on a real load.