Some integrations will not have a Message that closes the Bond. In these situations, it is preferable to close any open Bonds manually from a business rule on the Target table, e.g. when an Incident is closed . The following business rule script will close all the Bonds for a given record:

(function executeRule(current, previous /*null when async*/) {
  var bond;
 
  bond = new GlideRecord('x_snd_eb_bond');
  bond.addQuery('document', '=', current.sys_id);
  bond.addQuery('state', '!=', 'Closed');
  bond.query();
 
  while (bond.next()) {
    bond.state = 'Closed';
    bond.update();
  }
 
})(current, previous);

Attachments can be sent either as a stream or embedded in the payload as Base64.

In this guide, you will configure a dedicated Message as part of the Incident Guide Integration (created when following the Bidirectional Asynchronous Incident Guide). It is assumed that the Process, Web Service, Integration & Connection are already in place (if not, please ensure that those elements are in place before continuing).

The components to configure are as follows:

• Message

• Scripted REST Resource

This guide is supplementary to the Bidirectional Asynchronous Incident Guide and assumes the Process (& subsequent Scripted REST Resources) are already in place (See the Web Service page of that guide for details).

We will now examine the automatically generated Attachment Resource. If you are manually updating an existing Resource to cater for inbound streaming, ensure that it looks like the this.

Attachment Resource

The following code is extracted from the automatically generated Attachment Scripted REST Resource:

(function process( /*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

    var helper = new x_snd_eb.RestHelper('incident_guides'); // the API name of the Unifi Process
    processAttachment(helper.getRequest().getRecord());
    helper.processRequest(request, response, 'POST'); // the HTTP method of the resource

    /**
     * This scripted REST API allows an attachment to be sent into Unifi in a
     * similar way to the OOB api/now/attachment REST API, but it processes it
     * in Unifi.
     *
     */
    function processAttachment(target_record) {
        var file_name = request.queryParams.file_name;
        var reference = request.queryParams.reference;
        var mime_type = request.getHeader('Content-Type');

        if (!file_name || !reference || !mime_type) return;

        var ga = new GlideSysAttachment();

        // save the body to an attachment on the request
        var attachment_id = ga.writeContentStream(target_record, file_name, mime_type, request.body.dataStream);

        // return custom payload for the body to process
        helper._getRequestBody = function _getRequestBody() {
            return '{\n' +
                '"message":    { "name": "AddAttachment" },\n' +
                '"reference":  "' + reference + '",\n' +
                '"attachment": "<x-attachment-data sys_id="' + attachment_id + '" />"\n' +
                '}';
        };
    }

})(request, response);

With the Message & Scripted REST Resource in place, you are now ready to Test the AddAttachment Message.

Scope

This document will guide you through the process of configuring an OAuth Connection for your Unifi Integration (ServiceNow to ServiceNow). This will involve making configuration changes in both the identity provider and identity consumer instances. As such, this guide will examine the changes for each instance separately on the subsequent pages.

Approach

In this guide, you will configure an additional OAuth Connection to another ServiceNow instance as part of the Incident Guide Integration (created when following the Bidirectional Asynchronous Incident Guide). The external instance will act as the Identity Provider whilst the original instance will act as the Identity Consumer.

It is assumed that the Integration has been configured, packaged and moved to the external instance (see here for details). Therefore, the Process, Web Service & Integration are already in place (if not, please ensure that at least those elements are in place before continuing).

Sometimes a polling integration that is fetching data from another system is required to handle response payloads larger than the 5MB limit imposed by ServiceNow. The normal setup for a Poll Processor includes the response payload being returned as a string in the Request script. Here we look at an alternative approach which avoids handling the response payload as a string and so avoids the 5MB string limit.

Alternative approach for response payloads > 5MB:

1. Make the request (using RESTMessageV2()).

2. Save the response as an attachment on a record (using saveResponseBodyAsAttachment()).

3. Pass the attachment sys_id through (using getResponseAttachmentSysid()).

