Prerequisites

The prerequisites to set up the MQ-based integration between IBM Sterling® Order Management System and an external system are listed in this topic.

The customer's remote public IP addresses must be enabled by IBM. For more information, see Information for network firewall policy. When connectivity to IBM Sterling Order Management System is through a VPN or direct link, enablement of domain or IP is not required. To test whether the connection to IBM Sterling Order Management System MQ QMGR and the MQ QMGR listening port is available execute telnet, nc, nmap or similar commands. Refer the following examples:
```
telnet <client>-oms.<environment>.coc.ibmcloud.com 1415
nc -v <client>-oms.<environment>.coc.ibmcloud.com 1415
nmap -sT <client>-oms.<environment>.coc.ibmcloud.com -p 1415
```
The MQI channel uses the IBM Sterling Order Management System MQ Server Self-Signed SSL certificate for channel authentication/message encryption. The SSL certificate can be downloaded from the IBM Cloud Dropbox or from the SI DEV Team IBM Box area.
To test and confirm the IBM Sterling Order Management System-MQ connectivity and functionality, it is strongly recommended that the standard IBM MQ Client is installed by SI Team on customer integration points.
Note: MQ Explorer is not supported.

The IBM MQ Client configuration needs to be as follows:


    JMS Server Type :  IBM MQ
    Connection Type :  Single Connection
    Hostname : OMoC public domain name or public IP                                            
               <cust>-oms.<env>.coc.ibmcloud.com
    Port : 1415
    Queue Manager : OM_QMGR
    Channel : SYSTEM.SSL.SVRCONN
    Use SSL : Yes
    SSL Cipher : TLS_RSA_WITH_AES_128_CBC_SHA256

where, Hostname env = dev, qa, preprod, prod.

Note: This configuration is for the IBM MQ Client. For third-party middleware there may be a need to amend SSL cipher entries where needed. Consult third-party middleware documentation for necessary Java class libraries and cipher specs for IBM MQ SSL compatibility.

As part of client integration with the IBM Sterling Order Management System platform, where the default MQ Client channel is used, you must specify certain MQ message header parameters and values to ensure that the IBM Sterling Order Management System can consume and process the messages placed in the client-created queues. IBM Sterling Order Management System is configured to consume text-based messages. The format of the messages should be: Format : 'MQSTR'

It is strongly recommended that SI teams use the standard MQ Client to browse messages in queues where the header details can be seen. An example of a correctly formed header for IBM Sterling Order Management System consumption is as follows:


StrucId : 'MD ' Version : 2
Report  : 64 MsgType : 8
Expiry  : -1 Feedback : 0
Encoding : 273 CodedCharSetId : 1208
Format : 'MQSTR'
Priority : 5 Persistence : 1
MsgId : X'414D51204F4D5F514D47522020202020520CB65BE5F15A2C'
CorrelId : X'D34DF8E3CE78FDD69E6FFE386B8FDB7F4EBF73D7766F8F77'
BackoutCount : 0
ReplyToQ : '       '
ReplyToQMgr : 'OM_QMGR'

