Maximo Manage Deep Dive: Object Structures, Security, and JSON Mapping

In IBM Maximo Manage, almost every integration, report, mobile data flow, and AI training pipeline eventually routes through an object structure. Object structures are the canonical abstraction that groups related business objects, such as work orders, assets, locations, or purchase orders, into a single data contract. They define which attributes are exposed, which child objects are included, and how the data can be read or written by external systems. Despite their central role, object structures are often configured quickly during a project and then left untouched for years. That is a mistake. A poorly designed object structure can leak data, create synchronization conflicts, break after upgrades, or force teams to write brittle custom transformations that should have been handled inside Maximo.

This article is a technical deep dive into object structures as they are used in modern Maximo Manage deployments. We cover the anatomy of an object structure, how to restrict sensitive attributes, how object structure security templates work, and a practical pattern for invoking the Maximo JSON mapper from an Automation Script when an invocation channel does not natively support JSON mapping. The goal is to give Maximo developers and integration specialists a stronger mental model for one of the most important configuration artifacts in the platform. Whether you are building MIF-based integrations, REST APIs, OSLC endpoints, or AI training pipelines, the object structure is the layer where correctness, security, and maintainability are decided.

Anatomy of an Object Structure

An object structure is a collection of Maximo business objects, also called MBOs, arranged around a root object. The root object determines the primary entity that the structure represents. For example, an object structure for work order details might use WORKORDER as the root, with child objects such as WOLABOR, WOMATERIAL, and WOSERVICE joined through defined relationships. The child objects provide the related records that make the data contract useful. Without the child objects, an external system receives only the header data and must make additional calls to reconstruct the full work order state.

When you create or inspect an object structure in Maximo, the key components to review are the source objects, the relationships between them, and the operations the structure supports. Source objects define which MBOs participate. Relationships define how the child records are fetched relative to the root. Operations, including Query, Add, Update, Delete, and Sync, determine what external callers can do. Not every object structure needs to support every operation. A reporting-only structure, for instance, may only need Query, while an inbound integration from an ERP system may need Add and Update.

Object structures are used for more than integrations. They also power Start Center result sets, Query Based Reporting, Work Centers, Role Based Applications, and the data contracts used by Maximo AI Service. This broad usage means that a single object structure may be consumed by multiple parts of the system. Changing a structure that was originally built for one purpose can have unexpected side effects elsewhere. A good practice is to document the intended consumers of each custom object structure and to avoid reusing a structure for an unrelated purpose just because it happens to contain the right objects.

Restricting Fields and Inbound Behavior

One of the most important configuration tasks is deciding which fields are exposed for external read and write. In Maximo, attributes can be marked as restricted at the database configuration level. A restricted attribute will not be overwritten by inbound values from an external system. This is useful for fields that are system-managed, such as work order identifiers, status history, or auto-generated numbers. When an external payload includes a restricted field, Maximo ignores the external value and lets the MBO framework determine the correct value.

There is also a finer-grained override mechanism. For fields where you normally want to protect the value but occasionally need to allow an external update, you can configure an override on the object structure. For example, a work order status field might be restricted by default so that external systems cannot accidentally close a work order, but a specific integration from a field service mobile app may be trusted to update status. In that case, you can enable the override for the status field on the relevant object structure. The external system can then update status through that structure, while other integrations using different structures remain protected.

The configuration path for attribute restriction starts in Database Configuration. Find the object, select the attribute, and mark it as restricted. On the object structure side, the Inbound Setting Restrictions dialog shows which fields are restricted and allows you to set override behavior. The relationship between database-level restriction and object structure-level override is a common source of confusion. Remember that database configuration is the default; object structure overrides are the exception. This layered approach lets administrators enforce a safe default while granting specific integrations more latitude.

Object Structure Security Templates

Exposing an object structure to external callers without controlling who can use it is a security risk. Object Structure Security, sometimes called Object Structure Data Restrictions, lets administrators control which SIG options are available for a given object structure. Once enabled, the object structure appears as a separate authorization name in the Security Groups application. Administrators can then grant or deny capabilities such as read, save, insert, or delete per group.

To enable object structure security, open the object structure and use the Configure Object Structure Security action. After enabling it, you can assign access in the Security Groups application under the Object Structures tab. The available options typically include:

This model aligns well with least-privilege integration design. A reporting integration may receive only Read access. An ERP integration that creates purchase orders may receive Insert but not Delete. A mobile integration that updates work orders may receive Read and Save but not Insert. By mapping integration accounts to security groups with narrow object structure permissions, administrators reduce the blast radius if an integration account is compromised or misconfigured.

