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

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

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

JSON Example