# Native IBM® MQ ## Quick start Have a look at the [quick start to Traffic Parrot](https://trafficparrot.com/documentation/5.65.x/start.html). It covers HTTP only, but it will show you how to install the tool and explain a few basic concepts. To stand in for the IBM® MQ CICS bridge, answering and recording CICS DPL requests with your COBOL copybooks, see [CICS over IBM® MQ](https://trafficparrot.com/documentation/5.65.x/cics.html), which builds on this page. ## JMS vs. Native IBM® MQ Traffic Parrot supports IBM® MQ brokers via JMS and native IBM® MQ APIs. If you are connecting to the IBM® MQ broker via JMS, please use JMS in Traffic Parrot as well and follow [the JMS IBM® MQ instructions](https://trafficparrot.com/documentation/5.65.x/jms.html#ibm-mq-libs). If you are using native IBM® MQ APIs, please follow the instructions below. ## IBM® MQ virtual service architecture A tester or developer uses a web browser to access the console. The console manages the virtual service. The system under test (application under test) connects directly to the virtual service on different ports. Here is an example of how that could look like for a scenario where the virtual service is replaying messages to an external queue. [![Mocking IBM MQ architecture](https://trafficparrot.com/documentation/5.65.x/img/mq/MQ_architecture.png)](https://trafficparrot.com/documentation/5.65.x/img/tp/architecture-replay-jms-queue.png) Virtual service replaying IBM® MQ messages to and from a queue ## Configuration ##### Define connections To record from or replay to brokers you will need to tell Traffic Parrot how to connect to them. Those connections are displayed in the dropdown menus on the record and replay panels, for example: ![screenshot](https://trafficparrot.com/documentation/5.65.x/img/mq/mq-connection-dropdown.png) To define a new connection that will be available in the dropdown in the record and replay panels: 1. Open `ibm-mq-connections.json` file located in the main Traffic Parrot directory, using your [favourite](https://trafficparrot.com/documentation/5.65.x/faqs.html#favourite-editor) text editor 2. Add the new connections (make sure the connectionId field has a unique value!). An example content of the file, with 2 connections defined: ``` [ { "connectionId": "1", "connectionName": "Test Payments Broker", "connectionData": { "ibmMqVersion": "IBM_MQ_7_5", "hostname": "mqserver.example.com", "port": 1415, "queueManager": "PAYMENT.QM", "channel": "PAYMENT.SVRCONN", "username": "payuser", "password": "paypassword222", "useMQCSPAuthenticationMode": true, "readConnectionsToOpen": 1, "writeConnectionsToOpen": 1, "sslCipherSuite": null, "sslPeerName": null } }, { "connectionId": "2", "connectionName": "Local docker MQ 9", "connectionData": { "ibmMqVersion": "IBM_MQ_9", "hostname": "localhost", "port": 1414, "queueManager": "QM1", "channel": "DEV.APP.SVRCONN", "username": "app", "password": "MQ_APP_PASSWORD", "useMQCSPAuthenticationMode": true, "readConnectionsToOpen": 1, "writeConnectionsToOpen": 1, "sslCipherSuite": null, "sslPeerName": null } } ] ``` 3. IBM MQ username and password are interpreted as `null` if set to `""` or `"null"` in the connection JSON configuration - To configure a `""` value use `""` - To configure a `"null"` value use `""` 4. Supported values of `ibmMqVersion` are `IBM_MQ_7_5`, `IBM_MQ_8` or `IBM_MQ_9` 5. Set the value of `useMQCSPAuthenticationMode` to `true` if you require [MQCSP authentication mode](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_8.0.0/com.ibm.mq.sec.doc/q118680_.htm) when connecting (e.g. for passwords longer than 12 characters) 6. Save the file 7. Refresh the page in Traffic Parrot to reload the dropdown list. In the current Traffic Parrot version you edit connections directly in the `ibm-mq-connections.json` file. In near future you will be able to do it via the Web UI as well. ###### Change the location of ibm-mq-connections.json If you would like to change the location of the `ibm-mq-connections.json` file, [change the value of property](https://trafficparrot.com/documentation/5.65.x/user_guide.html#properties) ``` trafficparrot.virtualservice.ibmMqConnectionsUrl=classpath:ibm-mq-connections.json ``` to for example ``` trafficparrot.virtualservice.ibmMqConnectionsUrl=file:/home/john/git/project/trafficparrot-ibm-mq-connections.json ``` This can be useful if you would like to version control it with your application source code. ##### More than one queue manager To mock several queue managers from one Traffic Parrot, for example one per test environment, each with mappings of its own, give each its own [virtual service](https://trafficparrot.com/documentation/5.65.x/virtual_services.html#vs-configuration-native-ibm-mq): a folder `scenarios//` with its own `ibm-mq-connections.json`, its own `ibm-mq-mappings` and a `service.properties` naming the queue manager it consumes requests from and replies on. Each virtual service answers only on its own queue manager, so two environments can use the same queue names and still get different replies. The [worked example](https://trafficparrot.com/documentation/5.65.x/virtual_services.html#vs-configuration-jms-example) on the Virtual Services page uses JMS; a native IBM® MQ virtual service is set up the same way with the [native IBM® MQ keys](https://trafficparrot.com/documentation/5.65.x/virtual_services.html#vs-configuration-native-ibm-mq). To serve several queue managers with one set of mappings, so that every queue manager gets the same replies, use a [replay script](#replay_script) instead. ##### Required JARs To connect to IBM® MQ you need jar files provided by IBM that will allow Traffic Parrot to establish connections with MQ. Before you proceed please read [these instructions](http://www-01.ibm.com/support/docview.wss?uid=swg21376217) to double check your actions are inline with the supported way to install WebSphere MQ Java jar files. You will need: - `com.ibm.mq.jakarta.client.jar` If you do not have the required JAR file yet, download the Jakarta client JAR library from [the Maven Central repository](https://mvnrepository.com/artifact/com.ibm.mq/com.ibm.mq.jakarta.client/), for example [com.ibm.mq.jakarta.client-10.0.0.5.jar](https://repo1.maven.org/maven2/com/ibm/mq/com.ibm.mq.jakarta.client/10.0.0.5/com.ibm.mq.jakarta.client-10.0.0.5.jar). > **Upgrading from a previous version of Traffic Parrot?** Replace `com.ibm.mq.allclient.jar` with `com.ibm.mq.jakarta.client.jar` in your `lib/external/` folder. Existing javax.jms plugins continue to work without source changes. Note: support for javax-based plugins will be removed in a future major release; migrating your plugins to jakarta.jms is recommended as a next step. > **Will my existing javax-based client applications still connect to Traffic Parrot?** **Yes.** The `javax.jms` → `jakarta.jms` change is an *API-level rename* only; the underlying IBM® MQ wire protocol is unchanged. Your customer applications built against `javax.jms` (with IBM's `com.ibm.mq.allclient.jar`) send the same bytes on the wire as applications built against `jakarta.jms` (with `com.ibm.mq.jakarta.client.jar`). Traffic Parrot using the Jakarta client will accept connections from javax clients, jakarta clients, .NET clients, and native MQI clients against the same queue manager, with no client-side changes required. See the [IBM MQ Classes for Jakarta Messaging overview](https://www.ibm.com/docs/en/ibm-mq/latest?topic=messaging-mq-classes-jakarta-overview) for background. If you have any issues with obtaining the jar files please [contact us](https://trafficparrot.com/documentation/5.65.x/faqs.html#email-help). Copy those files to `trafficparrot-x.y.z/lib/external` and restart Traffic Parrot. ##### Startup replay script The following property allows to specify a replay IBM® MQ script that will be run on startup ``` trafficparrot.ibmmq.start.queue.replay.on.startup.script=classpath:start-ibmmq-queue-replay-on-startup.txt ``` The script is in the same format as the one used in the [web user interface.](#replay_script) ##### Connect to the queue manager via SSL/TLS channels To connect Traffic Parrot Native IBM MQ to an SSL/TLS channel, you need to configure the cipher suite and provide the certificates. To configure the cipher suite, you need to update the connection definition in the `ibm-mq-connections.json` file, for example below we set the `sslCipherSuite` to `TLS_RSA_WITH_AES_128_CBC_SHA`: ``` [ { "connectionId": "1", "connectionName": "Local Docker MQ 9", "connectionData": { "ibmMqVersion": "IBM_MQ_8", "hostname": "localhost", "port": 2414, "queueManager": "QM1_V8", "channel": "DEV.APP.SVRCONN.SSL", "username": "app", "password": "MQ_APP_PASSWORD", "useMQCSPAuthenticationMode": true, "readConnectionsToOpen": 1, "writeConnectionsToOpen": 1, "sslCipherSuite": "TLS_RSA_WITH_AES_128_CBC_SHA", "sslPeerName": "OU=TP IBM MQ" } } ] ``` In the example above we are also configuring the `sslPeerName` which allows us to validate the server certificate DN. To provide the server and client certificates, we will use a trust store and key store. The trust store should contain all certificates, be it CA or direct public keys to validate the IBM MQ queue manager certificate. The key store should include a client certificate that when requested by the IBM MQ queue manager SSL channel is signed by the approved issuer. The key store should also contain a private key associated with the client certificate. You can configure both of these in the `jvm.args` file by adding at the bottom: ``` -Djavax.net.ssl.trustStore=certificates/ca-chain.jks -Djavax.net.ssl.trustStorePassword=trafficparrot -Djavax.net.ssl.keyStore=certificates/mq-client.jks -Djavax.net.ssl.keyStorePassword=trafficparrot -Dcom.ibm.mq.cfg.useIBMCipherMappings=false ``` For the example above to work, you will need to create the `certificates/ca-chain.jks` and `certificates/mq-client.jks` JKS files with the required certificates in them. Below you can find sample content of the trust store and the key store. In our example, the trust store contains a certificate authority chain of 2 certificates. The intermediate ca was used to sign both client and the IBM MQ queue manager certificates. The key store contains the client private key and a certificate signed by the intermediate ca. ``` trafficparrot@trafficparrot-pcs:~/Downloads/tp/trafficparrot-linux-x64-jre$ keytool -list -keystore certificates/ca-chain.jks Enter keystore password: Keystore type: jks Keystore provider: SUN Your keystore contains 2 entries intermediateca, 13-Jul-2020, trustedCertEntry, Certificate fingerprint (SHA1): 2E:FB:4F:8A:44:89:CD:FB:EE:25:5B:78:D0:D8:9B:89:A8:1E:1C:9E rootca, 13-Jul-2020, trustedCertEntry, Certificate fingerprint (SHA1): 13:D1:98:09:59:66:C7:64:F0:78:C3:8C:C1:C2:68:9D:76:F0:CF:34 trafficparrot@trafficparrot-pcs:~/Downloads/tp/trafficparrot-linux-x64-jre$ keytool -list -keystore certificates/mq-client.jks Enter keystore password: Keystore type: jks Keystore provider: SUN Your keystore contains 1 entry 1, 13-Jul-2020, PrivateKeyEntry, Certificate fingerprint (SHA1): 21:9B:F6:A4:12:B0:31:1E:D6:29:B5:D3:C4:19:6F:ED:E4:C3:50:C2 ``` ##### Performance monitoring You can enable additional logging that displays total processing time of messages. To enable set property: ``` trafficparrot.ibmmq.monitorPerformance=true ``` You should then see INFO log lines that contain `"Total processing time"`, for example: ``` 2026-10-07 08:28:43,686 INFO DEV.QUEUE.1-replay-responses-ibm-mq-message-scheduler-0 Request message '414D5120514D312020202020202020202E3C455F02FFE524' was received on '2026-10-07T07:28:43.670568865Z' from 'QUEUE:DEV.QUEUE.1'. Request message putDateTime is '2026-10-07T07:28:43.640Z'. Response message '414D5120514D312020202020202020202E3C455F02FEE524' was sent on '2026-10-07T07:28:43.686505432Z' to 'QUEUE:DEV.QUEUE.2'. Total processing time 15ms ``` You can increase the logging level by setting it to DEBUG or TRACE, change `trafficparrotserver.log4j.properties` (last line in the file): ``` log4j.category.com.trafficparrot.messaging.ibmmq.connection.monitor.ReportingIbmMqPerformanceMonitor=DEBUG ``` ## Recording and replaying IBM® MQ ### Introduction As with HTTP recording Traffic Parrot, during recording incoming and outgoing messages are matched up to provide mappings. Then upon playback receipt of a matching incoming message will trigger generation of an outgoing message. Before you proceed to recording or replaying messages make sure you have [installed the required libraries (required JARs)](#ibm-mq-libs) so that Traffic Parrot can connect to the broker. ### Message matching Traffic Parrot can form mappings in a number of ways. - Time: pair messages in the order they happened in time - Correlation ID: pair messages with matching correlation id The default is to use time based matching. This can be changed in the advanced parameter section of the record page. ### Configuration steps overview Please see the diagram below for an overview of the steps required for configuring recording of messages between existing systems. ![MQ recording configuration steps overview](https://trafficparrot.com/documentation/5.65.x/img/mq/queue-record-steps.png) ### Recording and replaying IBM® MQ queues using an external broker Traffic Parrot does not support running IBM® MQ internally. You will need to use an external broker. You can use one of the following: - You probably already have a test environment where there is a IBM® MQ broker available. You can use that IBM® MQ instance to set up your virtual service queues, which we have [described below](#recording-mq-queues-external). - You can run a developer edition of IBM® MQ using [Docker](https://www.docker.com/) on your laptop, for more information see [IBM® MQ for Developers](https://github.com/ibm-messaging/mq-container) (image `icr.io/ibm-messaging/mq`) This diagram shows how two production systems connect: ![Systems communicating via queues](https://trafficparrot.com/documentation/5.65.x/img/jms/systems-comunicating-via-queues.png) One system generates messages onto a queue; another system consumes these messages and puts responses onto a second queue, which the first system consumes. If our goal is to test the system-under-test in isolation, we must record these interactions in order to replay them. ### Recording IBM® MQ queues using an external broker We will create extra queues on the existing broker that will be used by the virtual service. Then we will reconfigure the system-under-test to connect to these queues instead of the original ones. Traffic Parrot will move messages between these queues and the original queues, recording and creating mappings as it does so. ![screenshot](https://trafficparrot.com/documentation/5.65.x/img/jms/recording_queue_messages_using_an_external_broker.png) ##### Steps to perform a queue recording using an external broker 1. Add the queues that will be used by the virtual service to the broker. In the example above you would add to the existing broker queues "Virtual Service Request Queue" and "Virtual Service Response Queue". 2. [Define connections](#define-connections) that will be used for recording 3. [Start](https://trafficparrot.com/documentation/5.65.x/user_guide.html#start-and-stop) Traffic Parrot 4. Go to the [IBM® MQ record page](http://localhost:8080/ibmMq/record.html) 5. Select "External" in the "Broker" panel 6. Select "Queue" 7. Choose the connections to brokers, and specify the queue name where messages will be received and responses sent. Follow the diagram [Configuring recording queue messages using an external broker](#configuring_recording_queue_messages_using_an_external_broker) which will guide you how to populate those fields. 8. Click "Turn on" 9. Reconfigure System A to connect to the virtual service queues 10. Execute a test case via System A to allow Traffic Parrot to record requests and responses. They will appear on the Messages and Mappings lists on the web page as shown on [Mappings and messages lists during recording](#mappings-and-messages-lists-during-queue-recording) image. 11. Click "Turn off" ![screenshot](https://trafficparrot.com/documentation/5.65.x/img/jms/configuring_recording_queue_messages_using_an_external_broker.png) As the system-under-test generates messages they are listed in the bottom table 'Current recording session'. As the second system generates responses to these messages, they are also listed at the bottom, but in addition mappings are generated in the 'Mappings' table showing incoming and outgoing messages that Traffic Parrot has paired up. ![Mappings and messages lists during a IBM® MQ recording](https://trafficparrot.com/documentation/5.65.x/img/mq/mappings-and-messages-lists-during-queue-recording.png) ### Replaying IBM® MQ queues using an external broker To replay the recorded mappings we will need the same virtual service queues in place as shown on the image below. ![Replaying queue messages using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/replaying_queue_messages_using_an_external_broker.png) ##### Steps to perform a queue replay using an external broker 1. Add the queues that will be used by the virtual service to the broker. In the example above you would add to the existing broker queues "Virtual Service Request Queue" and "Virtual Service Response Queue" (Note - depending on your broker and it's configuration these queues may be auto-created for you when the software first attempts to connect.) 2. [Start](https://trafficparrot.com/documentation/5.65.x/user_guide.html#start-and-stop) Traffic Parrot 3. Go to the [IBM® MQ replay page](http://localhost:8080/ibmMq/replay.html) 4. Select "External" in the "Broker" panel 5. Select "Queue" 6. De-select "Topic" 7. Choose the connections as shown on the [Configuring recording queue messages using an external broker](#configuring_replaying_queue_messages_using_an_external_broker) diagram. 8. Click "Turn on" 9. Reconfigure System A to connect to the virtual service broker 10. Execute a test case via System A to allow Traffic Parrot to consume a request message and send a response message. 11. Click "Turn off" ![Configuring replaying queue messages using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/configuring_replaying_queue_messages_using_an_external_broker.png) ### Recording and replaying IBM® MQ model queues using an external broker Traffic Parrot does not support running IBM® MQ internally. You will need to use an external broker. You can use one of the following: - You probably already have a test environment where there is a IBM® MQ broker available. You can use that IBM® MQ instance to set up your virtual service queues, which we have [described below](#recording-mq-queues-external). - You can run a developer edition of IBM® MQ using [Docker](https://www.docker.com/) on your laptop, for more information see [IBM® MQ for Developers](https://github.com/ibm-messaging/mq-container) (image `icr.io/ibm-messaging/mq`) This diagram shows how two production systems connect when using model queues: ![MQ model queues communication](https://trafficparrot.com/documentation/5.65.x/img/mq/model-queues-communication.png) One system obtains a temporary queue based on a model queue. It puts messages onto a request queue with the ReplyToQ set to the temporary queue. Another system consumes these messages and puts responses onto the temporary queue that was in the ReplyToQ field, which the first system consumes. If our goal is to test the system-under-test in isolation, we must record these interactions in order to replay them. ### Recording IBM® MQ model queues using an external broker We will create an extra request queue on the existing broker that will be used by the virtual service. Then we will reconfigure the system-under-test to connect to this request queue instead of the original one. Traffic Parrot will move messages between the virtual and original request queue, recording and creating mappings as it does so. Both the system-under-test and the virtual service will use a model queue that exists on the existing broker. This model queue will be used to create a dynamic response queue. Traffic Parrot will move messages between the virtual and original dynamic queue, recording and creating mappings as it does so. ![MQ model queues recording](https://trafficparrot.com/documentation/5.65.x/img/mq/record-model-queues.png) Steps to record are similar to the [usual recording steps](#mq-record-external-steps) but the response queues selected should be the same model queue name that exists in the external broker. In addition, the advanced parameter "Model response queues" should be set to "Yes": ![Advanced recording parameters](https://trafficparrot.com/documentation/5.65.x/img/mq/advanced-recording-parameters.png) ### Replaying IBM® MQ model queues using an external broker To replay the recorded mappings we will need the same virtual service queues in place as shown on the image below. ![MQ model queues replay](https://trafficparrot.com/documentation/5.65.x/img/mq/replay-model-queues.png) Steps to replay are the same as the [usual replay steps](#mq-replay-external-steps). Response messages will be sent to the queue mentioned in th ReplyToQ field of the request message. ### Recording and replaying IBM® MQ topics using an external broker Recording and playback of topics using an external broker is less intrusive than queues because Traffic Parrot can subscribe to a topic just like any other application and receive messages, without affecting the delivery of those messages to other applications. This diagram shows how the production systems connect: ![Systems communication with topics](https://trafficparrot.com/documentation/5.65.x/img/jms/systems_communication_with_topics.png) The system-under-test generates messages onto a topic which are received by a number of other systems. One of these systems generates responses onto a different topic (which are received by a number of systems, one of which is the system-under-test). ### Recoding IBM® MQ topics using an external broker We will configure Traffic Parrot to connect to the request and response topics and record the messages appearing on both, generating mappings as it goes, as shown on diagram [Recording topics using an external broker](#recording_topics_using_an_external_broker) ![Recording topics using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/recording_topics_using_an_external_broker.png) ##### Steps to perform a topic recording using an external broker 1. [Define IBM® MQ connections](#define-connections) that will be used for recording 2. [Start](https://trafficparrot.com/documentation/5.65.x/user_guide.html#start-and-stop) Traffic Parrot 3. Go to the [IBM® MQ record page](http://localhost:8080/ibmMq/record.html) 4. Select "External" in the "Broker" panel 5. Select "Topic" 6. Choose the connections to brokers, and specify the topic names where messages will be received and responses sent. Follow the diagram [Configuring recording topics using an external broker](#configuring_recording_topics_using_an_external_broker) which will guide you how to populate those fields. 7. Click "Turn on" 8. Reconfigure System A to connect to the virtual service queues 9. Execute a test case via System A to allow Traffic Parrot to record requests and responses. They will appear on the Messages and Mappings lists on the web page as shown on [Mappings and messages lists during recording](#mappings-and-messages-lists-during-topic-recording) image. 10. Click "Turn off" ![Configuring recording topics using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/configuring_recording_topics_using_an_external_broker.png) As the system-under-test generates messages they are listed in the bottom table 'Current recording session'. As the second system generates responses to these messages, they are also listed at the bottom, but in addition mappings are generated in the 'Mappings' table showing incoming and outgoing messages that Traffic Parrot has paired up. ![Mappings and messages lists during IBM® MQ topic recording](https://trafficparrot.com/documentation/5.65.x/img/mq/mappings-and-messages-lists-during-topic-recording.png) #### Replaying IBM® MQ topics using an external broker When replaying to an external broker Traffic Parrot will subscribe to the request topic and publish to the response topic as shown in the diagram [Replaying topic messages using an external broker](#replaying_topics_using_an_external_broker). ![Replaying topic messages using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/replaying_topics_using_an_external_broker.png) ##### Steps to perform a topic replay using an external broker 1. [Start](https://trafficparrot.com/documentation/5.65.x/user_guide.html#start-and-stop) Traffic Parrot 2. Go to the [IBM® MQ replay page](http://localhost:8080/ibmMq/replay.html) 3. Select "External" in the "Broker" panel 4. Select "Topic" 5. De-select "Queue" 6. Choose the connection as shown on the [Configuring replaying topics messages using an external broker](#configuring_replaying_topics_messages_using_an_external_broker) diagram. 7. Click "Turn on" 8. Disconnect System B from the broker so it does not produce response messages to the response topic 9. Execute a test case via System A to allow Traffic Parrot to consume a request message and send a response message. 10. Click "Turn off" ![Configuring replaying topics messages using an external broker](https://trafficparrot.com/documentation/5.65.x/img/jms/configuring_replaying_topics_using_an_external_broker.png) #### Recording multiple queues If you would like to record multiple queues at the same time, please use the recording script. See [recording using a script](#recording_script) for more details. #### Recording using a script You can use the "Script" tab to record advanced setups of multiple queues on multiple queue managers. ![Recording using a script](https://trafficparrot.com/documentation/5.65.x/img/mq/native-ibmmq-script-recording.png) Here is an example script to record multiple queues at the same time. ``` # # This is a sample comment # QueueManager:'Local Docker MQ 9' ProxyRequestQueue:'PROXY_PROCESS_PAYMENT' LiveRequestQueue:'PROCESS_PAYMENT' LiveResponseQueue:'PAYMENT_PROCESSESED' ProxyResponseQueue:'PROXY_PAYMENT_PROCESSESED' # # This is a sample comment # QueueManager:'Local Docker MQ 9' ProxyRequestQueue:'PROXY_CREATE_ORDER' LiveRequestQueue:'CREATE_ORDER' LiveResponseQueue:'ORDER_CREATED' ProxyResponseQueue:'PROXY_ORDER_CREATED' ``` You can also use the another script format with syntax: ``` # # Order and payment processing # Record request messages from connection 'Local Docker MQ 9' and queue 'PROXY_PROCESS_PAYMENT' and proxy to 'AWS Docker MQ 8' and queue 'PROCESS_PAYMENT', and record response messages from connection 'AWS Docker MQ 8' and queue 'PAYMENT_PROCESSESED' and proxy to 'Local Docker MQ 9' and queue 'PROXY_PAYMENT_PROCESSESED'. Record request messages from connection 'Local Docker MQ 9' and queue 'PROXY_CREATE_ORDER' and proxy to 'AWS Docker MQ 8' and queue 'CREATE_ORDER', and record response messages from connection 'AWS Docker MQ 8' and queue 'ORDER_CREATED' and proxy to 'Local Docker MQ 9' and queue 'PROXY_ORDER_CREATED'. Record request messages from connection 'Local Docker MQ 9' and queue 'PROXY_MAKE_SHIPMENT' and proxy to 'AWS Docker MQ 8' and queue 'MAKE_SHIPMENT', and record response messages from connection 'AWS Docker MQ 8' and queue 'ORDER_SHIPPED' and proxy to 'Local Docker MQ 9' and queue 'PROXY_ORDER_SHIPPED'. # # Compute statistics # Record request messages from connection 'Local Docker MQ 9' and queue 'PROXY_COMPUTE_USER_STATS' and proxy to 'AWS Docker MQ 8' and queue 'COMPUTE_USER_STATS', and record response messages from connection 'AWS Docker MQ 8' and queue 'USER_STATS' and proxy to 'Local Docker MQ 9' and queue 'PROXY_USER_STATS'. ``` #### Replaying to multiple queue managers If you would like to replay multiple queues to multiple queue managers at the same time, please use the replay script. See [replaying using a script](#replay_script) for more details. #### Replaying using a script You can use the "Script" tab to replaying advanced setups of multiple queues on multiple queue managers. Starting with the Script tab chosen and nothing typed is refused with `Please enter a replay script, or choose Manual`. ![Recording using a script](https://trafficparrot.com/documentation/5.65.x/img/mq/native-ibmmq-script-replay.png) Here is an example script to replay multiple queues on multiple queue managers at the same time: ``` # # QM1 queue replay # RequestQueueManager:'Request QM1' ResponseQueueManager:'Response QM1' RequestQueueNames:'REQ_1_A','REQ_1_B' # # QM2 queue replay # RequestQueueManager:'Request QM2' ResponseQueueManager:'Response QM2' RequestQueueNames:'REQ_2_A','REQ_2_B' ``` ## Request message matchers When Traffic Parrot receives a request message, it will try to simulate the system it is replacing by sending back a response message on the response queue or topic. To decide which response message to send, it will go through all the request to response mappings it has available to find the response to be sent. For more details how request matching works, see [Request matching](https://trafficparrot.com/documentation/5.65.x/request_matching.html). The most common matchers are shown below. All other WireMock [request body patterns](https://wiremock.org/docs/request-matching/) are also supported. The expected value of the top-level `bodyMatcher` can also be kept in a file under `__files`, see [Request body matcher value from a file](#edit-mq-request-body-file). ##### Request body matchers - **Matcher name:** any **Matcher Id:** any **Description:** Any request body will match. - **Matcher name:** equal to **Matcher Id:** equalTo **Description:** Check that the received request message body is equal to the request body specified in the mapping - **Matcher name:** contains **Matcher Id:** contains **Description:** Check that the received request message body contains the sequence of characters specified in the mapping - **Matcher name:** does not contain **Matcher Id:** doesNotContain **Description:** Check that the received request body does not contain the sequence of characters specified in the mapping - **Matcher name:** matches regex **Matcher Id:** matches **Description:** Check that the received request message body matches the regexp specified in the mapping - **Matcher name:** does not match regexp **Matcher Id:** doesNotMatch **Description:** Check that the received request message body does not match the regexp specified in the mapping - **Matcher name:** equal to JSON **Matcher Id:** equalToJson **Description:** Check that the received request message body is JSON and that it is equal to the request body JSON specified in the mapping - **Matcher name:** matches JSON **Matcher Id:** matchesJson **Description:** Check that the received request message body matches (allowing for special wildcard tokens) JSON specified in the mapping. Tokens allowed: - `{{ anyValue }}` - matches any value - `{{ anyNumber }}` - matches any whole or decimal number - `{{ anyElements }}` - matches any number of sub-elements (child-nodes) For example a "matches JSON" request body matcher: ``` { "name": "{{ anyValue }}", "lastName": "{{ anyValue }}", "age": "{{ anyNumber }}", "children": "{{ anyElements }}" } ``` will match a request body: ``` { "name": "Bob", "lastName": "Smith", "age": 37, "children": [{"name": "sam"}, {"name": "mary"}] } ``` - **Matcher name:** matches JSONPath **Matcher Id:** matchesJsonPath **Description:** Check that the received request message body is JSON and that it matches [JSONPath](https://restfulapi.net/json-jsonpath/) specified in the mapping. For example, if we use the following expression as the request body matcher ``` $[?(@.xyz.size() == 2)] ``` it will match this request body: ``` {"xyz":[{"a":true}, {"b":false}]} ``` but will NOT match this one: ``` {"xyz":[{"a":true}, {"b":false}, {"c":true}]} ``` For more examples see the [request matching](https://trafficparrot.com/documentation/5.65.x/request_matching.html#request-matcher-examples) documentation. - **Matcher name:** equal to XML **Matcher Id:** equalToXml **Description:** Check that the received request message body is XML and that it is equal to the request body XML specified in the mapping - **Matcher name:** matches XML **Matcher Id:** matchesXml **Description:** Check that the received request message body matches (allowing for special wildcard tokens) XML specified in the mapping. Tokens allowed: - `{{ anyValue }}` - matches any value - `{{ anyNumber }}` - matches any whole or decimal number - `` - matches any number of sub-elements (child-nodes) For example a matches XML request body matcher: ``` {{ anyValue }} {{ anyNumber }} ``` will match a request body: ``` Sam 29 ``` - **Matcher name:** matches XPath **Matcher Id:** matchesXPath **Description:** Check that the received request message body is XML and that it matches [XPath](https://www.w3schools.com/xml/xml_xpath.asp) specified in the mapping. For example, if we use the following expression as the request body matcher ``` /xyz[count(abc) = 2] ``` it will match this request body: ``` ``` but will NOT match this one: ``` ``` - **Matcher name:** matches SWIFT field **Matcher Id:** matchesSwiftField **Description:** Match on a specific field within a SWIFT MT message body. Instead of writing a complex regular expression to match the entire message, you can target an individual field by its tag number and apply a regex to just that field's value. The matcher value is a JSON object with two properties: - `field`: the SWIFT tag identifier without colon delimiters (e.g., `20`, `32A`, `59`) - `matches`: a regular expression applied to the extracted field value For example, to match an MT103 message where tag 20 (Transaction Reference) starts with `TXNREF`: ``` {"field": "20", "matches": "TXNREF.*"} ``` This will match a SWIFT message containing: ``` :20:TXNREF001 ``` but will NOT match: ``` :20:OTHERREF ``` The matcher handles both full SWIFT envelopes (with block structure) and bare field content. Multi-line field values (e.g., `:59:` address fields) are supported. If the specified tag appears multiple times, the match succeeds if any occurrence matches. If the tag is not present or the input is not a SWIFT message, the matcher returns no-match (not an error). The corresponding JSON mapping file format is: ``` { "bodyMatcher": { "matchesSwiftField": { "field": "20", "matches": "TXNREF.*" } } } ``` - **Matcher name:** matches FIX field **Matcher Id:** matchesFixField **Description:** Match on a specific tag within a FIX protocol message body. Instead of writing a complex regular expression to match the entire message body, you can target an individual tag by its number and apply a regex to just that tag's value. The matcher value is a JSON object with two properties: - `field`: the FIX tag number (e.g., `35` for message type, `11` for client order ID, `44` for price) - `matches`: a regular expression applied to the extracted tag value For example, to match a NewOrderSingle message (message type `D`) where tag 35 is `D`: ``` {"field": "35", "matches": "D"} ``` This will match an IBM MQ message body containing the FIX-standard SOH-delimited body: ``` 8=FIX.4.4|9=176|35=D|49=SENDER|56=TARGET|11=ORDER123|55=AAPL|54=1|44=150.25|10=128| ``` (where `|` represents the SOH character, ASCII `0x01`) but will NOT match an ExecutionReport message where tag 35 is `8`. Tag numbers are treated as opaque string keys, so the matcher works across FIX 4.2, 4.4, 5.0, and FIXT without any FIX-dictionary validation. If the specified tag appears multiple times (for example inside a repeating group), the match succeeds if any occurrence matches. If the tag is not present or the input is not a FIX message, the matcher returns no-match (not an error). The corresponding JSON mapping file format is: ``` { "bodyMatcher": { "matchesFixField": { "field": "35", "matches": "D" } } } ``` - **Matcher name:** equal to base64 **Matcher Id:** binaryEqualTo **Description:** Check that the received request message's bytes equal the Base64 value specified in the mapping, decoded. The bytes compared are the message bytes as Traffic Parrot read them: the raw bytes of an `MQFMT_NONE` body; for an `MQFMT_RF_HEADER_1` or `MQFMT_RF_HEADER_2` message, the body after the headers, read by its own format, or the whole message with its headers when [`trafficparrot.ibmmq.skipHeadersInRequestMessageBodyWhenMatching`](https://trafficparrot.com/documentation/5.65.x/properties.html#ibmmq-properties) is `false`; for an `MQFMT_STRING` body, the UTF-8 encoding of its text, which is the message's own bytes when its CCSID is UTF-8 and not when it is an EBCDIC one. Recording a message writes a text matcher, not this one. It is accepted as the top-level `bodyMatcher` only, with the Base64 inline: not inside `not`, `and` or `or`, and not read from a `bodyFileName` file. The corresponding JSON mapping file format is: ``` { "bodyMatcher": { "binaryEqualTo": "AAEC/w==" } } ``` - **Matcher name:** matches CICS field **Matcher Id:** matchesCicsField **Description:** Match one field of a [CICS DPL bridge request](https://trafficparrot.com/documentation/5.65.x/cics.html) by its path in the request's JSON view: a decoded COMMAREA field, the program name, an `MQCIH` field or the MQMD user id. Needs the bridge enabled. The matcher value is a JSON object with a `field` path and exactly one of `equalTo`, `matches`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan` and `lessThanOrEqualTo`; a number compares as a number, so a `PIC 9(4)` holding `0042` equals `42`: ``` {"field": "COMMAREA.BRANCH-ID", "greaterThan": 40} ``` See [the `matchesCicsField` matcher](https://trafficparrot.com/documentation/5.65.x/cics.html#matches-cics-field) for the path syntax and the comparisons. - **Matcher name:** NOT (negate a matcher) **Matcher Id:** not **Description:** Check that the received request message body does **not** match the child matcher. Selecting `NOT (negate a matcher)` in the *Request body* dropdown replaces the request body field with a **NOT child matcher** sub-editor where you choose the matcher to negate and its value. It is saved as a nested matcher, for example ``` "bodyMatcher": { "not": { "contains": "CANCELLED" } } ``` See [Authoring `not` in the messaging editor](https://trafficparrot.com/documentation/5.65.x/request_matching.html#not-in-messaging-editor) for the matchers that can be negated. - **Matcher name:** AND (all sub-matchers match) **Matcher Id:** and **Description:** Check that the received request message body matches **every** sub-matcher. Selecting `AND (all sub-matchers match)` in the *Request body* dropdown replaces the request body field with a **Sub-matchers** panel in which each row is a matcher and its value. It is saved as a list of sub-matchers, for example ``` "bodyMatcher": { "and": [ {"contains": "ORDER-"}, {"doesNotContain": "DRAFT"} ] } ``` At least two sub-matchers are required. See [Authoring `and` and `or` in the messaging editor](https://trafficparrot.com/documentation/5.65.x/request_matching.html#and-or-in-messaging-editor). - **Matcher name:** OR (any sub-matcher matches) **Matcher Id:** or **Description:** Check that the received request message body matches **at least one** sub-matcher. It is authored through the same **Sub-matchers** panel as `AND (all sub-matchers match)` above, and saved the same way under an `or` key, for example ``` "bodyMatcher": { "or": [ {"equalTo": "PING"}, {"equalTo": "HEALTHCHECK"} ] } ``` At least two sub-matchers are required. See [Authoring `and` and `or` in the messaging editor](https://trafficparrot.com/documentation/5.65.x/request_matching.html#and-or-in-messaging-editor). ## Edit IBM® MQ mappings ### Introduction On the following IBM® MQ pages, the edit button ![Edit button](https://trafficparrot.com/documentation/5.65.x/img/http/edit_button.png) will allow you to edit an existing mapping: - Add/Edit - Record - Replay Traffic Parrot supports the following MQ message formats: - `MQFMT_STRING` - `MQFMT_NONE` - `MQFMT_RF_HEADER_1` and `MQFMT_RF_HEADER_2` You can edit the message body through the UI and configure certain [response header fields](#edit-mq-response-headers) (`replyToQueueManagerName` and `replyToQueueName`) directly in the mapping JSON file. ### Response delay Traffic Parrot supports postponing the delivery of a MQ message. This can be useful to better simulate a more realistic scenario where the responding system does not send a response message immediately after receiving the request message. Use the ![Edit delay screenshot](https://trafficparrot.com/documentation/5.65.x/img/jms/edit-message-delay.png) field on the edit mapping panel to specify the delay in milliseconds. ### Priority The request priority can be set in order to set up a preference order for matching mappings. The highest priority value is `1`. If two or more mappings both match a request, the mapping with the higher priority will be used to provide the response. The default priority is `5`. This can be useful, if you want a "catch-all" mapping that returns a general response for most requests and specific mappings on top that return more specific responses. ### Text messages Traffic Parrot is able to record and replay messages that could contain text in a variety of formats e.g. JSON, XML or plain text. ![Edit MQ text mapping screenshot](https://trafficparrot.com/documentation/5.65.x/img/mq/edit-mq-text-mapping.png) ##### Supported features - Edit the response body - Match requests using the request body matchers (e.g. JsonPath, contains, regexp) - Use priority to set up a preference order for matching mappings ### Response body from a file Instead of typing a text response body inline, you can keep the body in a separate file and point the mapping's response at it with a `bodyFileName` attribute, the same convention as a [JMS response body from a file](https://trafficparrot.com/documentation/5.65.x/jms.html#edit-jms-response-body-file) and an [HTTP file-backed response](https://trafficparrot.com/documentation/5.65.x/http.html#file-backed-responses). This is useful when the response is large, is generated by a build step, or is shared between more than one mapping, and it keeps your `ibm-mq-mappings/*.json` files small. In a mapping's `response`, set `bodyFileName` to a path under the `__files` directory in place of an inline `text` value: ```json { "request": { "destination": { "name": "DEV.REQUEST.QUEUE", "type": "QUEUE" }, "bodyMatcher": { "equalTo": "hello" } }, "response": { "destination": { "name": "DEV.RESPONSE.QUEUE", "type": "QUEUE" }, "bodyFileName": "responses/reply.txt" } } ``` with the response body stored in the sibling `__files` directory: ``` trafficparrot-x.y.z/ |-- ibm-mq-mappings/ | `-- greeting.json <- "response": { "bodyFileName": "responses/reply.txt" } `-- __files/ `-- responses/ `-- reply.txt <- the response body that is sent ``` The `bodyFileName` is resolved relative to the `__files` directory that sits next to the mapping's `ibm-mq-mappings` directory (each scenario has its own `__files` for scenario-scoped mappings). Nested paths such as `responses/reply.txt` are allowed. A `bodyFileName` that would resolve outside the `__files` directory, whether by climbing out with `..` or by giving an absolute path, is rejected. ##### What to know - **`MQFMT_STRING` only.** A `bodyFileName` response is read as UTF-8 text and is supported for the `MQFMT_STRING` message format only, which is the format a response has unless its `format` says otherwise. The `MQFMT_NONE`, `MQFMT_RF_HEADER_1` and `MQFMT_RF_HEADER_2` formats write bytes, and a response in one of those formats that names a file is rejected when the mappings load, with an error naming the format; such a body must still be provided inline. - **One or the other.** A response sets either an inline `text` value or a `bodyFileName`, not both. - **One file per response message.** In a mapping that sends [multiple response messages](#multiple-response-messages), each entry of `responses` chooses for itself between an inline `text` and a `bodyFileName`. - **Templated at reply time.** The file's contents are run through the same [Handlebars templating](https://trafficparrot.com/documentation/5.65.x/dynamic.html#extract-data) as an inline text body, so a body file can reference the incoming request and use the response [helpers](https://trafficparrot.com/documentation/5.65.x/dynamic.html#extension-functions), as long as [`trafficparrot.ibmmq.handlebars.enabled`](https://trafficparrot.com/documentation/5.65.x/properties.html) is `true`, which it is by default. A [custom IBM® MQ response transformer](https://trafficparrot.com/documentation/5.65.x/dynamic.html#custom-nativeibmmq-response-transformers) that reads the response's `text` field directly sees no value for a file-backed response, because the body lives in the file rather than in `text`. - **A bad reference stops the whole mappings list from loading.** Setting both `text` and `bodyFileName`, naming a file that does not exist under the resolved `__files` directory, or naming a file on a response whose format is not `MQFMT_STRING`, is rejected when the mappings are loaded. This is deliberate fail-fast behaviour, and it is not limited to the offending mapping: your IBM® MQ mappings fail to load until the mapping is corrected, rather than that one mapping being skipped or an empty reply being sent. The error names the mapping and the file. ##### Editing a file-backed response The mappings list shows the file name in the **Response text** column, so a file-backed response can be told from an inline one at a glance. When you open the mapping in the editor, a read-only note reading **Response from file:** followed by the file name is shown above the response body field, and the field is pre-filled with the file's current contents so you can edit it in place. When you click **Save**, Traffic Parrot writes your changes back to the file in `__files`; the mapping keeps its `bodyFileName` reference, so the body stays in the file rather than being copied inline. The [Static Files](https://trafficparrot.com/documentation/5.65.x/http.html#static-files-browser) page counts a file referenced by an IBM® MQ response as in use, so it cannot be deleted or renamed from there while a mapping references it, and exporting a scenario bundles the referenced `__files` body file into the export, so file-backed mappings move between environments intact. ### Request body matcher value from a file Instead of typing the expected value of the request `bodyMatcher` inline, you can keep it in a file under the `__files` directory and replace the matcher's value with a `bodyFileName` object, the same convention as a [response body from a file](#edit-mq-response-body-file) above and as a [JMS request body matcher value from a file](https://trafficparrot.com/documentation/5.65.x/jms.html#edit-jms-request-body-file). This is useful when the expected message is large or is generated by a build step. For example ```json { "request": { "destination": { "name": "DEV.REQUEST.QUEUE", "type": "QUEUE" }, "bodyMatcher": { "equalToXml": { "bodyFileName": "requests/expected-order.xml" } } }, "response": { "destination": { "name": "DEV.RESPONSE.QUEUE", "type": "QUEUE" }, "text": "OK" } } ``` The file is read as UTF-8 text when the mappings are loaded, resolved relative to the `__files` directory beside the mapping's `ibm-mq-mappings` directory (per scenario for scenario-scoped mappings), and matched against exactly as an inline value would be. A `bodyFileName` that names a file which does not exist, or that would resolve outside `__files`, is rejected when the mappings load, with an error naming the mapping and the file, and the IBM® MQ mappings fail to load until it is corrected, as for a bad response file reference above. ##### What to know - **Top-level matcher only.** Only the `bodyMatcher` itself reads its value from a file. A `bodyFileName` nested inside an `and`, `or` or `not` operator is refused when the mappings load, with an error naming the mapping file, the matcher and the file: move the file reference to the top level, or write that value inline. - **Text matchers.** The file form is available for the [matchers](#request-body-matchers) whose value is a text, JSON or XML document: `equalTo`, `contains`, `doesNotContain`, `matches`, `doesNotMatch`, `equalToXml`, `matchesXml`, `matchesXPath`, `equalToJson`, `matchesJson`, `matchesJsonPath`, `matchesJsonSchema`, `matchesGraphQL`, `matchesSwiftField`, `matchesFixField` and `matchesCicsField`. A `binaryEqualTo` matcher keeps its bytes inline. - **The file holds the value, not the matcher.** It contains the expected value of that one matcher and nothing else; the matcher and any `and`, `or` or `not` structure always live in the mapping. - **Exported with the scenario, and protected.** Exporting a scenario bundles the files referenced by request matchers as well as those referenced by response bodies, and the [Static Files](https://trafficparrot.com/documentation/5.65.x/http.html#static-files-browser) page counts both as in use, so a file that backs a request matcher cannot be deleted or renamed from there while a mapping references it. - **The editor keeps the file reference.** The mapping editor shows a file-backed request matcher as its `bodyFileName` object, as JSON text, in the request body field, and the mappings list shows the same text in its request column. Saving the form with that text unchanged keeps the file reference and the matcher's other options, such as `caseInsensitive`; a reference to a file that does not exist, or is outside `__files`, is refused and nothing is saved. Replacing the text with a value saves that value as the matcher's inline value and keeps the other options. Changing the matcher type in the editor saves the reference's JSON text as the new matcher's inline value and drops the other options, so change the matcher of a file-backed request on disk or through the REST API. The [mapping schema](https://trafficparrot.com/documentation/5.65.x/generate-mocks-with-ai-agent.html#agents-md) served at `/schemas/ibm-mq-mapping.schema.json` describes the file form, so `trafficparrot.sh validate`, which checks each mapping file against it, reports a misplaced file reference before the mapping is loaded. ### Zero response messages Traffic Parrot is able to send zero response messages for a given request message. When a request message is matched to a mapping, no response will be sent. ![Remove Native IBM MQ response](https://trafficparrot.com/documentation/5.65.x/img/mq/remove_response_message.png) ##### To create a mapping that will no response message in response to one request message: - Go to IBM® MQ > Add/Edit - Click the ![Trash button](https://trafficparrot.com/documentation/5.65.x/img/mq/trash_button.png) button at the top of the response mapping pane. This will delete the response message from the mapping. - Press "Save" to save the request to responses mapping ### Multiple response messages Traffic Parrot is able to send multiple response messages for a given request message. When a request message is matched to a mapping, all the responses present in that mapping will be sent. ![Add an additional Native IBM MQ response](https://trafficparrot.com/documentation/5.65.x/img/mq/add_additional_response_message.png) ##### To create a mapping that will send multiple response messages in response to one request message: - Go to IBM® MQ > Add/Edit - Click the ![Plus button](https://trafficparrot.com/documentation/5.65.x/img/mq/plus_button.png) button below the response in the mapping pane. This will add a new response that will be sent after the first one has been sent. - Fill in the details where to send the response - You can use delays to space out sending of response messaged is needed - (Optional) Add more additional response messages - Press "Save" to save the request to responses mapping ##### Important notes: - Order of response messages is guaranteed only when "Send threads" is set to 1. If there is more than one send thread, order is not guaranteed. - [Performance monitor](#performance-monitoring-configuration) is not available for mappings with multiple response messages ### Response headers You can configure the `replyToQueueManagerName` and `replyToQueueName` response header fields directly in the mapping JSON file. These fields support [Handlebars templates](https://trafficparrot.com/documentation/5.65.x/dynamic.html), so you can use dynamic values based on the request message. To set response headers, add the `replyToQueueManagerName` and/or `replyToQueueName` fields to the `response` section of your IBM® MQ mapping JSON file located in `ibm-mq-mappings/`. ##### Example: static response headers ```json { "request": { "destination": { "name": "DEV.REQUEST.QUEUE", "type": "QUEUE" }, "bodyMatcher": { "equalTo": "hello" } }, "response": { "destination": { "name": "DEV.RESPONSE.QUEUE", "type": "QUEUE" }, "text": "world", "replyToQueueManagerName": "QM1", "replyToQueueName": "MY.REPLY.QUEUE" } } ``` ##### Example: dynamic response headers using Handlebars You can use Handlebars expressions to set response MQMD header fields. `replyToQueueName` sets metadata on the outgoing message and does not control where the response is sent. Response routing is handled automatically: by default, if the request message has a `replyToQueueName` header set, the response is sent to that queue; otherwise, it is sent to the `destination.name` configured in the mapping. `replyToQueueManagerName` also selects the queue manager the response queue is opened on, so it must be one the connected queue manager can resolve: its own name, as in the example above, or a remote queue manager it has a transmission queue for. A name it cannot resolve leaves the response undelivered. ```json { "request": { "destination": { "name": "DEV.REQUEST.QUEUE", "type": "QUEUE" }, "bodyMatcher": { "anything": "anything" } }, "response": { "destination": { "name": "DEV.RESPONSE.QUEUE", "type": "QUEUE" }, "text": "response body", "replyToQueueManagerName": "{{request.header.replyToQueueManagerName}}", "replyToQueueName": "{{request.header.replyToQueueName}}" } } ``` ##### Default behavior When these fields are not set in the mapping JSON: - `replyToQueueManagerName` defaults to the value from the request message header, or the producer's queue manager name if the request header is empty - `replyToQueueName` defaults to an empty string See the [dynamic responses](https://trafficparrot.com/documentation/5.65.x/dynamic.html#request-data-native-mq) page for a full list of available request attributes that can be used in Handlebars templates. ## Requests page **IBM® MQ > Requests** in the top navigation bar lists the messages the native IBM MQ virtual service received that matched no mapping, each with the mappings that came closest and the field each one missed on. A message a mapping matched is answered and is not listed. The page is the one the [JMS page](https://trafficparrot.com/documentation/5.65.x/jms.html#requests-page) shows, with the queue the message arrived on as its destination. The page needs [`trafficparrot.messaging.diagnostics.enabled=true`](https://trafficparrot.com/documentation/5.65.x/properties.html#jms-properties) in `trafficparrot.properties`, read when Traffic Parrot starts. It is `false` by default, because finding the near misses compares each unmatched message with every mapping. With it off the page keeps its intro and stays at `0 MESSAGES`; an unmatched message is still written to the [log](https://trafficparrot.com/documentation/5.65.x/logging.html), under `No match for`. Each row shows when the message arrived, its queue, its body type and how many near misses were found. Expand a row to see the message body, laid out as JSON when it is JSON (for a [CICS bridge request](https://trafficparrot.com/documentation/5.65.x/cics.html#request-view), the JSON view Traffic Parrot matches), and under **Near Misses** the three closest mappings, best first. Each one is headed with the mapping's queue and how close the message came, as a percentage, and compares what the mapping expects with what the message carried, for the destination, the body type and the body content, with a tick on each row that matched and a cross on each that did not. **Show full near-miss JSON** prints the comparison as `GET /ibmMq/management/nearMisses` returns it. With no mapping to compare against, the row reads `No near misses found`. ![The Requests page, here the JMS one, with one unmatched message expanded: its JSON body, then two near misses, each a table comparing the mapping's destination, body type and body content with the message's](https://trafficparrot.com/documentation/5.65.x/img/jms/requests-near-miss.png) The list reloads every three seconds and pauses while a row is expanded; **Refresh** reloads it at once and collapses the rows. **Clear** empties it, after a confirmation. Messages are listed under the [scenario](https://trafficparrot.com/documentation/5.65.x/user_guide.html#scenarios) selected when they arrived, at most [`trafficparrot.virtualservice.maxRequestJournalEntries`](https://trafficparrot.com/documentation/5.65.x/properties.html#virtualservice-properties) of them per scenario (`1000` by default; `0` switches the journal and this page off), and are forgotten when Traffic Parrot restarts. A message whose body cannot be read is logged as skipped and is not listed. The same journal answers the request count API, whether or not the diagnostics property is set: `POST /api/ibmMq/requests/count` counts the messages received, matched or not, that match the pattern in its body (every message when the body is empty; a message is counted under the scenario whose virtual service received it), and `DELETE /api/ibmMq/requests` resets the journal, which also empties this page. Both are in the [OpenAPI documentation](https://trafficparrot.com/documentation/5.65.x/openapi/index.html). ## Import an AsyncAPI specification [AsyncAPI](https://www.asyncapi.org/) is an open specification for describing event-driven and message-based APIs (its channels, operations and message schemas) in the same way that OpenAPI describes HTTP APIs. If your team already documents its messaging APIs with AsyncAPI, you can create native IBM® MQ mappings directly from that document instead of writing them by hand. Go to **IBM® MQ** in the top navigation bar and then click **Import AsyncAPI**. Upload a JSON or YAML **AsyncAPI 2.x or 3.0** document and Traffic Parrot generates one IBM® MQ mapping per importable channel operation, each serving an example payload generated from the operation's message schema. ### Preview and select before importing After you upload the document, Traffic Parrot shows a preview of the mappings it would create so you can review and select exactly which ones to import. The import page works the same way as the [JMS AsyncAPI import](https://trafficparrot.com/documentation/5.65.x/jms.html#import-asyncapi-jms), except each selected operation becomes a native IBM® MQ mapping. ![AsyncAPI import preview on the IBM MQ page showing channel operations with destination, type, operation, reply destination, example payload and status columns](https://trafficparrot.com/documentation/5.65.x/img/mq/asyncapi_import_preview.png) The preview table lists one row per importable operation, with the following columns: - **Destination**: the channel name the operation maps to - **Type**: `QUEUE` or `TOPIC`, taken from the channel's `ibmmq` or `jms` binding - **Operation**: the AsyncAPI operation id (for example `publishOrderCreated`) - **Reply destination**: for an AsyncAPI 3.0 request-reply operation (one that carries a `reply` object), the reply channel the response is published to; blank for a one-way operation - **Example payload**: the example message generated from the operation's message schema - **Status**: a green **New** badge for an operation that does not match an existing mapping Each row has a checkbox. Use the header checkbox to select or deselect all rows at once, or toggle individual rows. The **Import Selected** button shows the count of selected rows. Click it to create IBM® MQ mappings only for the checked operations, or click **Cancel** to discard the preview and return to the file selector. If the document is malformed, is not a supported AsyncAPI version, or contains no importable operations, the page reports a clear error and no mappings are created. ### What gets created Each selected operation becomes a native IBM® MQ mapping whose request matches any message on the channel destination and whose response is the example payload generated from the message schema. You can then open the mapping in the [IBM® MQ editor](#edit-mq) to refine the request matchers, response message, response headers or priority just like any other IBM® MQ mapping. For an AsyncAPI 3.0 operation that carries a `reply` object, Traffic Parrot creates a **request-reply** mapping instead: it still receives the request on the operation's own channel, but it publishes the response on the **reply channel's** destination (shown in the **Reply destination** column of the preview), and the response is the example payload generated from the **reply** message's schema. A one-way operation continues to echo its example back on the same channel as before. AsyncAPI import is part of the native IBM® MQ support and requires the IBM® MQ licensed feature, the same as the rest of the native IBM® MQ functionality. ##### Supported scope Traffic Parrot supports both **AsyncAPI 2.x** and **AsyncAPI 3.0** documents with the **IBM® MQ** and **JMS** channel bindings. For a 3.0 document, the destination is taken from the channel's `address` (falling back to the channel name). The destination **type** is taken from the channel binding: it is a `TOPIC` when either the `ibmmq` or the `jms` binding declares `destinationType: topic` (case-insensitive); otherwise it defaults to a `QUEUE` (so a document with no binding, or one whose `destinationType` is absent, empty or unrecognised, imports as a queue). Both one-way publish/subscribe operations (`send` and `receive`) and request-reply operations (those that carry a `reply` object) are imported; a request-reply operation publishes the reply message's example on the reply channel's destination. Other channel bindings (AMQP, Kafka, MQTT) and AsyncAPI 4.x are not yet supported. Message payload schemas use JSON Schema (draft-07 for 2.x, draft 2020-12 for 3.0); Traffic Parrot generates an example from common schema constructs, and renders a placeholder payload for advanced constructs it cannot yet turn into an example (for example `$defs` with internal `$ref`, `patternProperties`, `prefixItems`, `const`, `if`/`then`/`else` and `additionalProperties`). You can edit any generated payload in the editor afterwards. ## Messaging skeletons Messaging skeletons offer a quick way to pre-fill a native IBM® MQ mapping form from an operation declared in an imported [AsyncAPI](https://www.asyncapi.org/) specification, in the same way the [HTTP skeletons](https://trafficparrot.com/documentation/5.65.x/http.html#http-skeletons) and gRPC skeletons dropdowns pre-fill their forms. Where [Import AsyncAPI](#import-asyncapi-mq) creates mappings for many operations at once, the skeletons dropdown is for hand-crafting a single mapping that starts from a declared operation. On the IBM® MQ **Add/Edit** page, pick an operation from the **skeletons** dropdown above the form. The form's destination name, destination type (the **Queue** / **Topic** radio) and request body/payload pre-fill from the selected operation. To edit the list of operations, place [AsyncAPI specifications](https://www.asyncapi.org/) (JSON or YAML, AsyncAPI 2.x or 3.0) into the `trafficparrot-x.y.z/asyncapi` configuration directory, or use the import button beside the dropdown to upload one directly. The dropdown behaves the same as on the JMS page, including the **request-reply** pre-fill that populates both the request and the reply sides for a request-reply operation; see [Messaging skeletons](https://trafficparrot.com/documentation/5.65.x/jms.html#messaging-skeletons-jms) on the JMS page for a screenshot and the full details. It appears on the JMS and IBM® MQ messaging editors only (AsyncAPI has no file-message source, so the file-message editor does not show it). ## Messaging coverage check The headless `trafficparrot.sh validate` command (`trafficparrot.exe validate` on Windows) checks your messaging mappings against your imported [AsyncAPI](https://www.asyncapi.org/) specifications and reports any declared operation that has no backing messaging mapping. The check is identical for JMS and native IBM® MQ mappings: a native IBM® MQ mapping covers a declared AsyncAPI operation in exactly the same way a JMS mapping does, matched by destination identity (`QUEUE:name` / `TOPIC:name`). For the messaging under-coverage check, the `asyncapi/` specification directory and the `messaging-coverage.properties` (`exclude.destinations`) allowlist, see [Messaging coverage check](https://trafficparrot.com/documentation/5.65.x/jms.html#validate-messaging) on the JMS page; for the shared usage, exit codes and CI-pipeline details see the full [validate CLI reference](https://trafficparrot.com/documentation/5.65.x/http.html#validate-cli). ## Import a message Pact contract [Pact](https://docs.pact.io/) is a consumer-driven contract format. As well as the HTTP interactions you can [import as HTTP stubs](https://trafficparrot.com/documentation/5.65.x/http.html#import-http-pact), a Pact contract can describe **asynchronous message** interactions: the messages a provider publishes for a consumer to handle. If your team captures its messaging contracts as Pact files, you can create native IBM® MQ mappings directly from them instead of writing them by hand. Go to **IBM® MQ** in the top navigation bar and then click **Import message Pact**. Upload a Pact `.json` file and Traffic Parrot generates one IBM® MQ mapping per message interaction in the contract, each publishing the message's example payload. > **Two contract shapes are accepted.** A Pact specification **v3** contract carries its messages in a top-level `messages[]` array. A specification **v4** contract carries them as `interactions[]` entries whose `type` is `Asynchronous/Messages`. Both are detected automatically. An HTTP-only Pact contract (one with no message interactions) is rejected with a message pointing you to the [HTTP Pact import](https://trafficparrot.com/documentation/5.65.x/http.html#import-http-pact) instead. ### Preview and select before importing After you upload the file, Traffic Parrot shows a preview of the mappings it would create so you can review and select exactly which ones to import. The import page works the same way as the [JMS message Pact import](https://trafficparrot.com/documentation/5.65.x/jms.html#import-message-pact-jms), except each selected message becomes a native IBM® MQ mapping. The preview table lists one row per message interaction, with the following columns: - **Destination**: the queue or topic the message is published to, [derived](#import-message-pact-mq-result) from the contract - **Type**: `QUEUE` or `TOPIC` - **Operation**: the message's `description` from the contract, used as the operation id - **Reply destination**: always blank for a message Pact, because message interactions are [one-way](#import-message-pact-mq-result) (there is no reply) - **Example payload**: the message's example `contents` from the contract, which is what the mapping will publish - **Status**: a green **New** badge for a message whose derived destination does not match an existing mapping, or a **Duplicate** badge when it does Each row has a checkbox. New rows are checked by default and duplicate rows are left unchecked. Use the header checkbox to select or deselect all rows at once, or toggle individual rows. The **Import Selected** button shows the count of selected rows. Click it to create IBM® MQ mappings only for the checked messages, or click **Cancel** to discard the preview and return to the file selector. If the file cannot be parsed as JSON, or contains no message interactions, the page reports a clear error and no mappings are created. > **Review a derived destination before importing.** A Pact message interaction carries no destination, so Traffic Parrot derives one from the message's `metadata` (a `destination`, `queue` or `topic` key, where a `topic` key makes it a TOPIC) or, failing that, from the message's `description`. When a destination is derived from the description, the preview shows a warning banner listing each affected message; review it, because the generated name is a best guess and may not match the queue or topic your system under test uses. See [How the destination is derived](https://trafficparrot.com/documentation/5.65.x/jms.html#import-message-pact-jms-destination) on the JMS page for the full rules. ### What gets created Each selected message becomes a **one-way publish** native IBM® MQ mapping. It matches any message on the derived destination and, on receipt, publishes the message's example `contents` back on that same destination. You can then open the mapping in the [IBM® MQ editor](#edit-mq) to refine the request matchers, response message, response headers or priority just like any other IBM® MQ mapping. > **Message Pact imports are one-way only.** A Pact message interaction is a fire-and-forget message a provider publishes; the contract has no request that selects it and no reply. The imported mapping therefore just publishes the example payload; it is *not* a request-matching, request-reply stub. (Request-reply mappings are created only by an [AsyncAPI](#import-asyncapi-mq) operation that carries a `reply` object.) **Import message Pact** is part of the native IBM® MQ support and requires the IBM® MQ licensed feature, the same as the rest of the native IBM® MQ functionality; the menu link does not appear without it. Pact specification **v3** (`messages[]`) and **v4** (`Asynchronous/Messages` interactions) message contracts are supported; for a v4 contract the example body is read from the message's `contents.content` envelope. The same import flow is also available for [JMS](https://trafficparrot.com/documentation/5.65.x/jms.html#import-message-pact-jms), including a [worked example](https://trafficparrot.com/documentation/5.65.x/jms.html#import-message-pact-jms-result). ## Proof of concept with on-premises installation at a large enterprise See [proof of concept](https://trafficparrot.com/documentation/5.65.x/user_guide.html#poc) in the user guide. ## Dynamic responses and custom extensions Have a look at [available custom extensions and how to generate responses dynamically](https://trafficparrot.com/documentation/5.65.x/dynamic.html) ## FAQ Have a look at [FAQ](https://trafficparrot.com/documentation/5.65.x/faqs.html)