Object structure security is also valuable for AI and analytics use cases. Maximo AI Service uses object structures to define the data that can be used for training and inference. Restricting which groups can read or save through an AI-related object structure helps prevent unauthorized model training or inference against sensitive operational data. Security templates should be part of the design review for any new object structure, not an afterthought applied during production hardening.

Advanced Configuration and Child Object Behavior

Object structures include advanced configuration options that control how child objects behave during serialization and deserialization. One common option is whether to exclude parent keys from child objects. For example, when generating a work order with child work activities, the parent work order number is already present on the parent record. You may not want the child records to include that same parent key in the outbound payload. Excluding parent keys reduces payload size and avoids redundant data, but it may also require the receiving system to re-associate child records based on position or sequence. The right choice depends on the consumer's expectations.

Other advanced options control duplicate detection, how objects are deleted, and whether to apply business rules during inbound processing. These settings should be reviewed whenever an object structure is used for more than simple querying. The default behavior is safe for most cases, but integrations with complex data contracts may need adjustments. A typical scenario is an inbound work order update that includes multiple child objects. If the integration is expected to replace the entire set of child records rather than merge them, the delete and duplicate behavior must be configured accordingly.

For diagnostics, Maximo provides several tools. The Object Structures application shows the object hierarchy, relationships, and enabled operations. Integration events and error messages can be traced through the Message Reprocessing application and the system logs. When debugging a structure that is not returning expected data, start by confirming the relationships are correct, the operations are enabled, and the user account has the right security options. Then verify the XML or JSON payload matches the expected schema, including the root element name and namespace.

JSON Mapping Through Automation Scripts

IBM Maximo's JSON Mapping feature supports Publish Channels and Enterprise Services, but it does not support Invocation Channels. This gap matters when an integration needs to transform outbound data for a target system but the native channel type cannot use the JSON mapper directly. Amin Chakri, an IBM Maximo technical expert, documented a clean workaround that uses a short Automation Script to invoke the Maximo JSON mapper engine programmatically. The script instantiates ExternalJSONMapper, applies the mapping to the object structure data, converts the output to bytes, and returns it as the outbound payload.

The advantage of this approach is that it reuses existing JSON Mapping configuration. Teams do not need to hand-build JSON in scripts, do not need custom Java development, and keep transformation logic separated from integration routing logic. The script serves as a bridge between the invocation channel and the mapper engine. A simplified illustration of the pattern is shown below.

from com.ibm.tivoli.maximo.oil.json import ExternalJSONMapper
from java.nio.charset import StandardCharsets

# Load the configured JSON mapping for the object structure
mapper = ExternalJSONMapper()
mapper.setMappingName("MY_JSON_MAPPING")

# Apply the mapping to the current MboSet / object structure data
mapped_json = mapper.transform(mboSet)

# Convert to bytes for the outbound invocation channel payload
payload = mapped_json.getBytes(StandardCharsets.UTF_8)

# Return the payload to the channel
errorgroup = ""
errorkey = ""

This pattern is not a replacement for native JSON Mapping support in invocation channels. It is a practical workaround that preserves the value of the mapper investment. Teams that use it should still test the output schema carefully, handle mapping failures with appropriate error logging, and document which channels rely on scripted transformation. If IBM adds native invocation channel support for JSON mapping in a future release, the script can be retired.

Practical Implications

Object structures are configuration artifacts, but they have code-level consequences. A structure that exposes too many fields, supports the wrong operations, or lacks security restrictions can become a long-term liability. The practical implications for a Maximo development team are clear. First, treat object structure design as architecture, not ad hoc configuration. Every custom structure should have a documented owner, consumer list, intended operations, and security profile. Second, restrict attributes by default and open them only where a specific integration requires write access. Third, enable object structure security for any structure consumed by external systems, and assign integration service accounts to narrowly scoped groups.

The JSON mapping script pattern adds another tool to the integration toolkit. It allows teams to reuse mapper definitions in places where native support is missing, reducing technical debt and avoiding duplicate transformation logic. However, scripted solutions should be reviewed during upgrades because internal class signatures and engine behavior can change. Keep these scripts under version control and include them in upgrade regression testing.

Bottom Line

Object structures are the contract layer of Maximo Manage. Getting them right improves integrations, reporting, mobile flows, and AI pipelines. Getting them wrong creates security gaps, upgrade fragility, and integration failures. The combination of field restrictions, object structure security templates, advanced child object behavior, and scripted JSON mapping gives developers a strong set of controls. Use them deliberately. Document your structures, restrict access, and test them in full-stack scenarios before promoting changes to production.