Table 1. Message descriptors
Field	Description
`StrucId`	Identifier for message descriptor structure. Should be set to `MD`.
`Version`	This is the structure version number and should be set to 2.
`MsgType`	This indicates the type of the message. A value of 8 indicates that it is of type `MQMT_DATAGRAM`, which means the message does not require a reply. For information about other message types, see MQMT_* (Message Types)
`Expiry`	This is a period of time expressed in tenths of a second and set by the application that puts the message. The message can be discarded if it is not removed from the destination queue before this period elapses. For more information, see Expiry (MQLONG). A value of -1 means that the message never expires.
`Feedback`	This field is used for a message of type `MQMT_REPORT` to indicate the nature of the report, and is only meaningful with that type of message. It should be set to 0 which means that no feedback will be provided. For more information, see Feedback (MQLONG)
`Encoding`	This specifies the numeric encoding of numeric data in the message. It does not apply to numeric data in the `MQMD` structure itself. The numeric encoding defines the representation used for binary integers, packed-decimal integers, and floating-point numbers. `MQENC_NATIVE` is the default encoding for the programming language and machine on which the application is running. Note: The value of this constant depends on the programming language and environment. For this reason, applications must be compiled using the header, macro, `COPY`, or `INCLUDE` files that are appropriate to the environment in which the application will run. Applications that put messages usually specify `MQENC_NATIVE`. Applications that retrieve messages must compare this field against the value of `MQENC_NATIVE`. If the values differ, the application might need to convert numeric data in the message. Use the `MQGMO_CONVERT` option to request the queue manager to convert the message while processing the `MQGET` call. `MQENC_NATIVE` constant is defined here. Look up the correct value for your operating system.
`CodedCharSetId`	This field specifies the character set identifier of character data within the message body. Set it to 1208 for UTF-8 . For other character sets, follow this technote to determine the CCSID.
`Format`	This is a name that the sender of the message uses to indicate the nature of the data in the message to the receiver. Set it to `MQSTR` to mimic the behavior of a `JMSTextMessage`. For more information, see Format (MQCHAR8) For a list of formats, see -MQFMT_* (Formats)
`Priority`	Set the priority of a message in this field when you PUT the message in a queue. You can set a numeric value for the priority, or you can let the message take the default priority of the queue. The `MsgDeliverySequence` attribute of the queue determines whether messages in the queue are stored in FIFO (first in, first out) sequence, or in FIFO within priority sequence. If this attribute is set to `MQMDS_PRIORITY`, messages are enqueued with the priority specified in the Priority field of their message descriptors. If this attribute is set to `MQMDS_FIFO`, messages are enqueued with the default priority of the queue. Messages of equal priority are stored in the queue in the order of arrival. By default, in IBM Sterling Order Management System environments, the following values are present for each defined queue: `DEFPRTY(0) MSGDLVSQ(PRIORITY)` Messages can be created with priorities between 0 (the lowest) and 9 (the highest). For the `MQPUT` and `MQPUT1` calls, the value must be greater than or equal to 0, which indicates the lowest priority. Set it to 5 to mimic the behavior of `JMSTextMessage`. For more information, see Priority (MQLONG)
`Persistence`	This field indicates whether the message survives system failures and restarts of the queue manager. Set it to 1 to ensure that the message survives system failures and restarts of the queue manager. For more information, see Persistence (MQLONG). For information on the list of allowed values, see MQPER_* (Persistence Values)
`MsgId`	This is a byte string that is used to distinguish one message from another. Generally, no two messages should have the same message identifier, although this is not disallowed by the queue manager. The message identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the message identifier is a byte string and not a character string, the message identifier is not converted between character sets when the message flows from one queue manager to another. For more information, see MsgId (MQBYTE24)
`CorrelId`	This field is property in the message header that might be used to identify a specific message or group of messages. This is a byte string that the application can use to relate one message to another, or to relate the message to other work that the application is performing. The correlation identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the correlation identifier is a byte string and not a character string, the correlation identifier is not converted between character sets when the message flows from one queue manager to another.
`BackoutCount`	This is a count of the number of times the message is previously returned by the `MQGET` call as part of a unit of work, and subsequently backed out. It helps the application to detect processing errors that are based on message content. The initial value of this field is 0. For more information, see BackoutCount (MQLONG)
`ReplyToQ`	This is the name of the message queue to which the application that issued the `GET` request for the message sends `MQMT_REPLY` and `MQMT_REPORT` messages. If the `ReplyToQMgr` field is blank, the local queue manager looks up the `ReplyToQ` name in its own queue definitions. For more information, see ReplyToQ (MQCHAR48)
`ReplyToQMgr`	This is the name of the queue manager to which the reply message or report message must be sent. For more information, see ReplyToQMgr (MQCHAR48)