What is JSON Mapping ?
- JSON Mapping is an application in Integration Module
- A Mapper plugin com.ibm.tivoli.maximo.fdmbo.JSONMapperExit used as Processing Class (or External Exit) in Publish Channel or Enterprise Service
Why it is used ?
Used to convert messages of Maximo XML to JSON (Outbound) and JSON to Maximo XML (Inbound).
- JMS Queues
- Message Tracking & Message Reprocessing
- Enterprise Services
- Publish Channel
- JSON Mapping Application
- JMS Queues support JSON messages from Integration components like Enterprise Service or Publish Channel.
- Inbound JSON data is supported into JMS Queues using http/https end point or a direct update to JMS
- Not Supported - JSON data using Interface tables, Web Services or from a file upload
- Same JMS queue can be used for XML/JSON payload without any configuration
- Message driven Bean (MDB) and JMS Cron task psdi.iface.jms.JMSQueueCronTask will support the use of Selectors against queues with JSON data
- View Queue and Delete Queue that allows viewing or deleting of data in the queues will support messages in a JSON format
- JSON messages work for kafka topic because it takes payload of base64 encoded compressed xml/json messages
Message Tracking
Message Tracking will save the payload in JSON format for Enterprise Services and Publish Channels where JSON Map is implemented.
The Search and External Message IDs are supported using format - $.header.attributeID header is JSON object & attributeID is tag name with case sensitive
Sample JSON payload & its external message ID $.header.transactionId (case sensitive)
{
"header": {
"reportedAsOfDateTime": "2024-04-24T00:00:00+05:30",
"recordTotal": 1,
"transactionDateTime": "2024-04-29T03:30:00+05:30",
"transactionId": "4a262629c1134b1eafed7b81dd50a6b",
},
"data": {
"assets": [
{
"assetId": 10000056,
"assetLocationId": 10000062,
"assetCriticalityCode": 1,
"assetStatusCode": "OPERATING",
"assetStatusDate": "2022-06-06",
}
]
}
}
Message Reprocessing application supports both JSON and XML. Error Messages from Enterprise Services and Publish Channel with JSON Map can be viewed in the application as JSON.
Enterprise Service
JSON Mapping for Enterprise Services can be used in a couple of scenarios: Asynchronous where ES is invoked with an inbound JSON message persisted to an inbound JMS queue or Synchronous http/https Call without JMS queue as an outbound response.
Enterprise Service using JSON Mapping need to have Processing Class (External Exit) com.ibm.tivoli.maximo.fdmbo.JSONMapperExit or a Java class extending this class. This processing class is needed for both request and response side.
The mime type of content-type header parameter should be "application/json".
Publish Channel
JSON Mapping for Publish Channel to convert outbound XML message into JSON is used in scenarios: Data is pushed out by an Event/Data Export or triggered from an incoming message of an enterprise service (customization in java/scripting for Event Filter class is used to enable response to incoming message).
A JSON message placed in outbound queue can be processed by End points: HTTP/JMS/XML file. The XML file end point will create a file in JSON format.
JSON Mapping application is used for creation and configuration of a JSON Map used for Integration messages.
This application has fields for
Mapping: This field need to be entered as per the Maximo naming convention for different Integration points.
- ExternalSytemName.EnterpriseServiceName.IN
- ExternalSytemName.EnterpriseServiceName.RESPONSE (Outbound)
- ExternalSytemName.PublishChannelName.OUT
Object Structure: Object Structure of type INTEGRATION to map the JSON data
Direction: Inbound or Outbound Processing
End Point: Existing HTTP End point for JSON payload
URL: URL will be used to retrieve the sample JSON data for configuration.
End point or URL should be able to access the sample JSON payload and populate the data in JSON document section. We are also allowed to manually enter the JSON data. It is recommended to have the content in simple editor like notepad before pasting in JSON document section as directly putting the content from browser will have junk character and cause problems on the mapping configuration.
JSON Mapping Properties
Once we have pasted the content of the JSON data, we can proceed on the JSON object and its attribute mapping in the Properties tab of JSON Mapping application.
The JSON Mapping can be performed for Inbound and Outbound messages.
Inbound JSON Message to Maximo XML mapping:
Please refer the steps documented in the reference link.
Maximo XML Message to Outbound JSON mapping:
We read the Interface specification document to know the expected JSON outbound message expected by external system.
for example, we paste the sample message in JSON document section.
{
"header": {
"reportedAsOfDateTime": "2024-04-24T00:00:00+05:30",
"recordTotal": 1,
"transactionDateTime": "2024-04-29T03:30:00+05:30",
"transactionId": "4a262629c1134b1eafed7b81dd50a6b",
},
"data": {
"assets": [
{
"assetId": 10056,
"assetLocationId": "POWERHOUSE",
"assetCriticalityCode": 1,
"assetStatusCode": "OPERATING",
"assetStatusDate": "2024-08-08"
},
{
"assetId": 10058,
"assetLocationId": "GARAGE",
"assetCriticalityCode": 1,
"assetStatusCode": "DISPOSED",
"assetStatusDate": "2024-08-08",
"disposalDate": "2024-06-06",
}
]
}
}
Some rules to consider:
assetStatusDate - date format should be yyyy-MM-dd
disposalDate - this field should be present only if assetStatusCode is DISPOSED or REPAIRED
assetLocationId - this value should be within an array even though we have single value in Maximo
Object Structure for this sample message is configured without any alias conflict:
In the Properties tab, we set the JSON Object Mapping first.
JSON Properties for Object Attributes:
Process Order 1 and 3 are for header section only.
Simple Maximo XML field to JSON tag mapping
Formatting for Date field mapping
Conditional Values: Disposed Date field should be set only for statuses [DISPOSED & REPAIR]
We can have multiple conditions for the mapping of one field.
Valid Condition Syntax must align with JavaScript Notation.
attr$STATUS=="DISPOSED" || attr$STATUS=="REPAIR"
attr$STATUS=="DISPOSED" && attr$STATUS=="REPAIR"
Limitations
- Maximo accepts Array for JSON Objects level, but not at JSON Attribute level. So if the external system needs a JSON value within an Array, we need to convert it in User Exit class. for example, "location":["30045", "56789" , "67890"] It is considered as a single value and can't be pared in Maximo.
- JSON Map is not supported for Invocation Channel
References:
