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.

Fetching attachments dynamically using a Poller

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

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

Setup script

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

Request script

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

Response script

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

Payload to Stage

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

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

Stage to Target

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