1 of 4

Attachments

Extracting Attachments

Introduction

Attachments can be extracted from payloads and saved before the payload is saved. This is highly recommended as it saves from storing the attachment itself in the payload on the HTTP Request record.

Attachment data should be extracted, saved as an attachment, and replaced with the attachment sys_id in the format <x-attachment-data sys_id="...">. Unifi will automatically collect the attachment ids, create Bonded Attachments for each of them, and finally move the attachments to the target record.

We strongly recommend streaming attachments when possible. Attachments can be streamed into Unifi which bypasses the need for extraction, supports binary file sharing, and also allows for sizes up to 50MB (providing your instance and integration configuration supports this).

This is available for all new integrations from Unifi 3.0.

For more information on configuring inbound streaming, please see our How to Handle Attachments guide.

Variables

Variable

Type

Description

XML Example

<!-- Example attachments payload structure -->
<eb:Attachments xmlns:eb="https://sharelogic.com/unifi">
    <eb:Attachment>
      <eb:FileName>Hello world.txt</eb:FileName>
      <eb:MimeCode>text/plain</eb:MimeCode>
      <eb:Data>SGVsbG8gd29ybGQudHh0</eb:Data>
    </eb:Attachment>
</eb:Attachments>

// Example extract attachments script using a Script Include
// for extracting Base64 from an XML payload.
// We rewrite the payload to pass back to Unifi
payload = unifi_util.extractAttachmentsFromXml(payload, request);

// Example script include extract for extracting Base64 attachment
// data from an XML payload.
// To be used with a Unifi Extract attachments script.
unifi_util.extractAttachmentsFromXml = function extractAttachmentsFromXml(payload, request) {

  // create a new standard XMLDocument so we can rewrite it on the fly
  var xml_doc = new XMLDocument(payload.toString()),
      attachment_container;

  function extract(node) {
    var result = null,
        name,
        tag;

    if (node.getNodeName() == 'eb:Attachment') {
      result = {};
      forEachNode(node.getChildNodes(), function (attr) {
        // convert eb:FileName to FileName
        var name = attr.getNodeName().split(':').pop();
        if (name == '#text') return;
        result[name] = '' + attr.getTextContent();
        if (name == 'Data') {
          attr.setTextContent(''); // remove the attachment data
        }
      });

      // Write the attachment using internal Unifi util
      //tag = '<x-attachment-data sys_id="abc123" />';
      tag = x_snd_eb.AttachmentHandler.saveAttachment(
        request, result.FileName, result.MimeCode, decodeData(result.Data));

      insertPointer(node, tag);
    }
  }

  function insertPointer(node, tag) {
    var id,
        data;
    // add the attachment pointer for the processor to pick up
    data = node.getElementsByTagName('eb:Data');
    if (data.getLength() &gt; 0) {
      xml_doc.setCurrent(data.item(0));
      xml_doc.setCurrent(xml_doc.createElement('x-attachment-data'));
      id = tag.match(/sys_id="(.+)"/);
      xml_doc.setAttribute('sys_id', id ? id[1] : 'unknown');
    }
  }

  function forEachNode(node_list, fn) {
    var len = node_list.getLength(),
        i;
    for (i = 0; i &lt; len; i++) {
      fn(node_list.item(i), i);
    }
  }

  function decodeData(data) {
    data = ('' + data).replace(/\s/g, '');
    if (global.snd_eb_util &amp;&amp; global.snd_eb_util.writeAttachment) {
      return GlideStringUtil.base64DecodeAsBytes(data);
    } else {
      return GlideStringUtil.base64Decode(data);
    }
  }

  attachment_container = xml_doc.getElementByTagName('eb:Attachments');
  if (attachment_container) {
    forEachNode(attachment_container.getChildNodes(), extract);
  }

  return xml_doc.toString();
};

JSON Example

{
  "attachment": {
     "FileName": "Hello world.txt",
     "MimeCode": "text/plain",
     "Data": "SGVsbG8gd29ybGQudHh0"
  }
}

