Sending Attachments

Overview

Unifi supports sending attachments outbound in two ways:

1. Streaming attachments

2. Embedding attachments in the message payload

Both approaches use the AttachmentSender class to retrieve bonded attachments that are ready to be sent.

---

Enable Attachment Sending

Attachment sending is configured per outbound message via Message → Outbound → Attachments.

The following options control how and when attachments are sent:

Send Attachments

When Send Attachments is enabled, the message is marked as attachment-capable. This allows the message to access attachments through the AttachmentSender class during outbound processing, but does not by itself cause attachments to be sent.

Maximum Attachments to Send

The Maximum attachments to send setting limits the number of attachments that the message is permitted to send via AttachmentSender. This limit is enforced during outbound execution and applies regardless of whether attachments are streamed or embedded.

Attachment Added

When Attachment added is enabled, the message is triggered immediately when an attachment is added to the source record. In this mode, attachments are sent regardless of the message’s normal trigger conditions.

This allows attachments to be sent as soon as they are created, rather than waiting for a state change or other business event.

---

AttachmentSender

AttachmentSender is responsible for iterating over Bonded Attachments associated with the current outbound transaction. It is typically used in the Stage to Target script of a message to fetch and selectively send attachments.

An AttachmentSender instance is created using the current transaction and bond:

var sender = new x_snd_eb.AttachmentSender(transaction, bond);

Attachments are accessed sequentially using:

sender.next();

Each call to sender.next() advances to the next eligible attachment, populates the sender with metadata for that attachment, and marks the associated Bonded Attachment record as Sent.

Commonly Used Properties

When an attachment is available, the following properties are exposed on the sender:

• sender.attachment_id — the sys_id of the attachment

• sender.attachment_name — the attachment file name

• sender.attachment_type — the attachment MIME type

Attachment Selection

The set of attachments exposed by AttachmentSender is automatically constrained by the integration’s attachment configuration, such as:

• Maximum attachment size

• Maximum number of attachments

Only attachments that meet these criteria are made available to the message.

Accessing Attachment Content

In addition to attachment metadata, AttachmentSender provides helper methods for accessing attachment content:

• getAttachmentContent() Returns the attachment content as a string. This method only supports .csv, .json, and .txt files and returns up to 5 MB of data.

• getAttachment() Returns the current sys_attachment GlideRecord for the attachment being processed.

These methods are intended for scenarios where attachment content must be inspected or transformed before being sent, rather than streamed directly.

---

Streaming Attachments

Overview

Streaming attachments sends the attachment as the outbound request payload, rather than embedding it inside a structured message.

Key characteristics:

• Exactly one attachment may be streamed

• The attachment is streamed directly from ServiceNow

• The payload must be a sys_attachment:<attachment_sys_id> reference

• The Content-Type header must be set explicitly

Streaming is typically used when the message itself represents the attachment.

---

Example Stage to Request Script (Streaming)

(function processStageToRequest(request, stage, transaction, message, bond, scratchpad) {

  var sender = new x_snd_eb.AttachmentSender(transaction, bond);
  sender.next();

  var file_name = sender.attachment_name;
  var mime_type = sender.attachment_type;
  var attach_id = sender.attachment_id;
  var reference = bond.getValue('external_reference');

  //-----------------------
  // Path construction
  //-----------------------
  scratchpad.file_name = encodeURIComponent(file_name);
  scratchpad.reference = encodeURIComponent(reference);

  // Example endpoint: ?file_name=${scratchpad.file_name}&reference=${scratchpad.reference}

  //-----------------------
  // Headers construction
  //-----------------------
  scratchpad.headers = {
    "Content-Type": mime_type
  };

  //-----------------------
  // Payload construction
  //-----------------------
  // This string triggers attachment streaming outbound
  payload = 'sys_attachment:' + attach_id;

})(request, stage, transaction, message, bond, scratchpad);

---

When to Use Streaming

Use streaming when:

• The outbound message is the attachment

• The target endpoint expects raw binary data

• Only one attachment is required

---

Embedding Attachments

Overview

Embedding attachments places attachment data inside a structured payload, such as JSON or XML.

Key characteristics:

• Supports single or multiple attachments

• Attachments are embedded inline

• Encoding is handled automatically

• Payload structure is fully controlled by the integration

Embedding supports multiple attachments, but iteration is only required when the target API explicitly supports or expects them.

---

Attachment Data Placeholder

To embed attachment data, use the following placeholder tag in the payload template:

<x-attachment-data sys_id="sys_id"></x-attachment-data>

At runtime, Unifi replaces this tag with the Base64-encoded attachment content for the referenced attachment.

The placeholder is used to replace embedded attachment content so that attachment data does not need to be stored in request payloads, avoiding unnecessary load on the database and application server.

The <x-attachment-data> element can be self-closing (<x-attachment-data ... />), but in some instances an explicitly closed form (<x-attachment-data ...></x-attachment-data>) is required.

---

Placement of <x-attachment-data>

The <x-attachment-data> tag is used whenever attachments are embedded, regardless of payload format.

What differs is where the tag is defined:

• Message Templates The tag is placed in the outbound template and processed as part of template rendering.

• Script-built payloads (for example JSON) The tag is added directly to the payload object/string in the Stage to Request script.

In both cases, Unifi replaces the tag at send time with the Base64-encoded attachment content for the referenced attachment.

---

Example Stage to Request Script (Embedding)

(function processStageToRequest(request, stage, transaction, message, bond, scratchpad) {

  var sender = new x_snd_eb.AttachmentSender(transaction, bond);
  scratchpad.attachments = [];

  while (sender.next()) {
    scratchpad.attachments.push({
      id: sender.attachment_id,
      name: encodeURIComponent(sender.attachment_name),
      mime: sender.attachment_type
    });
  }

})(request, stage, transaction, message, bond, scratchpad);

For single-attachment messages, this will typically result in one attachment entry. For multi-attachment messages, iteration is required and expected.

The number of attachments returned is automatically constrained by integration attachment configuration.

---

Example Template (Embedding)

For integrations using the Message Template script, embedded attachments are typically represented as a single element where:

• The file name and MIME type are expressed as attributes

• The Base64 content is contained within the element body

This approach is commonly used for SOAP and other XML-based integrations, where the <x-attachment-data> tag is placed directly in the message template and processed during payload rendering.

<documents>
  <jelly:forEach var="att" items="${JS:scratchpad.attachments}">
    <document fileName="${HTML:att.name}" mimeType="${HTML:att.mime}">
      <x-attachment-data sys_id="${HTML:att.id}"></x-attachment-data>
    </document>
  </jelly:forEach>
</documents>

For integrations where the payload is constructed directly in the Stage to Request script (for example JSON-based REST APIs), the same <x-attachment-data> mechanism is used, but the tag is included in the script-generated payload instead of a template.

In all cases, Unifi replaces the <x-attachment-data> tag at send time with the Base64-encoded attachment data for the referenced attachment.

---

Summary Comparison

Feature	Streaming	Embedding
Attachments supported	One	One or many
Iteration required	No	Only if message supports multiple
Payload type	Raw binary	Structured (JSON / XML)
Trigger mechanism	sys_attachment:<id>	<x-attachment-data>
Encoding	Native stream	Base64
Typical use case	File upload endpoints	Structured APIs