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.

Variables

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

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:

1. Open a record with a journal field, i.e. an Incident.

2. From the More options selector, choose Email. The Compose Email window will open.

3. 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).

4. Click the Source code button to view the HTML source code.

5. Select all the source code (Ctrl + A) and copy it (Ctrl + C).

6. Back in your Incident, go to a journal field, e.g. Additional Comments and paste in the HTML.

7. Wrap the comment in [code]...[/code] tags to tell ServiceNow to treat this comment as code.

8. 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.

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:

1. 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.

2. 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.

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:

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.

Setup

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

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.

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.

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.

Test

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