// Example extract attachments script
// for extracting Base64 from an JSON payload.
// We rewrite the payload to pass back to Unifi
payload = (function extractAttachments(payload, request) {

  function saveAttachment(record, filename, content_type, data) {
    var id;

    if (typeof filename === 'undefined') {
      x_snd_eb.ws_console.warn('Ignoring attachment with missing filename attribute.');
      id = 'x-attachment-error-missing-filename';
    } else if (!filename) {
      x_snd_eb.ws_console.warn('Ignoring attachment with empty filename attribute.');
      id = 'x-attachment-error-filename-is-empty';
    } else {  
      // use x_snd_eb scope to force using the scoped version of GSA
      id = new x_snd_eb.GlideSysAttachment().writeBase64(record, filename, content_type, data);
      x_snd_eb.ws_console.trace('Extracted attachment [' + filename + ':' + content_type + ']' +
        ' to record [' + id + ']' +
        ' for [' + record.getTableName() + ':' + record.sys_id + ']');
    }

    // return the original tag with the sys_id of the new attachment record
    // so Unifi can pick it up in processing later on
    return '[x-attachment-data sys_id="' + id + '" /]';
  }

  var obj = JSON.parse(payload);

  // replace the attachment data with the sys_attachment pointer
  obj.attachment.Data = saveAttachment(
    request, 
    obj.attachment.FileName, 
    obj.attachment.MimeCode, 
    obj.attachment.Data
  );

  return JSON.stringify(obj);
})(payload, request);

Fetching Attachments

Introduction

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:

Receive a message containing a list of attachment details to fetch from the other system.
Process the message as normal and store the attachment details in the Stage just like any other field.
In the Stage to Target script, loop through the attachments and execute an On-demand asynchronous Poller for each one.
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.
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.

Setup

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);

// Process the request e.g. by executing a web service and returning the response
(function (poll_request, poller, connection, params) {

  var request, response;
  
  request = new sn_ws.RESTMessageV2();
  request.setHttpMethod('GET');
  request.setEndpoint(poll_request.endpoint_url);
  request.setRequestHeader('Content-Type','application/json');
  request.setBasicAuth(connection.getBasicAuthUser(), connection.getBasicAuthPassword());
  
  // Save the response as a new attachment (on the poll request)
  request.saveResponseBodyAsAttachment(
    poll_request.getTableName(), poll_request.sys_id, params.attachment.name
  );
  
  response = request.execute();
  
  poll_request.response_code   = response.getStatusCode();
  poll_request.response_status = response.getErrorMessage();
  if (response.haveError()) {
    throw '\nResponse Code: ' + response.getErrorCode() + '\nResponse error: ' + response.getErrorMessage();
  }
  
  // Return the sys_id of the saved attachment
  answer = response.getResponseAttachmentSysid() + '';

})(poll_request, poller, connection, params);

// Process the response returned by the request script
// The 'answer' variable from the request script is passed in here as the 'response' parameter 
(function (poll_request, poller, response, params) {

  // Establish the environment
  var poll_helper = new x_snd_eb.PollHelper(poll_request);
  var info = [
    'Document: ' + params.internal_ref,
    '- Attachment file name: ' + params.attachment.name,
    '- Attachment id: ' + response
  ];

  // The response should be the sys_id of the created attachment
  params.attachment.data = '<x-attachment-data sys_id="' + response + '" />';
  
  // Build the payload for Unifi
  var payload = {
    external_ref : params.external_ref,
    internal_ref : params.internal_ref,
    attachment   : params.attachment
  };
  
  // Submit the message into Unifi
  poll_helper.processInbound({
    message_name : 'AddAttachment',
    payload : JSON.stringify(payload)
  });

  poll_request.response_status = info.join('\n');

})(poll_request, poller, response, 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
      }
    });
  });
}

Test

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

Embedded Attachments

Introduction

Attachments in ServiceNow are normally attached to the records they belong to, making it easy to identify and share those attachments over an integration. Embedded attachments require a bit more effort to integrate since they can belong to other records, or in some cases, no record at all. They are typically found inside journal fields.

