Integration Flow Explorer
Maximo integration patterns
Every Maximo Integration Framework pattern, explained with its flow, when to use it, the Enterprise Integration Patterns it implements, and how it handles failure.
Core patterns
Publish Channel
Maximo tells other systems when a record changes. When a record such as a work order is saved, the publish channel turns it into a message through its object structure and puts it on the outbound queue. Each external system that subscribes to the channel gets its own copy, delivered by that system’s end point. Maximo carries on without waiting for the receiver.
Enterprise Integration Patterns: Event Message, Event-Driven Consumer, Recipient List, Canonical Data Model, Message Filter, Message Translator, Content Enricher, Guaranteed Delivery, Point-to-Point Channel, Messaging Gateway, Dead Letter Channel.
Sequence
- User or process → Maximo record: Save work order
- Maximo record → Publish channel: Record event (listener on)
- Publish channel: Event filter, build PublishMXWO, rules, user exit, XSL
- Publish channel → Outbound queue (sqout): One message per subscribing system
- Maximo record → User or process: Saved: the user does not wait for delivery
- Queue consumer → Outbound queue (sqout): Read the next message
- Queue consumer → End point (HTTP): Send it
- End point (HTTP) → External system: HTTP POST PublishMXWO
- External system → End point (HTTP): 200 OK: message done
- On failure: External system → End point (HTTP): 500 or no answer
- On failure: Queue consumer → Message Reprocessing: Hold the message with BMXAA1477E
- On failure: Outbound queue (sqout): Later messages wait behind it (sequential)
Enterprise Service, synchronous
Another system sends a record and waits for Maximo to save it. The sender posts a message to the enterprise service URL. Maximo checks the sender is a known, enabled external system, runs the processing rules, checks the object structure security and saves the record, all inside the request. The answer says whether it worked.
Enterprise Integration Patterns: Request-Reply, Document Message, Messaging Gateway, Canonical Data Model, Message Translator, Splitter, Transactional Client, Remote Procedure Invocation.
Sequence
- External system → Enterprise service: POST /meaweb/es/{system}/MXWOInterface
- Enterprise service: Sender known and enabled?
- Enterprise service → Rules and OSIN script: Apply processing rules and OSIN
- Rules and OSIN script → Object structure: Message in Maximo format
- Object structure → Maximo database: Check security, validate, save WORKORDER
- Maximo database → Object structure: Saved
- Enterprise service → External system: 200 SyncMXWOResponse with messageID
- On failure: Object structure → Enterprise service: Validation fails, e.g. BMXAA7094E
- On failure: Enterprise service → External system: 400 Error 400: BMXAA7094E, nothing saved
Enterprise Service, queued
Another system drops a record on Maximo’s inbound queue and moves on. The sender posts to the queued URL and gets an answer as soon as the message is safely on the inbound queue. A consumer then applies messages one by one (sequential) or in parallel (continuous). A message that fails waits in Message Reprocessing, where it can be corrected and reprocessed.
Enterprise Integration Patterns: Guaranteed Delivery, Point-to-Point Channel, Competing Consumers, Polling Consumer, Dead Letter Channel, Invalid Message Channel, Message Store, Correlation Identifier.
Sequence
- External system → Enterprise service: POST /meaweb/esqueue/{system}/MXWOInterface
- Enterprise service → Inbound queue (sqin): Put the message on the queue
- Enterprise service → External system: 200: accepted, not yet applied
- Queue consumer → Inbound queue (sqin): Read the next message
- Queue consumer → Object structure: Apply: rules, OSIN, validation
- Object structure → Maximo database: Save WORKORDER
- Maximo database → Queue consumer: Saved: message removed from the queue
- On failure: Object structure → Queue consumer: Fails, e.g. BMXAA7094E
- On failure: Queue consumer → Message Reprocessing: Hold with the error, try 1
- On failure: Support → Message Reprocessing: Edit the message and reprocess
- On failure: Message Reprocessing → Object structure: Apply the corrected message
- On failure: Object structure → Maximo database: Save WORKORDER
Invocation Channel
Maximo calls another system and uses its answer. Maximo sends a request out through an end point and waits for the response, for example to get a price, check a permit or validate an address. The response can be mapped back onto the record. It is started by an action, a workflow step or an automation script, not by a queue.
Enterprise Integration Patterns: Request-Reply, Messaging Gateway, Message Translator, Content Enricher, Remote Procedure Invocation.
Sequence
- User → Action or script: Click the action, e.g. Get price
- Action or script → Invocation channel: service.invokeChannel
- Invocation channel: Build the request from the request object structure
- Invocation channel → End point: Send
- End point → External system: HTTP or SOAP request
- External system → End point: Response
- End point → Invocation channel: Response
- Invocation channel → Action or script: Map values from the response object structure
- Action or script → User: Record updated on screen
- On failure: External system → End point: Timeout or error
- On failure: Invocation channel → Action or script: Exception
- On failure: Action or script → User: Error shown; nothing is queued
Object Structure service
Send a record straight to an object structure, without an external system. The caller posts to the object structure itself. There is no sender check and no external-system routing, so external-system processing rules and controls do not apply; object structure rules and scripts still do.
Enterprise Integration Patterns: Request-Reply, Canonical Data Model, Document Message.
Sequence
- Caller → Object structure: POST /meaweb/os/MXWO
- Object structure: Object structure rules and scripts
- Object structure → Maximo database: Validate and save
- Maximo database → Object structure: Saved
- Object structure → Caller: 200 response
- On failure: Object structure → Caller: 400 with BMXAA message, nothing saved
REST / JSON API (OSLC)
Read and write any object structure with JSON over HTTP. The Maximo REST API exposes every object structure as a JSON resource: query with filters, create, update, delete, and call actions such as status changes. It is the most used integration on MAS. Callers authenticate with an API key.
Enterprise Integration Patterns: Request-Reply, Canonical Data Model, Polling Consumer, Remote Procedure Invocation, Idempotent Receiver.
Sequence
- Client app → REST API: GET /maximo/api/os/mxapiwodetail?oslc.where=…
- REST API → Security: API key and security group
- REST API → Object structure: Query
- Object structure → Maximo database: Select
- Maximo database → Object structure: Rows
- REST API → Client app: 200 JSON member[]
- Client app → REST API: POST … x-method-override: PATCH {status}
- REST API → Object structure: Update
- Object structure → Maximo database: Validate and save
- REST API → Client app: 200 or 204
- On failure: REST API → Client app: 400 oslc:Error with the BMXAA code
SOAP web services
Publish an object structure, enterprise service or Maximo method as a SOAP service. The Web Services Library creates a SOAP service with a WSDL from an object structure, an enterprise service, or a standard service that exposes a business-object method. Older middleware that speaks SOAP calls it.
Enterprise Integration Patterns: Request-Reply, Service Activator, Remote Procedure Invocation.
Sequence
- SOAP client → Web service: SOAP request (WSDL operation)
- Web service → Service behind it: Object structure, enterprise or standard service
- Service behind it → Maximo database: Apply or run the method
- Maximo database → Service behind it: Done
- Web service → SOAP client: SOAP response
- On failure: Web service → SOAP client: SOAP fault with the BMXAA message
Batch and file
Data Import (files)
Load XML or flat files into Maximo through an enterprise service. Files dropped in a folder are picked up on a schedule, or imported from External Systems, and each record goes through an enterprise service like any other inbound message, synchronously or through the queue.
Enterprise Integration Patterns: File Transfer, Polling Consumer, Splitter, Channel Adapter.
Sequence
- Source system → Import folder: Drop an XML or CSV file
- Import cron task → Import folder: Pick up the file
- Import cron task: Split into one message per record
- Import cron task → Enterprise service: Each record
- Enterprise service → Object structure: Apply
- Object structure → Import cron task: Saved
- On failure: Object structure → Enterprise service: A record fails
- On failure: Enterprise service → Message Reprocessing: Hold that record; the rest still load
Data Export
Send a selected set of existing records out through a publish channel. From External Systems you choose a publish channel and a filter, and Maximo publishes the matching records through the outbound queue to the channel’s end point, often an XML file. Used for initial loads and resyncs.
Enterprise Integration Patterns: Message Filter, File Transfer, Channel Adapter.
Sequence
- Administrator → External Systems: Data Export: channel and condition
- External Systems → Publish channel: Select the matching records
- Publish channel → Outbound queue: One message per record
- Outbound queue → End point (XML file): Consumer sends each message
- End point (XML file) → Output file: Write XML
- On failure: Output file → End point (XML file): Write fails
- On failure: Outbound queue → Message Reprocessing: Hold the message
Interface tables
Exchange records through database tables. Maximo creates a table per object structure. Outbound, it writes rows plus a transaction row in MXOUT_INTER_TRANS. Inbound, the other system writes rows plus a transaction row in MXIN_INTER_TRANS, and the IFACETABLECONSUMER cron task polls and applies them in transaction order.
Enterprise Integration Patterns: Shared Database, Polling Consumer, Guaranteed Delivery, Correlation Identifier.
Sequence
- External system → Interface table + MXIN_INTER_TRANS: Insert record row and transaction row (TRANSID)
- IFACETABLECONSUMER → Interface table + MXIN_INTER_TRANS: Poll new transactions in TRANSID order
- IFACETABLECONSUMER → Enterprise service: Apply each one
- Enterprise service → Object structure: Save
- Object structure → IFACETABLECONSUMER: Saved
- IFACETABLECONSUMER → Interface table + MXIN_INTER_TRANS: Clear the processed transaction
- On failure: Object structure → IFACETABLECONSUMER: Fails
- On failure: IFACETABLECONSUMER → Message Reprocessing: Hold with the error
Transport
End point handlers
How a message physically leaves or enters Maximo. An end point is a handler plus its settings. Handlers: HTTP, Web Service, JMS, XML file, flat file, interface table, EJB, command line and Kafka. A publish channel or invocation channel sends through the end point of its external system.
Enterprise Integration Patterns: Channel Adapter, Messaging Gateway, Message Endpoint.
Sequence
- Channel → End point: Message and end point name
- End point → Handler: Load properties: URL, method, timeouts
- Handler → Target: Deliver: HTTP, JMS, file, table or Kafka
- Target → Handler: Result
- Handler → Channel: Success
- On failure: Target → Handler: Error or timeout
- On failure: Handler → Channel: Exception: a queued message is held
Sequential and continuous queues
In order, one at a time, or in parallel. Sequential queues (sqin, sqout) are read by one cron consumer in arrival order: a failed message blocks the ones behind it. Continuous queues (cqin, cqout) are read by several consumers in parallel: faster, no order guarantee, and failures move aside to the error queue.
Enterprise Integration Patterns: Point-to-Point Channel, Guaranteed Delivery, Competing Consumers, Dead Letter Channel.
Sequence
- Producer → Sequential queue: M1, M2, M3
- One consumer → Sequential queue: Read M1
- One consumer: M2 waits until M1 is done
- Producer → Continuous queue: M1, M2, M3
- Several consumers → Continuous queue: Read M1, M2, M3 in parallel
- On failure: One consumer → Reprocessing / error queue: M1 fails: held, M2 and M3 wait
- On failure: Several consumers → Reprocessing / error queue: M2 fails: moved aside, the rest carry on
Kafka (Event Streams) message provider
Kafka topics in place of the JMS queues. On MAS, an external system can use Kafka (IBM Event Streams or another Kafka) as its message provider. Inbound and outbound queues become topics; Maximo produces to them and consumes from them. Messages stay on the topic for the retention period, so several systems can read the same stream and a consumer can replay from an earlier offset.
Enterprise Integration Patterns: Publish-Subscribe Channel, Competing Consumers, Message Store, Guaranteed Delivery, Event Message.
Sequence: Publish and consume
- Publish channel (producer) → Kafka topic: Produce the event, key = WONUM
- Kafka topic: Kept for the retention period; one key, one partition, so one work order stays in order
- Data platform group → Kafka topic: Read from its own offset
- ERP group → Kafka topic: Read the same event independently
- Maximo consumer → Kafka topic: Read the inbound topic
- Maximo consumer → Enterprise service: Apply
- Enterprise service → Maximo consumer: Saved: commit the offset
Sequence: Replay on failure
- Publish channel (producer) → Kafka topic: Events 101–105, key = WONUM
- ERP consumer group → Kafka topic: Poll from the committed offset 101
- ERP consumer group → ERP API: Apply 101 and 102
- ERP API → ERP consumer group: OK
- ERP consumer group → Kafka topic: Commit offset 103
- On failure: replay: ERP consumer group → ERP API: Apply 103
- On failure: replay: ERP API → ERP consumer group: 500 or unreachable
- On failure: replay: ERP consumer group: Retry with back-off; offset 103 is not committed, so nothing is lost
- On failure: replay: ERP consumer group: Stops, or parks 103 on a dead-letter topic so 104 and 105 keep flowing
- On failure: replay: Operator → ERP API: Fix the cause
- On failure: replay: Operator → Kafka topic: Reset the group offset to 103 (kafka-consumer-groups --reset-offsets --to-offset 103), within retention
- On failure: replay: ERP consumer group → Kafka topic: Re-read 103–105
- On failure: replay: ERP consumer group → ERP API: Apply again, idempotent by WONUM + message id
- On failure: replay: ERP API → ERP consumer group: OK
- On failure: replay: ERP consumer group → Kafka topic: Commit offset 106
When Maximo is the consumer, a message that fails to apply is held in Message Reprocessing and reprocessed there; with Kafka you can also replay it from the topic by resetting the Maximo consumer group, within the retention period.
Customisation points
Processing rules
No-code rules that skip, stop or change a message. Rules on a publish channel or enterprise service, per object in the structure: SKIP (drop the message or a record), STOP, SET, REPLACE, COMBINE and SPLIT, each with conditions that can read integration controls set per external system. MXWOInterface ships a SKIPWO rule that skips statuses not in the WOSTART control.
Enterprise Integration Patterns: Message Filter, Content Filter, Content Enricher, Content-Based Router, Splitter.
Sequence
- Channel or service → Processing rule: Message and current object
- Processing rule → Integration controls: Control values for this external system
- Integration controls → Processing rule: e.g. WOSTART statuses
- Processing rule: Evaluate the condition
- Processing rule → Next step: SET, REPLACE or COMBINE: changed message
- When a rule skips: Processing rule → Channel or service: SKIP or STOP: message dropped, not an error
Java user exits and processing classes
Java code at the boundaries of a message. Processing classes and user exit classes run at the external-system boundary (before and after the standard processing) and at the object-structure boundary. They translate, enrich, route or reject in Java. On MAS, automation scripts usually replace them.
Enterprise Integration Patterns: Message Translator, Content Enricher, Content-Based Router, Normalizer.
Sequence
- Channel or service → User exit (before): Message in the external format
- User exit (before) → Channel or service: Changed message
- Channel or service → Standard processing: Processing rules and mapping
- Standard processing → User exit (after): Message in the Maximo format
- User exit (after) → Object structure: Final message
- On failure: User exit (after) → Channel or service: Exception: message rejected
XSL maps
Reshape the XML to and from the other system’s format. An XSLT file on a publish channel or enterprise service turns Maximo’s XML into the receiver’s format, or the sender’s format into Maximo’s.
Enterprise Integration Patterns: Message Translator, Normalizer.
Sequence
- Publish channel → XSL map: PublishMXWO XML
- XSL map: Apply erp-wo.xsl
- XSL map → Publish channel: XML in the receiver’s format
- Publish channel → Receiver: Send
- On failure: XSL map → Publish channel: Transform error: message rejected
Integration automation scripts
JavaScript or Jython at the integration hooks. Scripts named for their hook: OSIN.{object structure} for inbound processing, OSOUT.{object structure} for outbound, PUBLISH.{channel}.EVENTFILTER to decide what is published, plus user-exit scripts on channels and services. All four recipes ran on Manage 9.2.197.
Enterprise Integration Patterns: Message Filter, Message Translator, Content Enricher, Content-Based Router.
Sequence
- Enterprise service → OSIN.MXWO: beforeProcess(ctx)
- OSIN.MXWO → Enterprise service: Site defaulted, or ctx.skipTxn()
- Enterprise service → Object structure: Apply
- Publish channel → PUBLISH…EVENTFILTER: Publish this record?
- PUBLISH…EVENTFILTER → Publish channel: evalresult false: publish
- Publish channel → OSOUT.MXWO: overrideValues(ctx)
- OSOUT.MXWO → Publish channel: STATUS goes out as APPROVED
- On failure: OSIN.MXWO → Enterprise service: Script error BMXAA7837E: message rejected
Operations
Message Tracking
A record of every message and its status history. With tracking switched on for an enterprise service or publish channel, Maximo keeps each message, its status (RECEIVED, PROCESSED, ERROR, DELETED) and the history of changes, searchable by key fields and external message ID.
Enterprise Integration Patterns: Message Store, Message History, Correlation Identifier, Wire Tap.
Sequence
- Service or channel → MAXINTMSGTRK: RECEIVED, with the stored message
- Service or channel → MAXINTMSGTRK: PROCESSED or ERROR, with history
- Support → Message Tracking: Search by key or external message ID
- Message Tracking → MAXINTMSGTRK: Read
- MAXINTMSGTRK → Message Tracking: Status and history
- Message Tracking → Support: What happened to the message
Message Reprocessing
Fix and replay messages that failed on a queue. Every queued message that fails waits here with the error, the message and the try count. You can edit the message and reprocess it, change it to HOLD or RETRY, or delete it. Manage holds a message after five tries.
Enterprise Integration Patterns: Dead Letter Channel, Invalid Message Channel, Control Bus.
Sequence
- Queue consumer → Message Reprocessing: Failed message with the error, try 1
- Support → Message Reprocessing: Open it and read the error
- Support → Message Reprocessing: Reprocess unchanged
- Message Reprocessing → Object structure: Apply
- Object structure → Message Reprocessing: Fails again: try 2
- Support → Message Reprocessing: Edit the message (P2 → 2)
- Message Reprocessing → Object structure: Apply the corrected message
- Object structure → Message Reprocessing: Saved: entry cleared
- If it keeps failing: Message Reprocessing: After five tries Manage sets HOLD
- If it keeps failing: Support → Message Reprocessing: Change status to RETRY, or delete
Enterprise Integration Patterns in Maximo
- File Transfer: Data Import and Data Export with XML or flat-file end points.
- Shared Database: Interface tables with MXIN_INTER_TRANS and MXOUT_INTER_TRANS.
- Remote Procedure Invocation: Synchronous enterprise services, REST, SOAP and invocation channels.
- Point-to-Point Channel: The JMS queues sqin, sqout, cqin and cqout.
- Publish-Subscribe Channel: A Kafka topic read by several consumer groups.
- Dead Letter Channel: Message Reprocessing and the continuous error queue.
- Invalid Message Channel: Message Reprocessing holds them with the BMXAA error.
- Guaranteed Delivery: Persistent JMS queues on the messaging engine store; Kafka retention.
- Channel Adapter: End point handlers: HTTP, JMS, file, interface table, Kafka.
- Document Message: Sync and Publish messages built from an object structure.
- Event Message: A publish channel message raised by a record event.
- Request-Reply: Invocation channels, synchronous enterprise services and REST.
- Correlation Identifier: messageID on responses; the external message ID field tracked per service.
- Canonical Data Model: The object structure: MXWO, MXASSET and the rest.
- Message Filter: Event filter scripts, SKIP processing rules, Data Export conditions.
- Content-Based Router: Rule conditions with integration controls per external system; user exits and scripts.
- Recipient List: One publish channel event goes to every external system that has the channel enabled.
- Splitter: A JSON array applied record by record (Manage 9.2); SPLIT rules; file imports.
- Aggregator: Built around Maximo: App Connect, an integration platform or Kafka Streams.
- Scatter-Gather: Built around Maximo in an integration platform, or a script calling several invocation channels.
- Process Manager: An integration platform; Maximo workflow coordinates the Maximo side.
- Message Translator: XSL maps, user exits, OSIN and OSOUT scripts.
- Content Enricher: SET and COMBINE rules, OSOUT scripts, invocation-channel responses.
- Content Filter: Object structure excluded attributes; field-level SKIP rules.
- Normalizer: An XSL map or user exit per external system into the same object structure.
- Message Endpoint: End points and the /meaweb and /maximo/api URLs.
- Messaging Gateway: Enterprise service URLs and end point handlers.
- Polling Consumer: JMSQSEQCONSUMER, IFACETABLECONSUMER and file import cron tasks; REST clients polling changedate.
- Event-Driven Consumer: The publish channel listener on record events; MDB consumers for continuous queues.
- Competing Consumers: Continuous queues; Kafka consumer-group members sharing partitions.
- Idempotent Receiver: AddChange and Sync actions, REST PATCH; the external message ID to spot repeats.
- Transactional Client: A message is applied in one Maximo transaction; a failure saves nothing.
- Service Activator: Standard services in the Web Services Library; REST actions (wsmethod).
- Control Bus: Enable or disable external systems, channels and listeners; cron tasks; Message Reprocessing HOLD and RETRY.
- Message Store: Message Tracking with the message stored; Kafka retention.
- Message History: Message Tracking status history (MAXINTMSGTRKDTL).
- Wire Tap: Message Tracking keeps a copy; a second Kafka consumer group.
Resilience patterns
- Circuit breaker: Stop calling a system that keeps failing, wait, then try again carefully, so failures do not pile up. Maximo has the switches a breaker needs: a sequential outbound queue already pauses at the first failure, and the external system, publish channel and listener can be disabled and enabled (the Control Bus).
- Retry with back-off: Try a failed message again later instead of losing it. Queued messages that fail are retried and held in Message Reprocessing with a try count; Manage moves a message to HOLD after five tries (seen on Manage 9.2.197). RETRY releases it.
- Timeout: Give up on a slow call so threads are not tied up. HTTP end points take CONNECTTIMEOUT and READTIMEOUT properties.
- Dead-letter queue: Move messages that cannot be processed somewhere safe for a person to fix. Message Reprocessing holds failed queued messages with the message, error and try count; continuous queues move failures to the error queue.
- Poison message handling: Stop one bad message from blocking everything behind it. On a sequential queue the next message waits behind a failed one until it is corrected, held or deleted (seen on Manage 9.2.197). Continuous queues move it aside and carry on.
- Idempotency / duplicate detection: Receiving the same message twice should not create two records. A second JSON post with the same key is refused with BMXAA4211E; a queued duplicate is held. XML AddChange and Sync actions and REST PATCH update instead of insert.
- Throttling / rate limiting: Protect Maximo from more traffic than it can take. Queues absorb bursts; the number of consumers and the cron frequency set the pace.
- Bulkhead: Isolate parts so one failure does not sink the rest. Separate queues per external system; MAS server bundles split UI, cron, reporting and integration (mea) work; JMS runs in its own server bundle.
- Ordered processing: Apply changes to the same record in the order they happened. Sequential queues apply in arrival order; continuous queues do not promise order.
- Replay: Send past messages again after a fix or to a new system. Message Reprocessing replays held messages; Data Export republishes selected records.
- Compensating action: Undo a step in another system when a later step fails, since there is no transaction across systems. Each Maximo message is its own transaction.