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
payload	String,Stream	The raw inbound payload object to process. Attachment data should be removed and replaced with the attachment sys_id in the format "<x-attachment-data sys_id=>
headers	Object	An object containing the request headers.
params	Object	A key-value pair object of URL parameters.
request	GlideRecord	The record of the HTTP Request [x_snd_eb_http_request] being used.
options	Object	An object containing specific properties for processing.
options.is_stream	Boolean	True if the inbound payload is a stream.
log,console	Object	Object containing several functions that can be used for logging. info, warn, error and debug.
error	String	The error message to return from the script. Alternatively you can simply throw a string or Error and the system will take care of it.

XML Example

XML Payload

<!-- 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>

Extract attachments script

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

Script Include

// 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

JSON Payload

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

Extract attachments script

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