Use Case

The use case being looked at in this example is embedding attachments in the Additional Comments field using HTML inside [code] tags so lengthy comments such as operational checks can be shared with third parties directly from the instance.

To recreate this scenario:

Open a record with a journal field, i.e. an Incident.
From the More options selector, choose Email. The Compose Email window will open.
Copy/paste or drag an image into the email composer. (In Windows, you can use Windows Key + Shift + S to take a screenshot and then Ctrl + V to paste it into the formatter).
Click the Source code button to view the HTML source code.
Select all the source code (Ctrl + A) and copy it (Ctrl + C).
Back in your Incident, go to a journal field, e.g. Additional Comments and paste in the HTML.
Wrap the comment in [code]...[/code] tags to tell ServiceNow to treat this comment as code.
If the record and field is integrated, the field will be shared over the integration, but the other system will not have the attachment so the image will not show.

Note: [code] tags will only be rendered if the glide.ui.security.allow_codetag system property is enabled.

Automatic Embedding

We can allow the integration to share embedded attachments with some modification to the outbound mapping scripts.

In this example, we are sharing a journal field so will modify the Field Map for Journal fields. We want the attachment data to be automatically embedded as base64 instead of sending the sys_attachment reference.

1. Open the Field Map

Open Integration Designer and navigate to the Field Map you want to modify. Find the Source to Stage mapping script in theOutbound panel.

2. Embed Image Attachments Function

Copy the function below into your Source to Stage mapping script. This function accepts some text and updates all<img> tags that reference the sys_attachment table.

3. Modify Journal Entries

The final step is to update the same Field Map to use the new embedImageAttachments() function that you've just added.

Add the code to the bottom of the same Source to Stage mapping script and modify as required.

This code is designed for the out of box Journal field map.

4. Build

Build your integration to push the Field Map changes to all the messages. You can now test.

Known Limitations

File size

Embedding attachments in this way will mean the maximum string length imposed by ServiceNow of 5mb will be easy to reach. Since base64 is a 4/3 compression, you have a realistic limit of around 3mb of images which can be transferred this way in any single request.

Instance security

This approach is not considered secure since it is possible for malicious Javascript to be rendered in the [code] tags.

The glide.ui.security.allow_codetag system property is responsible for rendering [code] tags. This is typically disabled as part of Instance Security Hardening.

If the property is disabled then [code] tags will not be rendered. Both systems must have this property enabled for this solution to work.

Alternative Approaches

Some alternative approaches to embedding attachments in this way are:

Create a document containing the images and upload it as an attachment on the record. If you are streaming attachments, you will be able to share a file up to 50mb in size.
Upload the images separately as attachments and reference them in your comments. If you are streaming attachments, each image could be up to 50mb in size.

Embedded Attachments

Introduction

Use Case

To recreate this scenario:

Open a record with a journal field, i.e. an Incident.
From the More options selector, choose Email. The Compose Email window will open.
Copy/paste or drag an image into the email composer. (In Windows, you can use Windows Key + Shift + S to take a screenshot and then Ctrl + V to paste it into the formatter).
Click the Source code button to view the HTML source code.
Select all the source code (Ctrl + A) and copy it (Ctrl + C).
Back in your Incident, go to a journal field, e.g. Additional Comments and paste in the HTML.
Wrap the comment in [code]...[/code] tags to tell ServiceNow to treat this comment as code.
If the record and field is integrated, the field will be shared over the integration, but the other system will not have the attachment so the image will not show.

Note: [code] tags will only be rendered if the glide.ui.security.allow_codetag system property is enabled.

Automatic Embedding

We can allow the integration to share embedded attachments with some modification to the outbound mapping scripts.

1. Open the Field Map

Open Integration Designer and navigate to the Field Map you want to modify. Find the Source to Stage mapping script in theOutbound panel.

2. Embed Image Attachments Function

Copy the function below into your Source to Stage mapping script. This function accepts some text and updates all<img> tags that reference the sys_attachment table.