4. Fetch it and do something with the newly generated attachment - passing the stream of the attachment on to be processed however required, e.g. text/xml processing.

Example Use Case

The following example is taken from our Incident Attachment Poller Guide.

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.file_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 = [
        'Incident : ' + params.int_ref,
        '- Attachment file name: ' + params.attachment.file_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 = {
        sys_id : params.ext_ref,
        correlation_id : params.int_ref,
        attachment : params.attachment
    };

    // Submit the message into Unifi
    poll_helper.processInbound({
        message_name : 'AddAttachmentInbound',
        payload : JSON.stringify(payload)
    });

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

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

In our example we've taken the inbound attachment, built a payload and passed it to Unifi to process.

We recommend customers using outbound OAuth use this scheduled job script to ensure outbound OAuth connections remain alive, as explained in this KB Article from ServiceNow.

Without this job, the refresh token will eventually expire which means ServiceNow will no longer be able to retrieve an access token. This in turn will cause outbound requests to fail.

If your OAuth service is including refresh tokens with each access token request, this job may not be required.

This script has been reformatted from the KB Article for ease of use.

function refreshAccessToken(requestorId, oauthProfileId, token) {
    if (!(token && requestorId && oauthProfileId)) return;

    var tokenRequest = new sn_auth.GlideOAuthClientRequest();
    tokenRequest.setGrantType("refresh_token");
    tokenRequest.setRefreshToken(token.getRefreshToken());
    tokenRequest.setParameter('oauth_requestor_context','sys_rest_message');
    tokenRequest.setParameter('oauth_requestor', requestorId);
    tokenRequest.setParameter('oauth_provider_profile',oauthProfileId);

    var oAuthClient = new  sn_auth.GlideOAuthClient();
    var tokenResponse = oAuthClient.requestTokenByRequest(null,tokenRequest);
    var error = tokenResponse.getErrorMessage();
    if (error) gs.warn("Error:" + tokenResponse.getErrorMessage());
}

function isExpired(expiresIn, withinSeconds) {
    if (expiresIn > withinSeconds) return false;
    return true;
}


function getToken(requestorId, oauthProfileId) {
    if (!requestorId || !oauthProfileId) return null;
    var client = new sn_auth.GlideOAuthClient();
    return client.getToken(requestorId, oauthProfileId);
}

function checkAndRefreshAccessToken(grRestMessage) {
    if (grRestMessage.getValue("authentication_type") != "oauth2") return false;
    var accountMsg = grRestMessage.getValue("name");
    if (!accountMsg)
        accountMsg = grRestMessage.getUniqueValue();
    accountMsg = "Account=\"" + accountMsg + "\"";

    var token = getToken(grRestMessage.getUniqueValue(), grRestMessage.getValue('oauth2_profile'));
    var accessToken = token.getAccessToken();

    if (accessToken) {
        if (!isExpired(token.getExpiresIn(), 300)) return;
    }

    if (!token.getRefreshToken()) {
        gs.error("No OAuth refresh token for Rest Message. Manual reauthorization required. " + accountMsg);
        return;
    }

    if (isExpired(token.getRefreshTokenExpiresIn(), 0)) {
        gs.error("OAuth refresh token for Rest Message is expired. Manual reauthorization required. " + accountMsg);
        return;
    }

    gs.info("Refreshing oauth access token for Rest Message account. " + accountMsg);
    refreshAccessToken(grRestMessage.getUniqueValue(), grRestMessage.getValue('oauth2_profile'), token);
}

var grAccount = new GlideRecord("sys_rest_message");
grAccount.addQuery("authentication_type", "oauth2");
grAccount.addNotNullQuery("oauth2_profile");
grAccount.query();

while (grAccount.next()) {
    checkAndRefreshAccessToken(grAccount);
}

Heartbeat messages can be used to help identify if the integration is up or down. Both inbound and outbound heartbeat messages are supported.

The Heartbeat Message

Create a new Message and select type Heartbeat. Although specific configuration is not required, you can configure Heartbeat messages as you would any other message. The only difference is the Heartbeat transactions are bonded to the active connection.

You should only have one active Heartbeat message per integration. Activating an outbound Heartbeat message will create a scheduled job which sends the message according to the frequency set on the Integration.

No response message is required for Heartbeat messages unless you would like to customise how responses are sent and received.

Outbound

When an outbound heartbeat message is sent and fails, the integration will be paused and its Status marked as "Down". This will force all outbound messages to be queued. When a future outbound heartbeat message is successful, the integration will be resumed and its Status marked as "Up".

The frequency of outbound heartbeat messages is controlled by the Heartbeat Frequency setting on the Integration. By default, this is set to 300 seconds (5 minutes), meaning a heartbeat is sent every 5 minutes to the endpoint specified by the connection and message.

A heartbeat is seen to fail when it does not receive a 2xx status code response, e.g. 200. If you need to support other status codes, you can use Response Actions to intercept and modify the request response.

To help identify heartbeat messages, all outbound heartbeat messages contain the header x-snd-eb-heartbeat with a value of 1.

Inbound Heartbeat Messages

You can allow third party systems to send a heartbeat request. A Heartbeat message configured for Inbound processing is required. It can be configured to operate similarly to any other message, although no additional configuration is required.

Inbound heartbeats will run through the full connection process for the integration. By default, a 200 response is returned when authentication and Heartbeat message processing has been successful.

Check for Heartbeat Example

POST https://myinstancename.service-now.com/api/x_snd_eb/unifi/incident

Example to send a Heartbeat message to check if the API is available.

Headers

Update Bonded Record (Originating Instance)

In the originating instance, select one bonded ticket and Add an attachment to the record .

Review Outbound Transport Data

From the bonded record, navigate to the Unifi Integrations related list and click to open the Bond.

From the Bond, navigate to the following related lists:

Navigate to the Bonded Attachments related list and verify that a Bonded Attachment record has been created.

Navigate to the Transactions related list and click to open the AddAttachment Transaction.

From the Transaction, navigate to the HTTP Requests related list and click to open the HTTP Request.

Note the following about the HTTP Request:

View Bonded Record (Receiving Instance)

In the receiving instance, navigate to the corresponding bonded ticket and verify the attachment has been added to the record.

Review Inbound Transport Data

From the bonded record, navigate to the Unifi Integrations related list and click to open the Bond.

From the Bond, navigate to the following related lists:

Navigate to the Bonded Attachments related list and verify that a Bonded Attachment record has been created.

Navigate to the Transactions related list and click to open the AddAttachment Transaction.

From the Transaction, navigate to the HTTP Requests related list and click to open the HTTP Request.

Note the following about the HTTP Request:

Congratulations! You have successfully configured & tested a dedicated Message to stream inbound and outbound attachments.

In Unifi Integration Designer, click on the 'Messages' icon & then New to begin configuring the AddAttachment Message.

New Message Modal

The fields to be configured for the AddAttachment New Message modal are as follows:

Your AddAttachment New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

Your Response form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be configured are as follows:

*These fields are automatically populated.

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger fields to be configured (as required)* are as follows:

*Outbound condition (as required):

It is not always necessary for you to enter a condition. The value given is an example. You may create any condition (or not) to align with your business process requirements. In this case, it makes sense to set the Outbound Condition to false because we do not want Unifi to send this message on any update of the source record. Typically, we would configure different messages to align with state changes (e.g. Close, Resolve).

The code in the 'Outbound condition' script field should look like this:

false

Your Outbound Trigger form should look like this:

Navigate to Outbound > Attachments.

Outbound Attachments Fields

The Outbound Attachments fields to be configured are as follows:

*This field is automatically populated.

Your Outbound Attachments form should look like this:

Navigate to Outbound > Settings.

Outbound Settings Fields

The Outbound Setting fields to be configured are as follows:

The code in the 'Path' field should look like this:

/attachment?file_name=${scratchpad.file_name}&reference=${scratchpad.reference}

Your Outbound Settings form should look like this:

Navigate to Inbound > Settings.

Inbound Settings Fields

The Inbound Settings fields to be configured are as follows:

Your Inbound Settings form should look like this:

Navigate to Advanced > Script Editor.

Script Editor Fields

When you first open Script Editor, it should look like this:

The Script Editor fields to be configured are as follows:

Stage to Request (Outbound)

The code in the ‘Stage to Request’ script field should look like this:

(function processStageToRequest(request, stage, transaction, message, bond, scratchpad) {

  // This information would normally come from the AttachmentSender
  var sender = new x_snd_eb.AttachmentSender(transaction, bond);
  sender.next();

  var file_name = sender.attachment_name;
  var mime_type = sender.attachment_type;
  var attach_id = sender.attachment_id;
  var reference = bond.getValue('external_reference');

  //-----------------------
  // Path construction
  //-----------------------
  scratchpad.file_name = encodeURIComponent(file_name);
  scratchpad.reference = encodeURIComponent(reference);

  // ?file_name=${scratchpad.file_name}&reference=${scratchpad.reference}

  //-----------------------
  // Headers construction
  //-----------------------

  // Compose the scratchpad headers and payload
  scratchpad.headers = {
    "Content-Type": mime_type
  };

  //-----------------------
  // Payload construction
  //-----------------------

  // This is the string that triggers attachment streaming outbound
  payload = 'sys_attachment:' + attach_id;

})(request, stage, transaction, message, bond, scratchpad);

Payload to Stage (Inbound)

The code in the ‘Payload to Stage’ script field should look like this:

(function processPayloadToStage(payload, stage, transaction, message) {

  // set either internal/external reference on stage depending on what is needed.
  // make sure to configure the Bond reference lookup on the Message to be Internal/External
  stage.internal_reference = payload.reference;

})(payload, stage, transaction, message);

Your Script Editor fields should now look like this:

Save the message.

Next, we shall configure the Scripted REST Resource.

Create Application Registry

In native ServiceNow, navigate to System OAuth > Application Registry and click New.

On the interceptor page, click Create an OAuth API endpoint for external clients.

The fields to be configured for the Application Registry record are as follows:

*These values are to be left as-is.

Your Application Registries New Record should look like this:

Submit the record.

Configure Connection

If you haven't already done so, you will need to create an Inbound user in this instance. See here for details.

In Unifi Integration Designer, navigate to Connections and click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

The format of the Endpoint URL is as follows:

https://<your_consumer_instance>.service-now.com/<your_consumer_resource_path>

Your New Connection modal should look like this:

Submit and view to further configure the Connection.

Connection Details

The fields to be configured for the Details form are as follows:

Your Details form should look like this:

Save the Connection.

At this point you can perform a basic Connection test. For instructions, see here.

Next, configure the Identity Consumer Instance.

Create Application Registry

In native ServiceNow, navigate to System OAuth > Application Registry and click New.

On the interceptor page, click Connect to a third party OAuth Provider.

The fields to be configured for the Application Registry record are as follows:

*This value is to be left as-is.

Your Application Registries New Record should look like this:

Right-click and Save to remain on the record.

Configure Connection

In Unifi Integration Designer, navigate to Connections and click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

The format of the Endpoint URL is as follows:

https://<your_provider_instance>.service-now.com/<your_provider_process_api>

Your New Connection modal should look like this:

Submit and view to further configure the Connection.

Connection Details

The fields to be configured for the Details form are as follows:

Your Details form should look like this:

Save the Connection.

Get OAuth Token

Once you have saved the Connection, the 'Get OAuth Token' button is available.

Click Get OAuth Token.

On the modal that pops up, enter the Username & Password (for the Inbound user of the Identity Provider Instance).

Click Get OAuth Token.

The 'OAuth token flow completed successfully' info message is displayed. Close the modal.