Fetching Attachments


Sometimes attachments details can be provided within another message which require additional API calls to fetch them. We recommend breaking this out using a Poller which will asynchronously fetch the attachments and then push them into Unifi for full tracking. This has a lot of benefits and follows Unifi best practice.

The basic flow is:

  1. Receive a message containing a list of attachment details to fetch from the other system.

  2. Process the message as normal and store the attachment details in the Stage just like any other field.

  3. In the Stage to Target script, loop through the attachments and execute an On-demand asynchronous Poller for each one.

  4. The Poller fetches the attachment and pushes it into Unifi just like any other inbound message. We use a Poller because it has it's own queue management and provides visibility for the transactions.

  5. Unifi processes the message and moves the attachment to the target record. The attachment is also recorded against the bond and the full transaction stack is created.


This example is based on receiving a message which contains a list of attachments that need to be fetched. You may need to adjust to your specific environment and requirements.

1. Poll Processor

Create a new Poll Processor (we recommend <Integration name> - Get Attachment). It will fetch a single attachment as required and push it into your integration attachment message.

  • Name: <Integration name> - Get Attachment

  • Integration: <Integration name>

  • Active: true

  • Run parallel: true

// Configure the new Poll Request record
(function (poll_request, poller, params) {
  // Params contain an attachment object containing details of the remote attachment
  poll_request.endpoint_url = params.attachment.url;

})(poll_request, poller, params);

2. Poller

Create a new Poller (we recommend <Integration name> - Get Attachment) and set it use the Poll Processor we've just created. For scheduling, set it to run On Demand.

  • Name: <Integration name> - Get Attachment

  • Poll processor: <Integration name> - Get Attachment

  • Integration: <Integration name>

  • Active: true

  • Run: On Demand

3. Add Attachment Message

You'll need a Message to handle the incoming attachment. You can either use an existing one you already have or create a new one. We recommend calling it AddAttachment.

Since Unifi will automatically recognise the attachment provided by the Poll Processor, the only mapping you need to configure here is the internal and external reference mapping.

// Set the internal and external values on the stage
stage.internal_reference = payload.internal_ref;
stage.external_reference = payload.external_ref;

4. Connection Variable

We need to tell the integration which Poller to use for processing the attachments. We do this with the Poller record sys_id. To prevent hard-coding it, we specify it in a connection variable. You'll need to make sure this variable is present on all connections you use.

  • Description: The sys_id of the Poller record that we execute to retrieve an attachment.

  • Key: get_attachment_poller_id

  • Value: <The Poller sys_id>

5. Inbound Message

This section describes what the message that receives the attachment URLs needs to do. You may consider doing this in a new Field and Field Map, or just update the relevant Message Scripts.

Store Attachments Details

When the attachments details are received, they are treated like any other field. Store them in the stage for visibility and later processing.

// Source to stage script
$stage.attachments = [].concat(payload.attachments);

Process Attachment Details with a Poller

In the Stage to Target script (either Message Script or Field Map), loop through the attachments and execute a Poller.

 *  This is the code for the message where the attachments are present in
 *  the payload. It assumes that we receive an array of attachment objects,
 *  with each object containing a parameter specifying the details where the
 *  attachment can be found.
 *  The Poller used is specified by connection variable 'get_attachment_poller_id'
 *  Example Attachment object from the payload
 *  {
 *    url: "https://someothersystem.com/attachments/my_file.txt",
 *    name: "my_file",
 *  }

// Stage to target script
if ($stage.attachments && $stage.attachments.length) {
  $stage.attachments.forEach(function (attachment) {
    x_snd_eb.Poller.execute(variables.get_attachment_poller_id, {
      internal_ref : bond.getValue('internal_reference'),
      external_ref : bond.getValue('external_reference'),
      attachment   : {
        url  : '' + attachment.url,
        name : '' + attachment.name


Now you've configured your inbound message, Poll Processor, Poller and AddAttachment message, it's time to test!