function embedImageAttachments(text, options) {

  function getAttachment(attachment_id) {
    var attachment = new GlideRecord('sys_attachment');
    return attachment.get(attachment_id) ? attachment : null;
  }

  function humanFileSize(size) {
    var i = size == 0 ? 0 : Math.floor(Math.log(size) / Math.log(1024));
    return (size / Math.pow(1024, i)).toFixed(2) * 1 + ' ' + ['B', 'kB', 'MB', 'GB', 'TB'][i];
  }

  function findImages(text) {
    var match_img = /<img\s+\w+=(\\?["'])[\s\S]+?\1\s*\/?>/;
    var tags = [];
    var start, end, match;
    while ((start = text.indexOf('<img')) > -1) {
      text = text.slice(start);
      match = text.match(match_img);
      if (!match) continue;
      end = match[0].length;
      tags.push({
        start: start,
        end: start + end,
        tag: text.slice(0, end + 1)
      });
      text = text.slice(end + 1);
    }
    return tags;
  }

  function embedImages(text) {
    var match_src = /src=\\?(["'])(\/?sys_attachment\.do\?(?:[\s\S]+&)*sys_id=([a-f0-9]{32})(?:&.+)*)\1/gm;
    var images = findImages(text);
    var output = '';
    var position = 0;
    if (!images.length) {
      return text;
    }
    images.forEach(function (image) {
      output += text.slice(position, image.start);
      output += image.tag.replace(match_src, replaceImageSrc);
      position = image.end + 1;
    });
    output += text.slice(position);
    return output;
  }

  function _log(text) {
    $stage.$embedded_attachment_logs.push(text);
    return text;
  }

  function replaceImageSrc(match, quote, src, attachment_id) {
    var attachment = getAttachment(attachment_id);
    var result = '';
    var data_uri;

    if (!attachment) {
      _log.warn(_log('Cannot embed image attachment ' + attachment_id + '; invalid attachment.'));
      return match;
    }

    _log('Embedding image attachment ' + attachment_id + '.');

    data_uri = 'data:' + attachment.content_type + ';base64,';
    $stage.$payload_size = $stage.$payload_size - src.length + data_uri.length + (attachment.size_bytes * 4/3);

    if ($stage.$payload_size > $stage.$payload_size_max) {
      error = 'Unable to embed image attachments; combined file size is too large to send ' +
            '(' + 
              humanFileSize($stage.$payload_size) + ' > ' +
              humanFileSize($stage.$payload_size_max) +
            ').';
      throw new Error(_log(error));
    }

    // this tag will be automatically replaced with base64 during send
    data_uri += '<x-attachment-data sys_id="' + attachment_id + '" />';

    result += match.replace(src, data_uri);

    // ensure file name is included
    if (match.indexOf('name=' + quote) == -1) {
      result += ' name=' + quote + attachment.file_name + quote;
    }
    return result;
  }

  // ensure objects are strings (e.g. GlideElement objects)
  text = String(text);

  // allow space for the actual message outside of the text with embedded attachments
  var payload_size_no_attachments = 5 * 1024;

  // track embedded attachment size as part of the full payload
  $stage.$payload_size = ($stage.$payload_size || payload_size_no_attachments) + text.length;

  // scoped string limit is 5MB
  $stage.$payload_size_max = $stage.$payload_size_max || (5 * 1024 * 1024);

  // make it easy to debug                                          
  $stage.$embedded_attachment_logs = $stage.$embedded_attachment_logs || [];       

  return embedImages(text);
}

3. Modify Journal Entries

The final step is to update the same Field Map to use the new embedImageAttachments() function that you've just added.

Add the code to the bottom of the same Source to Stage mapping script and modify as required.

This code is designed for the out of box Journal field map.

$stage.$[field.element].forEach(function (log) {
    log.text = embedImageAttachments(log.text);
});

4. Build

Build your integration to push the Field Map changes to all the messages. You can now test.

Known Limitations

File size

Instance security

This approach is not considered secure since it is possible for malicious Javascript to be rendered in the [code] tags.

The glide.ui.security.allow_codetag system property is responsible for rendering [code] tags. This is typically disabled as part of Instance Security Hardening.

If the property is disabled then [code] tags will not be rendered. Both systems must have this property enabled for this solution to work.

Alternative Approaches

Some alternative approaches to embedding attachments in this way are:

Create a document containing the images and upload it as an attachment on the record. If you are streaming attachments, you will be able to share a file up to 50mb in size.
Upload the images separately as attachments and reference them in your comments. If you are streaming attachments, each image could be up to 50mb in size.

Extracting Attachments

Introduction

Attachments can be extracted from payloads and saved before the payload is saved. This is highly recommended as it saves from storing the attachment itself in the payload on the HTTP Request record.

This is available for all new integrations from Unifi 3.0.

For more information on configuring inbound streaming, please see our How to Handle Attachments guide.

Variables

Variable

Type

Description

XML Example

<!-- Example attachments payload structure -->
<eb:Attachments xmlns:eb="https://sharelogic.com/unifi">
    <eb:Attachment>
      <eb:FileName>Hello world.txt</eb:FileName>
      <eb:MimeCode>text/plain</eb:MimeCode>
      <eb:Data>SGVsbG8gd29ybGQudHh0</eb:Data>
    </eb:Attachment>
</eb:Attachments>

// Example extract attachments script using a Script Include
// for extracting Base64 from an XML payload.
// We rewrite the payload to pass back to Unifi
payload = unifi_util.extractAttachmentsFromXml(payload, request);

// Example script include extract for extracting Base64 attachment
// data from an XML payload.
// To be used with a Unifi Extract attachments script.
unifi_util.extractAttachmentsFromXml = function extractAttachmentsFromXml(payload, request) {

  // create a new standard XMLDocument so we can rewrite it on the fly
  var xml_doc = new XMLDocument(payload.toString()),
      attachment_container;

  function extract(node) {
    var result = null,
        name,
        tag;

    if (node.getNodeName() == 'eb:Attachment') {
      result = {};
      forEachNode(node.getChildNodes(), function (attr) {
        // convert eb:FileName to FileName
        var name = attr.getNodeName().split(':').pop();
        if (name == '#text') return;
        result[name] = '' + attr.getTextContent();
        if (name == 'Data') {
          attr.setTextContent(''); // remove the attachment data
        }
      });

      // Write the attachment using internal Unifi util
      //tag = '<x-attachment-data sys_id="abc123" />';
      tag = x_snd_eb.AttachmentHandler.saveAttachment(
        request, result.FileName, result.MimeCode, decodeData(result.Data));

      insertPointer(node, tag);
    }
  }

  function insertPointer(node, tag) {
    var id,
        data;
    // add the attachment pointer for the processor to pick up
    data = node.getElementsByTagName('eb:Data');
    if (data.getLength() &gt; 0) {
      xml_doc.setCurrent(data.item(0));
      xml_doc.setCurrent(xml_doc.createElement('x-attachment-data'));
      id = tag.match(/sys_id="(.+)"/);
      xml_doc.setAttribute('sys_id', id ? id[1] : 'unknown');
    }
  }

  function forEachNode(node_list, fn) {
    var len = node_list.getLength(),
        i;
    for (i = 0; i &lt; len; i++) {
      fn(node_list.item(i), i);
    }
  }

  function decodeData(data) {
    data = ('' + data).replace(/\s/g, '');
    if (global.snd_eb_util &amp;&amp; global.snd_eb_util.writeAttachment) {
      return GlideStringUtil.base64DecodeAsBytes(data);
    } else {
      return GlideStringUtil.base64Decode(data);
    }
  }

  attachment_container = xml_doc.getElementByTagName('eb:Attachments');
  if (attachment_container) {
    forEachNode(attachment_container.getChildNodes(), extract);
  }

  return xml_doc.toString();
};

JSON Example

{
  "attachment": {
     "FileName": "Hello world.txt",
     "MimeCode": "text/plain",
     "Data": "SGVsbG8gd29ybGQudHh0"
  }
}

// Example extract attachments script
// for extracting Base64 from an JSON payload.
// We rewrite the payload to pass back to Unifi
payload = (function extractAttachments(payload, request) {

  function saveAttachment(record, filename, content_type, data) {
    var id;

    if (typeof filename === 'undefined') {
      x_snd_eb.ws_console.warn('Ignoring attachment with missing filename attribute.');
      id = 'x-attachment-error-missing-filename';
    } else if (!filename) {
      x_snd_eb.ws_console.warn('Ignoring attachment with empty filename attribute.');
      id = 'x-attachment-error-filename-is-empty';
    } else {  
      // use x_snd_eb scope to force using the scoped version of GSA
      id = new x_snd_eb.GlideSysAttachment().writeBase64(record, filename, content_type, data);
      x_snd_eb.ws_console.trace('Extracted attachment [' + filename + ':' + content_type + ']' +
        ' to record [' + id + ']' +
        ' for [' + record.getTableName() + ':' + record.sys_id + ']');
    }

    // return the original tag with the sys_id of the new attachment record
    // so Unifi can pick it up in processing later on
    return '[x-attachment-data sys_id="' + id + '" /]';
  }

  var obj = JSON.parse(payload);

  // replace the attachment data with the sys_attachment pointer
  obj.attachment.Data = saveAttachment(
    request, 
    obj.attachment.FileName, 
    obj.attachment.MimeCode, 
    obj.attachment.Data
  );

  return JSON.stringify(obj);
})(payload, request);

Fetching Attachments

Introduction

The basic flow is:

Receive a message containing a list of attachment details to fetch from the other system.
Process the message as normal and store the attachment details in the Stage just like any other field.
In the Stage to Target script, loop through the attachments and execute an On-demand asynchronous Poller for each one.
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.
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.

Setup

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);

// Process the request e.g. by executing a web service and returning the response
(function (poll_request, poller, connection, params) {

  var request, response;
  
  request = new sn_ws.RESTMessageV2();
  request.setHttpMethod('GET');
  request.setEndpoint(poll_request.endpoint_url);
  request.setRequestHeader('Content-Type','application/json');
  request.setBasicAuth(connection.getBasicAuthUser(), connection.getBasicAuthPassword());
  
  // Save the response as a new attachment (on the poll request)
  request.saveResponseBodyAsAttachment(
    poll_request.getTableName(), poll_request.sys_id, params.attachment.name
  );
  
  response = request.execute();
  
  poll_request.response_code   = response.getStatusCode();
  poll_request.response_status = response.getErrorMessage();
  if (response.haveError()) {
    throw '\nResponse Code: ' + response.getErrorCode() + '\nResponse error: ' + response.getErrorMessage();
  }
  
  // Return the sys_id of the saved attachment
  answer = response.getResponseAttachmentSysid() + '';

})(poll_request, poller, connection, params);

// Process the response returned by the request script
// The 'answer' variable from the request script is passed in here as the 'response' parameter 
(function (poll_request, poller, response, params) {

  // Establish the environment
  var poll_helper = new x_snd_eb.PollHelper(poll_request);
  var info = [
    'Document: ' + params.internal_ref,
    '- Attachment file name: ' + params.attachment.name,
    '- Attachment id: ' + response
  ];

  // The response should be the sys_id of the created attachment
  params.attachment.data = '<x-attachment-data sys_id="' + response + '" />';
  
  // Build the payload for Unifi
  var payload = {
    external_ref : params.external_ref,
    internal_ref : params.internal_ref,
    attachment   : params.attachment
  };
  
  // Submit the message into Unifi
  poll_helper.processInbound({
    message_name : 'AddAttachment',
    payload : JSON.stringify(payload)
  });

  poll_request.response_status = info.join('\n');

})(poll_request, poller, response, 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

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
      }
    });
  });
}

Test

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