Attachment Transformer Reference
| Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version. |
Use an attachment transformer to set, remove, or copy attachments on the outbound scope of a message. To learn more about message scopes, refer to Mule Concepts.
Each Mule message consists of two parts. The header contains metadata pertaining to the message, such as the message type and the encoding protocol used to format the payload. The payload holds the data that typically gets processed by the Mule application flow, then dispatched to one or more external parties. This payload may also include a sub-section that holds any attachments (such as text, images, or applications) that travel with the message.
When an attachment is received into a flow along with its associated message, it is considered an inbound property, and it remains active (that is, affixed to its parent message) as long as that message remains within the same flow. Note that the attachment does not automatically become part of the processed message that gets sent out of the flow by the outbound connector. For that to happen, you must explicitly make it an outbound property by reattaching it to the message with the attachment transformer. Alternatively, you can designate a different attachment to leave the flow along with the processed message.
The attachment transformer can use expressions that evaluate the content of the current message as well as the current state of the Mule environment in order to make a runtime determination as to which specific attachment leaves the flow with the current message. For example, the Attachment transformer can retrieve a photo that matches some content in the message payload and affix it to the message.
Attachments and Transports
The attachment transformer is very similar in functionality to the property transformer. However, attachments are only supported by the following transports:
-
Axis
-
Email
-
HTTP
-
VM
If you use the attachment transformer to affix an attachment to a message and the message then exits the flow via a transport that does not support attachments, the attachments are lost.
Configuration
Studio Visual Editor
| Field | Description |
|---|---|
Display Name |
Attachment - Customize to display a unique name for the transformer in your application. doc:name="Attachment" |
Operation |
Set Attachment - Select to set a new attachment on the outbound scope of your message. |
Remove Attachment - Select to delete an existing attachment from your message to remove it from the outbound scope. |
|
Copy Attachments - Select to copy one or more existing attachments from the inbound scope onto the outbound scope of your message. |
|
Name |
String or Mule Expression - Specify the name for the attachment that you are creating, or identify the name of the attachment that you are copying or removing. If you are copying or removing attachments, this field accepts a wildcard "*" character. attachmentName="MyAttachmentName" |
Value |
String or Mule Expression - This field displays only if you are setting a new attachment. Specify the value using either a string or a Mule expression. value="MyAttachmentValue" |
Content Type |
Select from drop-down list - This field displays only if you are setting a new attachment. Select the content type of the attachment from the drop-down list (shown in screenshot above.) contentType="text/plain" |
XML Editor or Standalone
# Set attachment
<set-attachment attachmentName="IMG_001" doc:name="Attach Photo" value="IMG_001.jpeg"/>
# Remove attachment
<remove-attachment attachmentName="AttachmentForRemoval" doc:name="Delete Attachment"/>
# Copy attachment
<copy-attachments attachmentName="IMG*" doc:name="Copy All IMG Attachments"/>| Element | Description |
|---|---|
set-attachment |
Set a new attachment on the outbound scope of your message. |
remove-attachment |
Delete an existing attachment from your message to remove it from the outbound scope. |
copy-attachments |
Copy one or more existing attachments from the inbound scope onto the outbound scope of your message. |
| Element Attribute | Description |
|---|---|
doc:name |
Customize to display a unique name for the transformer in your application, as shown in the examples above. Note: Attribute not required in Mule Standalone configuration. |
attachmentName |
The name of the attachment that you are setting, copying, or removing. Can be a string or a Mule expression. Note: If you are using the remove-attachment or copy-attachments element, you can use a wildcard "" character. For example, a copy-attachments transformer with an attachment name "IMG" copies all attachments whose names begin with "IMG", from the inbound scope to the outbound scope. |
value |
The value of the attachment that you are setting. This attribute is only relevant for the set-attachment element. Can be a string or a Mule expression. |
contentType |
The MIME format for the attachment string. Supported formats:
|
Code Example
The following example sends a POST request to http://www.example.com/test, with ContentType: text/plain and with two parts: one with name key1 and content value1, and the other one with name key2 and content value2.
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd">
<http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8082" doc:name="HTTP_Request_Configuration"/>
<flow name="test_flow">
<http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
<set-attachment attachmentName="key1" value="value1" contentType="text/plain" doc:name="Attachment1"/>
<set-attachment attachmentName="key2" value="value2" contentType="text/plain" doc:name="Attachment2"/>
<http:request config-ref="HTTP_Request_Configuration" path="test" method="POST" port="8082"/>
</flow>
</mule>See Also
-
Refer to Mule Concepts to learn more about message scopes.
-
Read about related transformers, the property transformer, the variable transformer, and the session variable transformer, which you can use to set properties and variables for different scopes.