Response Attachments

The Response Attachments section allows you to add attachments to the response.

Simplest Way: Attachment Name

If you only need to attach one file and it is the same file for all responses, provide only the attachment name. MockMotor uses the name (case-sensitive!) to find an attachment from the environment Attachments page.

For this file, MockMotor uses the content type from its properties. Content-ID header is populated as “Content-ID-1”.

Place the attachment name into double or single quotes:

"Quarterly Report.xlsx"

Multiple Attachments By Name

When you need to attach multiple files, you need to provide a names sequence (for XML-based responses) or an array (for JS-based responses).

Content-ID headers are populated as “Content-ID-1”, “Content-ID-2”, and so on.

XML Responses

A sequence of names, according to XQuery syntax, is enclosed into round brackets:

("cat.png","mouse.png","hedgehog.png")

JSON Responses

A sequence of names, according to JS syntax, is enclosed into square brackets:

["cat.png","mouse.png","hedgehog.png"]

More Control

In addition to name, MockMotor allows specifying the content-type and content-id of the attachments.

The Content-Transfer-Encoding value is not yet configurable and is always set to binary.

XML Responses

To provide the attachment’s content-type and content-id for XML-based responses, use an XML fragment as below:

<attachment>
    <name>Environment-Canada-Post-Accounts-3.xlsx</name>
    <content-type>application/vnd.ms-excel</content-type>
    <content-id>CONTENTID200</content-id>
</attachment>

When you need to have multiple attachments, use a sequence:

(
<attachment>
    <name>Environment-Canada-Post-Accounts-3.xlsx</name>
    <content-type>application/vnd.ms-excel</content-type>
    <content-id>CONTENTID200</content-id>
</attachment>,
<attachment>
    <name>Environment-Canada-Post-Accounts-4.xlsx</name>
    <content-type>application/vnd.ms-excel</content-type>
    <content-id>CONTENTID201</content-id>
</attachment>
)

JSON Responses

To provide the attachment’s content-type and content-id for JSON-based responses, use a JSON object as below:

{
    "name":"Environment-Canada-Post-Accounts-3.xlsx",
    "content-type":"application/vnd.ms-excel",
    "content-id":"CONTENTID200"
}

When you need to have multiple attachments, use an array:

[
    {
        "name":"Environment-Canada-Post-Accounts-3.xlsx",
        "content-type":"application/vnd.ms-excel",
        "content-id":"CONTENTID200"
    },
    {
        "name":"Environment-Canada-Post-Accounts-4.xlsx",
        "content-type":"application/vnd.ms-excel",
        "content-id":"CONTENTID201"
    }
]

Scripting

You’re not limited to hard-coded file names. You can use scripting to dynamically select an appropriate attachment based on the request, mock account or any other condition.

XQuery/XML

To script the attachments in an XML-based response, use XQuery to create an XML fragment or a sequence of XML fragments.

For example, here the first attachment’s name is taken from the account properties, and the second one is conditional on the request element <tos/>:

(
    <attachment>
      <name>{$account/*:contractName}</name>
      <content-id>{concat('CID',$account/*:id)}</content-id>
    </attachment>,
    if( $input//*:tos ) then 
      <attachment>
      <name>Standard TOS.pdf</name>
      </attachment>
    else ()
)

Javascript/JSON

To script the attachments in a JSON-based response, use JS to create a JSON object or an array of JSON objects.

For example, here the first attachment’s name is taken from the account properties, and the second one is conditional on the request property tos:

var attachments = [];

attachments.push({"name":account.contractName,"content-id":"CID"+account.id});

if( input.tos ) attachments.push({"name":"Standard TOS.pdf"});

attachments; 

Note the attachments; line: the last evaluated expression becomes the result of the field.

Note on Non-English Names

MockMotor supports sending non-English attachment names. However, not all clients do support receiving them.

The non-US-ASCII file names are encoded according to RFC 2231. Up to this day, some of the existing client tools and frameworks cannot read names encoded like this. I do not know a better alternative though.

--ff70bc47a5874257b13badee5780e8a1
Content-Type: text/plain
Content-ID: <Content-ID-1>
Content-Disposition: attachment; 
  name*=utf-8''%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9%D0%A4%D0%B0%D0%B9%D0%BB.txt; 
  filename*=utf-8''%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9%D0%A4%D0%B0%D0%B9%D0%BB.txt
Content-Transfer-Encoding: binary

MIME/SWA

By default, attachments are added following the standard MIME convention. For XML responses it is also called SWA (SOAP with Attachments).

You can recognize MIME/SWA by its structure. Its top section has Content-Type multipart/related with the attribute type set to the content type of the response payload (text/xml in this case). Neither SOAP response nor headers have an explicit reference to the attachment by name or content-id.

HTTP/1.1 200 OK
Date: Thu, 31 May 2018 03:15:29 GMT
Content-Type: multipart/related; type="text/xml"; start="039ddbce300f461c8e17d4d6f8fcc271"; boundary="ff70bc47a5874257b13badee5780e8a1"

--ff70bc47a5874257b13badee5780e8a1
Content-Type: text/xml; charset=UTF-8
Content-ID: <039ddbce300f461c8e17d4d6f8fcc271>
X-MockMotor-Delay: 300

    ... SOAP response payload is here ...

--ff70bc47a5874257b13badee5780e8a1
Content-Type: text/plain
Content-ID: <Content-ID-1>
Content-Disposition: attachment; name=file.txt; filename=file.txt
Content-Transfer-Encoding: binary

Test
--ff70bc47a5874257b13badee5780e8a1--

The JSON-based responses with attachments have a similar structure except the type attribute has the application/json value.

MTOM/XOP

A more modern way to pass the large binary objects is to use MTOM/XOP format.

This format is only applicable to SOAP responses. Although you can use it with JSON responses too, the results likely won’t be recognized by either SOAP or REST clients.

Comparing to the SWA example above, the XOP response has the attribute type set to application/xop+xml.

However, the main difference is that the response payload must contain an XOP <Include/> element that has a reference to the attachment Content-ID. If such an element is missing, some of the platforms ignore the attachment as if it doesn’t exist.

HTTP/1.1 200 OK
Date: Thu, 31 May 2018 03:29:38 GMT
Content-Type: multipart/related; type="application/xop+xml"; boundary="1cfbcfcf5bd24ac4ac8c84e2d431bac7"; start="daf16aee1529464db80c1874f81d01b3"; start-info="text/xml"

--1cfbcfcf5bd24ac4ac8c84e2d431bac7
Content-Type: application/xop+xml; charset=UTF-8; type=text/xml
Content-ID: <daf16aee1529464db80c1874f81d01b3>

    ... SOAP response payload is here ...
    <data>
        <xop:Include href="cid:Content-ID-1" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
    </data>
    ...

--1cfbcfcf5bd24ac4ac8c84e2d431bac7
Content-Type: application/vnd.ms-excel
Content-ID: <Content-ID-1>
Content-Disposition: attachment; name="file.txt"; filename="file.txt"
Content-Transfer-Encoding: binary

Test
--1cfbcfcf5bd24ac4ac8c84e2d431bac7--