File Transfer

First, go to Files in the top navigation bar and then click Add/Edit.

Fill in the Request/Response fields and click Save to configure a mapping.

After saving the mapping, it will appear in the list of mappings.

Clicking the edit button will allow you to edit an existing mapping.

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.

Request body matcher value from a file

Instead of typing the expected value of the request bodyMatcher inline, you can keep it in a separate file under the __files directory and replace the matcher's value with a bodyFileName object, the same convention a JMS or HTTP mapping uses for a body kept in a file. This is useful when the expected request file is large or is generated by a build step. The file is read when the mapping loads, resolved relative to __files and contained to it, so a mapping whose file is missing or would resolve outside __files is refused with an error naming the mapping file. For example

"bodyMatcher": {
  "equalToXml": { "bodyFileName": "orders/expected-order.xml" }
}

Only the top-level bodyMatcher reads its value from a file. A bodyFileName nested inside and, or or not, or on fileNameMatcher, is refused when the mapping loads, 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. The file form is available for the matchers above whose value is a text, JSON or XML document: equalTo, contains, doesNotContain, matches, doesNotMatch, equalToXml, matchesXml, matchesXPath, equalToJson, matchesJson, matchesJsonPath, matchesJsonSchema, matchesGraphQL, matchesSwiftField and matchesFixField. A binaryEqualTo matcher keeps its bytes inline. The mapping schema served at /schemas/file-message-mapping.schema.json describes the same rule, so trafficparrot.sh validate, which checks each mapping file against it, reports a file reference in a position the mapping cannot load from before the mapping is loaded.

A file that is not text, such as a PGP, zip or EBCDIC file, passes through recording and replay byte for byte on Local File System, SFTP and FTP connections: the copy forwarded while recording, the reply saved with the mapping and the reply written on replay are each identical to the original.

When you record a request file that is not valid UTF-8, the mapping matches it by file name and by content: its request has a file name equalTo and a binaryEqualTo of the file's exact bytes, as base64 in the mapping JSON, so two binary files of one name are each answered by their own mapping. Its reply is saved to __files/file-message-<mapping id>-<reply file name> with a bodyType of BYTES. A character in the reply file name other than A to Z, a to z, 0 to 9, ., _ or - is replaced with _. A text file is recorded as before, with its content and a body matcher in the mapping.

Text matchers compare a file's content as text. To match a binary file on its content, choose equal to base64 (binaryEqualTo) as the request body matcher and give the Base64 of the expected bytes, or record the file: the file's exact bytes must equal them, and the file name matcher applies as well. In the mapping JSON it is the top-level bodyMatcher beside the fileNameMatcher; see Request file body (contents) matchers.

Binary reply from a file

To reply with a binary file of your own, put it under __files and reference it from the mapping's response with bodyFileName and a bodyType of BYTES:

"response": {
  "destination": { "name": "reply", "type": "QUEUE" },
  "fileName": "reply.pgp",
  "bodyFileName": "statement-reply.pgp",
  "bodyType": "BYTES"
}

The file is written to the response directory as reply.pgp, byte for byte. Handlebars templates are not applied to a BYTES body; the response file name is still templated. With a BYTES body type, an inline text holds the content as base64, which may be wrapped over several lines. A mapping whose inline BYTES body is not base64 is refused when the mappings load, with an error naming the mapping file; as with any invalid file message mapping, the Files pages then list no mappings, show the error under the empty list, and replay matches nothing until it is fixed.

Binary replies in the editor

The Add/Edit page shows a binary reply as base64 under a Response from file note naming its __files file, as the JMS editor shows a bytes message. Saving writes the file back byte for byte. A Save whose response body is not base64 is refused with the reason, and the mapping and its file are left as they were.

The JMS, IBM® MQ and file message editors accept a response body up to trafficparrot.multipart.upload.max.size.mb (default 10 MB). Base64 is a third larger than the file it encodes and the form encoding adds a little more, so a binary reply of up to about 7 MB can be saved at the default.

Binary files in a custom response transformer

In a custom file message response transformer, FileMessage.bytes() returns the request file's exact content and FileMessage.ofBytes(fileName, bytes, timestamp) builds a message that is written as those bytes; text still holds the content decoded as UTF-8. A FileMessageResponse with a BYTES body type and base64 text writes the bytes the base64 encodes.

Go to Files in the top navigation bar and then click Export. Click the button to download a ZIP file that contains all of the File mappings and data files.

The ZIP file contains the following directories:

• mappings/: File stub mappings in JSON format
• data/: data directory files

Go to Files in the top navigation bar and then click Import. Select a ZIP file that was previously exported and it will be uploaded and the mappings and data files will be restored.

To run several consume and reply pairs in one replay session, choose Script on the Files replay page instead of Manual. Each block of the script has three lines: RequestRootDirectory names the connection to consume request files from, ResponseRootDirectory the connection to write responses to, and RequestSubdirectories the subdirectories to consume, each in quotes. Separate blocks with a blank line. For example, one block answers the system under test on a gateway connection while a second consumes the gateway's triggers and replies on the system under test's own root:

RequestRootDirectory:'gateway'
ResponseRootDirectory:'gateway'
RequestSubdirectories:'inbox'

RequestRootDirectory:'gateway'
ResponseRootDirectory:'sut'
RequestSubdirectories:'triggers'

The IBM® MQ page's keys (RequestQueueManager, ResponseQueueManager and RequestQueueNames) are still accepted, so a script written for the Files replay API keeps running. Starting with Script chosen and nothing typed is refused with Please enter a replay script, or choose Manual. Through the API, a script session needs parameterType set to SCRIPT; a script sent without it starts a Manual session and the script is ignored.

Files > Requests in the top navigation bar lists the request files replay picked up that matched no mapping, each with the mappings that came closest and the field each one missed on. A file a mapping matched is consumed and its reply written to the response directory, without being listed; a file no mapping matched is listed and left in its request directory.

The page needs trafficparrot.messaging.diagnostics.enabled=true in trafficparrot.properties, read when Traffic Parrot starts. It is false by default, because finding the near misses compares each unmatched file with every mapping. With it off the page keeps its intro and stays at 0 MESSAGES; an unmatched file is still written to the log, under No match for.

Each row shows when the file was picked up, the request directory it was in (its destination), its body type and how many near misses were found. Expand a row to see the file's content, laid out as JSON when it is JSON, and under Near Misses the three closest mappings, best first. Each one is headed with the mapping's request directory and how close the file came, as a percentage, and compares what the mapping expects with what the file 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. A file name the mapping's file name matcher refuses counts against the body content row; the name itself is not shown. Show full near-miss JSON prints the comparison as GET /fileMessage/management/nearMisses returns it. With no mapping to compare against, the row reads No near misses found.

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. Files are listed under the scenario selected when they were picked up, at most trafficparrot.virtualservice.maxRequestJournalEntries of them per scenario (1000 by default; 0 switches the journal and this page off), and are forgotten when Traffic Parrot restarts.

The same journal answers the request count API, whether or not the diagnostics property is set: POST /api/fileMessage/requests/count counts the files picked up, matched or not, that match the pattern in its body, every file when the body is empty, and DELETE /api/fileMessage/requests resets the journal, which also empties this page. Both are in the OpenAPI documentation.