Indoor Maps Need a Cross-System Identity Contract
A floor-aware map is more than a set of drawings. It is a contract between facility records, spatial features, relationship keys, and the people who maintain them.
Indoor Maps Need a Cross-System Identity Contract
A technician opens a work order for a water heater in a multistory building. The record names a location, and the map shows a point. That sounds like success until someone asks whether the point belongs to the correct building, the correct floor, and the same asset that the work order describes. A map can render beautifully while those answers remain uncertain.
The useful architecture question is not simply whether Maximo Spatial can display indoor layers. It is whether the organizations maintaining Maximo and the geographic information system can keep identity, ownership, and floor context aligned when buildings and equipment change. The visual result is the last step of a longer agreement.
A recent IBM Community hands-on lab by Mohamed Chihaoui illustrates this with a guest-house example. It connects facilities, levels, rooms, and equipment to Maximo records and demonstrates how a work order can inherit facility and floor context. The lab is a specific demonstration, not proof that every implementation behaves identically. Its strongest lesson is architectural: shared identifiers and carefully defined relationships do the work that the map presentation makes visible.
There is also a reliability angle. If an organization chooses to move spatial or asset changes through asynchronous interfaces, the interface's failure and replay behavior become part of the mapping contract. IBM's queue-based error documentation distinguishes between sequential processing that stops on an error and continuous processing that permits later messages to continue. That distinction matters when a floor must exist before a room can refer to it. A map may look current while one side of an exchange is held for correction.
I would treat this as a cross-system product with explicit owners, acceptance tests, and reconciliation, rather than a one-time mapping exercise. The following design is a proposed operating pattern, not an assertion that Maximo automatically provides every control described here.
Define identity before designing the map
Start with four kinds of business entity: facility, level, room, and equipment. Each needs an identifier that has an agreed meaning across the systems that exchange or relate it. The lab uses facility and level identifiers on indoor layers, with room and equipment features carrying a level reference. Maximo records also carry facility and floor context. The specific labels and fields should be checked against the versions and configurations in the target environment rather than copied without review.
Create a mapping inventory with one row per entity. Record the system that assigns the identifier, the scope in which it must be unique, the fields used to join it to another system, and the party authorized to change it. For a room, the inventory might identify the Maximo location and site combination alongside the GIS feature's corresponding business key. For equipment, it might identify an asset number and site context. These are design examples, not prescribed universal keys.
The distinction between a display label and a durable identifier is essential. A building name can change after a tenant moves or an organization restructures. A floor may be called ground, first, or level zero depending on local convention. A room label might be reused after a renovation. If labels are used as joins without a policy for change and reuse, the integration can associate a correct-looking feature with the wrong operational record.
Define what happens when a key changes. Is the old identifier retired permanently? Can it be reused? Which side initiates the change, and how is the other side notified? If a feature is temporarily unmatched, should it be hidden, flagged, or displayed with a warning? Those choices require business ownership. A developer cannot safely infer them from a map layer or an API schema.
Also define the time boundary of the relationship. Equipment can move between rooms, and rooms can be split or combined. A current map may need the current location while an older work order still needs its historical context. Decide whether the business requires a historical association and where that history is kept. Do not assume that changing a current feature automatically provides an auditable history of earlier locations.
The first acceptance test is therefore not a screenshot. Pick a sample facility, floor, room, and asset. Follow their identifiers from Maximo to the feature service and back. Have the facility owner confirm that each pair describes the same real-world entity. Then repeat the exercise with an intentionally incorrect key and confirm that the discrepancy is visible to the team responsible for fixing it.
Make the floor-aware web map a governed interface
The community lab separates four layers: facilities, levels, units, and equipment points. It explains that the web map must identify its facility and level layers and identify the floor field for other indoor layers. Without the floor-aware settings in that example, the Indoor tool is not presented. This is a configuration dependency, not merely a cartographic preference.
Treat the web map as an interface artifact. Inventory the map item, the relevant layers, their business purposes, and the fields used for facility and floor relationships. Record which team can alter each layer or publish a replacement. A map designer may legitimately improve a symbol, but renaming or replacing a field used by the integration is a contract change. It deserves review by the Maximo owner before the new version is promoted.
The lab describes vertical order as the floor stacking number and uses continuous ordering for its site. A basement, entrance level, and upper floor have an ordering relationship that is separate from the names people see on signs. Before relying on it, compare the configured order with the actual building and the floor selector. If a building has a mezzanine or an unusual numbering convention, document the local decision rather than assuming the visual label determines the underlying order.
A useful test set includes a basement, a normal occupied floor, and a boundary case such as a roof or mezzanine where the organization has chosen to model one. For each, select the facility and floor, confirm that the intended room appears, and confirm that a room on a different floor is not incorrectly shown as the selected room. Then inspect an equipment point and verify that its floor reference agrees with the associated Maximo record.
The test must also consider access. A GIS administrator who can see every layer is not a substitute for a maintenance user with ordinary permissions. Test with an appropriate role in a nonproduction environment and use the organization's approved access arrangements. A blank layer can indicate a permissions or service problem, not necessarily missing data. The team needs a troubleshooting path that distinguishes these cases before a user is instructed to redraw a feature.
Finally, give the map a versioned release record. Capture the source map, layer schema, relationship fields, test evidence, and rollback owner. This is an operational recommendation, not a claim that the lab implements a release pipeline. If a map or layer is replaced, the team should be able to say which contract changed, who approved it, and how the previous working configuration can be restored safely.
Specify relationship ownership and failure handling
In the lab, Map Manager creates GIS objects for the layers and relationships join GIS features to Maximo objects using shared keys. The author describes a system-of-record choice for those link values. This is an important boundary: seeing two records on the same screen does not mean either system owns every field or that all attributes are automatically copied between them.
Write a field-level ownership matrix. For example, an organization may choose Maximo to own an asset's maintenance identity while the GIS team owns geometry. Another organization may have a different arrangement. The important point is that ownership is explicit for each field and that the update direction is defined. List read-only fields, authoritative fields, derived fields, and fields that require human approval before synchronization.
The contract should cover creation, change, and retirement. When a new room is created in Maximo, what event or work request tells the GIS owner to add the corresponding feature? If a room polygon is edited, does that imply a change to the Maximo location hierarchy, or only a geometry correction? If a feature is retired, how is the corresponding operational record reviewed? Avoid a rule that silently deletes the other side merely because one system no longer returns a record.
Now consider a mismatch. The GIS feature references a room identifier that Maximo cannot resolve. The map may still display a shape, but the maintenance user cannot trust its relationship to work. The proposed response is to put that exception into an owned work queue with the feature key, source, observed time, and an actionable reason. A steward should decide whether the key is wrong, the Maximo record is missing, or the change arrived out of order.
If the implementation uses Maximo's asynchronous integration queues for some of these changes, queue behavior must be designed deliberately. IBM states that a sequential queue processes one message at a time and stops later messages when an error occurs, while a continuous queue can continue processing later messages and accumulate multiple errors. IBM's community explanation of queue selection also discusses dependencies between parent and child records. These sources describe integration queues generally; they do not establish that the indoor-map lab uses them.
For an ordered facility-to-floor-to-room feed, test a missing parent and an invalid child. Determine whether later changes should wait or proceed independently. If they proceed, ensure that unresolved references are tracked and rechecked. Do not assume that retrying alone guarantees correctness. The business owner should approve the recovery action, particularly when the correction changes identity rather than merely fixing a temporary connectivity problem.
Prove location context on work, not only on a map
A map becomes operationally useful when the work record carries enough context for someone to find and maintain the right asset. In the lab's example, Facility ID and Floor ID on Service Address provide that context, and a work order created from an asset or location inherits it. Treat this as a demonstrated example to verify in your own version and configuration, not as a promise about every custom creation path.
Build a test matrix around entry points. Create a work order from a location, create one from an asset, and test any integration or mobile flow that your organization actually uses. For each path, compare the work order's facility and floor with the source record. Document which values are inherited, which are editable, and what happens if the asset is moved after the work order is created. The expected outcome is a business decision that may vary by work type.
Include negative tests. An asset with no floor, an invalid floor identifier, or a room associated with a different facility should not be treated as a successful mapping simply because a work order saves. Decide which scenarios must block creation and which can proceed with a warning and a data-quality task. That distinction matters for emergency work: a missing map should not automatically prevent an urgent response, but the absence must be visible.
Inspect the result from the technician's perspective. Can the person identify the building and floor without interpreting a GIS field name? Does the displayed feature identify the intended equipment rather than a nearby feature on another level? If the map service is unavailable, does the record still present enough location information to continue safely? These are acceptance questions for the local implementation, not claims about a standard offline capability.
A second important test concerns change over time. Move a test asset between rooms using the authorized process. Observe the Maximo record, the GIS feature, and a newly created work order after synchronization or manual updates have completed. Then review a pre-existing work order. The organization must decide whether it represents the original place of work or should reflect the new asset location. Preserve evidence of the decision and test whichever policy is adopted.
Capture evidence without exposing sensitive building layouts more broadly than necessary. Screenshots, sample payloads, and logs can contain location details or operational information. Use approved test data, limit access, and agree on retention. A successful demonstration should leave behind a repeatable test case, not an uncontrolled collection of production floor plans on individual laptops.
Reconcile changes and assign a route to repair
Even a sound initial import does not eliminate drift. A building is renovated, an asset is replaced, or one team updates an identifier without notifying the other. A reconciliation process makes these changes visible. It does not have to be a complex real-time platform on day one, but it does need an owner and a defined response.
Compare key sets at the facility, level, room, and asset boundaries. Identify records present only in Maximo, features present only in GIS, duplicate business keys, and records whose facility or floor references disagree. Treat a difference as an exception for investigation, not proof that one side should automatically overwrite the other. Some records may legitimately be excluded from the map, and an inclusion rule should explain why.
For each exception, store the entity type, relevant business keys, source systems, first observed time, current state, and responsible owner. Keep a link to the approved correction or work request. If a change is corrected by replaying an integration message, record the reason for the replay and verify the resulting business record. If it is corrected manually in GIS, verify the relationship in Maximo after the map refreshes. A closed ticket without a successful cross-system check is not enough.
Set thresholds that reflect the use case. A missing equipment point on an inactive training map does not have the same consequence as a wrong floor on an active emergency response workflow. The facilities owner, maintenance lead, and GIS owner should agree which discrepancies require immediate attention and which can be handled in a regular stewardship cycle. Avoid promising a universal response time without an actual service agreement.
The IBM queue documentation describes Message Reprocessing for erroneous asynchronous messages. If a team uses that path, it should monitor both messages awaiting attention and the business-level reconciliation results. An empty error view alone does not demonstrate that the intended feature points to the correct room. Conversely, an exception in the reconciliation report might be a deliberately excluded feature rather than a transport failure.
Test the operational handoff with a tabletop exercise. Simulate a room identifier change, a feature that arrives before its floor, and a map service outage. For each scenario, identify who detects the issue, who decides the authoritative value, who makes the change, and who confirms that a technician sees the corrected context. Include the steps to suspend automatic replay if repeated attempts could worsen the state. Run the exercise in a controlled environment with approved test records.
Practical Implications
Begin with one building where the facilities team can identify a responsible owner for the hierarchy and the GIS team can identify a responsible owner for the layers. Choose a small but representative set of rooms and equipment, including at least one floor transition and one asset move. The objective is not to prove every enterprise scenario at once. It is to demonstrate that the identity and repair process works before scaling it.
The deliverables should be concrete: an entity and key inventory, a field ownership matrix, a floor-aware map configuration record, an agreed exception workflow, and a test pack covering work order creation and change over time. Add a reconciliation report only after the teams agree what counts as a legitimate difference. Otherwise the report becomes a list of noise that nobody owns.
Before production, review the security and availability model with the platform team. Identify the service accounts and permissions required to view the layers, the approved method for storing credentials, and the support route when a map service cannot be reached. Do not put actual credentials in the design record or test evidence. Validate the current IBM and GIS documentation for the deployed versions, especially where older examples describe a different runtime.
Measure acceptance through evidence rather than a generic claim that the map is live. A facilities representative should confirm the physical location, a Maximo owner should confirm the operational record, and a GIS owner should confirm the feature and floor. Record any unresolved exceptions and their owners before expanding the rollout.
Bottom Line
Indoor mapping is not finished when the floor selector appears. It is finished for a particular release when the people who own the facility hierarchy, the Maximo records, and the GIS features can demonstrate that their identifiers refer to the same things and can repair a disagreement without guessing.
The IBM Community lab provides a useful illustration of the layer and relationship model. IBM's integration documentation adds a separate warning about asynchronous processing: the choice between preserving order and continuing past errors changes the recovery problem. Neither source replaces the local decisions about ownership, safety, access, and historical work context.
Build the identity contract first, test it through an actual work order, and make reconciliation a routine responsibility. A trustworthy indoor map is not just a picture of a building. It is a maintained agreement about where the work and the equipment really are.