Welcome

We will be configuring a Poller and Poll Processor in order to pull Incident data which has been updated from an external instance and pass it to Unifi. We will then configure the relevant inbound Message in order to process that data.

If you have been following along with the Outbound Incident Guide you will know that it is given as an example of how you might configure such an integration. It is not meant to be prescriptive. The same applies here.

Having said that, this Guide has been written to follow on from that previous one and has been structured accordingly.

Scope

This document will guide you through an example of how you might configure a poller integration - polling the table API of your Personal Developer Instance (PDI).

The Outbound Incident Guide demonstrates how to configure outbound messages to the table API of your PDI. This Guide will demonstrate how you might poll data from the table API of your PDI and then configure inbound messages to process that data.

Definitions

It is not always possible for a remote system to send us the data. In such cases, we can make a scheduled request for it using Pollers. We can setup, execute and process those Requests using Poll Processors.

Poller

A poller defines the frequency of polling and which logic to use. It is effectively a scheduled job which ties together an Integration and Poll Processor. Although a Poller belongs to only one Integration, an Integration can have multiple Pollers.

Poll Processor

A Poll Processor contains the logic that will be applied when polling a remote system for data. It contains three main scripts:

Setup Script

The Setup Script is used to build the environment for the poll and define what it will do (for example, create/setup the URL that will be called).

Request Script

The Request Script is used to reach into the remote system and execute the request. This is usually done by making a REST call to the URL defined in the Setup Script.

Response Script

The Response Script is used to process the information returned from the remote system.

Warning

Approach

We will need to store and check some returned data in order to evaluate when the data was changed and which system has made the updates to the data (we don’t want to pull back data we have changed).

We will begin by polling for updates only and processing those requests using an update message in Unifi.

This Guide has shown us how we might configure a poller integration - polling data from the table API of a Personal Developer Instance (PDI) and then configure an inbound message to process that data. As such, we created the following records:

• Poll Processor

• Poller

• Inbound Message

• Fields

We also made further configuration changes to both the remote instance (PDI) and internal instance, in order to facilitate the following:

• Message Identification

• Bond Identification

In testing our integration, we created some incidents in the remote instance which were bonded. We then updated the bonded records from both instances (polling for updates each time). We successfully proved that we were only querying bonded records, pulling back updates made in the remote instance since the last update time, only retrieving a select number of fields and that the returned requests were looped through, generating transactions for each updated ticket.

By Using the Unifi integration platform, we have discovered that building and testing our integration is simpler and more efficient, saving both time and money. Our hope is that this Guide has been a valuable aid to you in that process.

For further information please see our technical documentation.

If you have any feedback or questions, please contact us via our website contact form.

A Poller is a configuration record which defines the frequency of polling and which logic to use (the logic itself is defined in the Poll Processor). Each time it is run, it creates a corresponding Poll Request record.

New Poller

Click the 'Pollers' icon & then New.

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

*These fields are mandatory, or automatically defaulted to true.

Your New Poller modal should look like this:

Submit and view to further configure the Poller.

Details

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

Your Details form should look like this:

Navigate to Scheduling.

Scheduling

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

*This field is mandatory.

Your Scheduling form should look like this:

Save the Poller.

In order to process the inbound Requests, we next need to configure our Inbound Message.

In order to process the data that is returned from the remote system, we will need to create the appropriate messages in Unifi. To satisfy the requirements of this Guide, we will only need to configure the one message:

• UpdateIncidentInbound

We shall look in detail at how to configure that message and the appropriate message scripts over the next couple of pages.

Let's begin by configuring the UpdateIncidentInbound Message.

To set up a scheduled poll that will query the remote system at regular intervals, check whether any data has changed and then pass that data to Unifi, we will need to configure the following records:

• Poll Processor

• Poller

Once those records are configured, we will need to configure an inbound message to process the returned data. We will also need to make some changes to our outbound messages before we can test our update scenario (in order to prove the poll is returning the expected data and the target record is updated accordingly). We will look at the polling records in turn over the next couple of pages.

We're now ready to configure the Poll Processor.

The Poll Processor is a configuration record which contains the logic that will be applied when polling a remote system for data. There are three main scripts which are used to setup, execute and process the Poll Requests. The scripts given here are examples of how you might configure your Poll. The details of yours may differ depending on your requirements.

Icons

The icons are:

a) 'Integration' icon: Opens the current integration's Details page.

b) 'Messages' icon: Opens the current integration's Messages page.

c) 'Fields' icon: Opens the current integration's Fields page.

d) 'Field Maps' icon: Opens the current integration's Field Maps page.

e) 'Pollers' icon: Opens the current integration's Pollers page.

f) 'Poll Processors' icon: Opens the current integration's Poll Processors page.

New Poll Processor

In Unifi Integration Designer, navigate to & open < Your Integration > (created following the Outbound Incident Guide).

Click the 'Poll Processors' icon & then New.

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

Your New Poll Processor modal should look like this:

Submit and view to further configure the Poll Processor.

Setup Script

The Setup Script is the first script to run (it runs at the point in time the Poll Request is created). It is used to build the environment for the poll and define what it will do. We will use it to setup the URL that will be called.

Navigate to Scripts > Setup Script.

The Setup script field is to be configured as follows:

The code in the Setup script field should look like this:

// Configure the new Poll Request record
(function(poll_request, poller, params) {

    var gdt = new GlideDateTime();
    gdt.addSeconds(-1800);

    var connection = poller.getIntegration().getActiveConnection();
    var user = connection.getBasicAuthUser();
    var time = connection.getData('last_update_time', (gdt + ''));

    var fields = 'sys_id,number,correlation_id,short_description,description,sys_updated_on,sys_updated_by';

    var query = [
        'correlation_idISNOTEMPTY',
        'sys_updated_by!=' + user,
        'sys_updated_on>' + time
    ];

    var uri_query = query.map(function(c) {
        return encodeURIComponent(c);
    }).join('%5E');

    poll_request.endpoint_url += '/table/incident?sysparm_query=' + uri_query +
        '&sysparm_fields=' + encodeURIComponent(fields) + '&sysparm_limit=10';

})(poll_request, poller, params);

Your Setup Script form should look like this:

Navigate to Request Script.

Request Script

The Request Script is used to reach into the remote system and execute the request. We will use the ServiceNow RESTMessageV2() web service to make a REST call to the URL defined in the Setup Script.

The Request script field is to be configured as follows:

The code in the Request script field should look like this:

// Process the request e.g. by executing a web service and returning the response
(function(poll_request, poller, connection, params) {

    var rm = new sn_ws.RESTMessageV2();
    rm.setEndpoint(poll_request.endpoint_url);
    rm.setHttpMethod('GET');
    rm.setRequestHeader('Accept', 'application/json');
    rm.setRequestHeader('Content-type', 'application/json');
    rm.setBasicAuth(connection.getBasicAuthUser(), connection.getBasicAuthPassword());

    // rm.setRequestBody(JSON.stringify(body));
    var resp = rm.execute();

    answer = resp.getBody() + '';

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

Your Request Script form should look like this:

Navigate to Response Script.

Response Script

The Response Script is used to process the information returned from the remote system. We will pass this data to Unifi to process.

The Response script field is to be configured as follows:

The code in the Response script field should look like this:

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

    var body = JSON.parse(response);

    // Process the result
    var conn = poller.getIntegration().getActiveConnection();
    var cvars = conn.getVariables();

    var poll_helper = new x_snd_eb.PollHelper(poll_request);
    var info = [];

    if ( body.result.length == 0 ) {
        status = 'No Incident found';
        poll_request.response_status = status + '\n\n' + JSON.stringify(body,null,2);
        return;
    }

    body.result.forEach(function(inc){

        // Set up the payload object
        var pl = {
            message : {
                name: 'UpdateIncidentInbound',
                source_reference: inc.sys_id
            },
            detail : {
                short_description : inc.short_description,
                description : inc.description
            }
        };

        // Set up the options object for message submission
        var opts = {
            //message_name: 'UpdateIncidentInbound',
            payload : JSON.stringify(pl)
        };

        poll_helper.processInbound(opts);

        var inc_time = inc.sys_updated_on;
        info.push('Incident : ' + inc.number + ' (' + inc_time + ')');

        // Set last update time (if later)
        var conn_time = conn.getData('last_update_time');
        if ( inc_time > conn_time ) {
            conn.setData('last_update_time',inc_time);
        }

    });

    poll_request.response_status = info.join('\n') + '\n\n' + JSON.stringify(body,null,2);

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

var poll_helper = new x_snd_eb.PollHelper(poll_request);

poll_helper.processInbound(opts);

Your Response Script form should look like this:

Save the Poll Processor.

Now let's move on and configure the Poller.

Correlation ID

In order for the remote system to store data about which record they're bonded with and to enable us to identify and only return data from those bonded records, we need to send and store a unique identifier. We will make use of the available correlation_id field on the Incident record. First we will add the field to the Incident form in our PDI.

Incident Form

From any Incident record in your PDI, right-click & navigate to Configure > Form Layout.

Select the Correlation Id field from the 'Available' slushbucket and move it to the 'Selected' slushbucket.

Save to add the field to your form.

Next, we will need to Edit the CreateIncident Message.

New Message Modal

Click the 'Messages' icon, then New.

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

Your UpdateIncidentInbound New Message modal should look like this:

Click Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

*This field is automatically defaulted to true.

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 Inbound > Settings.

Inbound Settings Fields

The Inbound Settings fields to be configured are as follows:

Your Inbound Settings form should look like this:

Click Save.

We are now ready to configure the Fields for our UpdateIncidentInbound Message.

When we configured our Outbound Incident Integration we weren't concerned with identifying inbound messages, because there weren't any (we were only sending outbound).

Now that we're polling our PDI for data as well as sending data, we need to be aware of the above concern.

To facilitate this we need to make a change to our Integration.

Message Identification

To enable the Integration to identify which messages to use to process inbound requests:

Navigate to the 'Integration' icon to open < Your Integration >, then navigate to Integration > Message Identification.

Update the code in the 'Identify message script' field so that it looks like this:

function identify(payload) {

  return (payload.message.name || '') + '';

}

The Message Identification form should look like this:

Save the record.

In order for both systems to identify and understand which records are bonded, we need to make a few more changes which we shall group together under the heading of Bond Identification.

CreateIncident Message

To ensure that our CreateIncident Message is sending the relevant data we need to configure a new Field record that will send the Incident number as the correlation id. We will make use of the previously copied String Field Map record.

Field: incident.number

In Unifi Integration Designer, from the CreateIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our incident.number New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.number' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.description

The ‘incident.description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we created the Message level record when configuring the Fields for the UpdateIncidentInbound Message. We will now create its Message level counterpart for the CreateIncident Message.

From the CreateIncident Message, navigate to Message > Fields.

Your CreateIncident Fields page should look like this:

Find the incident.description (Integration level) Field & set Active to true.

By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.

Click to open the incident.description (Message level) Field to make a few minor changes.

The incident.description Field record opens to the Details page.

To edit, set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.description Field record as follows:

Your 'incident.description' Field record should look like this:

Save the record.

Build

Now that we’ve configured the Field records for the CreateIncident message, we are ready to build our message scripts.

To quickly navigate to the CreateIncident Message from the Details page of the newly created incident.description Field record...

...click the 'Preview' icon to the left of the Message field.

The following Field records should now be in place for your CreateIncident Message:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor > View > Outbound to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

Source to Stage:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.number = '' + (source.number || default_value);
  } else if (source.number != '') {
    $stage.number = '' + source.number;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.caller_id = '' + (source.caller_id || default_value);
  } else if (source.caller_id != '') {
    $stage.caller_id = '' + source.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.short_description = '' + (source.short_description || default_value);
  } else if (source.short_description != '') {
    $stage.short_description = '' + source.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.description = '' + (source.description || default_value);
  } else if (source.description != '') {
    $stage.description = '' + source.description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var field_choice;
  var is_mandatory = false;  
  
  if (!source.state.nil()) {
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',         '=', 'incident');
    field_choice.addQuery('element',       '=', 'state');
    field_choice.addQuery('integration',   '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message', '=', '');
    field_choice.addQuery('direction',     '=', 'Outbound');
    field_choice.addQuery('value',         '=', source.state);
    field_choice.addQuery('active',        '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      $stage.state = '' + field_choice.external_value;
    }
  } 
  
  if (!$stage.state) {
    $stage.state = '' + (source.state || '');
  }
  
  if (is_mandatory) {
    $stage.state = '' + (source.state || '');
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Stage to Request:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.correlation_id = '' + $stage.number;
  } else if ($stage.number) {
    $payload.correlation_id = '' + $stage.number;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.caller_id = '' + $stage.caller_id;
  } else if ($stage.caller_id) {
    $payload.caller_id = '' + $stage.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.short_description = '' + $stage.short_description;
  } else if ($stage.short_description) {
    $payload.short_description = '' + $stage.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.description = '' + $stage.description;
  } else if ($stage.description) {
    $payload.description = '' + $stage.description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  var $payload = payload;
  
  var is_mandatory = false;  
  
  if (is_mandatory) {
    $payload.state = $stage.state;
  } else if ($stage.state) {
    $payload.state = $stage.state;
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

We have now completed the configuration and are ready to move on to Test our Update Scenario.

Our previously configured Outbound Incident Integration was very simple example and we weren't concerned with identifying which system made the updates. Neither were we concerned with telling the remote system which record they were bonded with.

Now that we're polling our PDI for data as well as sending data, we need to be aware of both the above concerns.

The first concern (identifying which system made the updates) has been taken care of in the Poll Processor Setup script (only returning data not updated by the Basic Authentication User). However, it doesn't make sense to try and return that data from all the records in the remote system. We should only be concerned with those records we're bonded with. To facilitate this we need to make a few configuration changes. We need to make a change in the remote system (our PDI) and some changes to our existing outbound CreateIncident Message.

First, we will need to Edit the Incident Form in our PDI.

Copy Field Maps

Some Field Maps should already have been copied for this Integration whilst following the Outbound Incident Guide. Those that aren't will need to be copied. The Field Maps we shall use for our UpdateIncidentInbound Field records are:

• Message Header

• String

To copy the Message Header Field Map, navigate to the 'Field Maps' icon.

Click on the ellipsis to the right of the Message Header Field Map & then click Copy.

Copy Field Map Modal

The fields to edit for the Copy Field Map modal are as follows:

Your Copy Field Map modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created Field Map.

If necessary, repeat the process for the String Field Map.

Field records can represent the handling of two categories of data: either a data object which carries transaction specific data (e.g. name, time stamp, source id etc.), or a field element on the bonded record (e.g. Short description). We will begin by configuring a Field record to deal with the transaction specific data.

Field: message.header

Back in the UpdateIncidentInbound Message, navigate to Message > Fields. Click New.

The fields to be configured for our message_header New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'message.header' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the UpdateIncidentInbound Message.

Fields & Field Maps

Depending on your requirements, you will need to create Field records for each of the relevant Incident record field elements you wish to map. As we have only chosen to include the short_description & description elements in both the Setup script & Response script of the Poll Processor, this Guide will focus on those two. If you wish, however, you are free to configure other Field records as required (ensuring you also define them in both the Setup Script & Response script of the Poll Processor).

For a full description of the available Field Maps, please see the relevant page in our technical documentation.

The table below lists the Incident record field elements we will map and the relevant Field Maps required to configure each Field record.

*Field map: Values may vary (dependent on your configuration of the copies). Choose the copy Field Maps you created earlier.

Field: incident.short_description

From the UpdateIncidentInbound Message, navigate to Message > Fields.

Your UpdateIncidentInbound Fields page should look like this:

Find the incident.short_description (Integration level) Field & set Active to true.

By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.

Click to open the incident.short_description (Message level) Field to make a few minor changes.

The incident.short_description Field record opens to the Details page.

The following info message is also displayed (which can be closed):

Set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.short_description Field record as follows:

Your incident.short_description Field record should look like this:

Save the record.

Field: incident.description

To quickly navigate to the UpdateincidentInbound Message from the Details page of the incident.short_description Field record...

...click the 'Preview' icon to the left of the Message field.

From the UpdateIncidentInbound Message, navigate to Message > Fields.

Click the ellipsis next to the incident.short_desscription Field record & click Copy.

The fields to edit for the Copy Field modal are as follows:

*This field is automatically populated.

Your 'incident.description' Copy Field modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created incident.description Field record.

Build

Now that we’ve configured the Field records for the UpdateIncidentInbound message, we are ready to build our message scripts.

To quickly navigate to the UpdateIncidentInbound message from the Details page of the newly created incident.description Field record…

...click the 'Preview' icon to the left of the Message field.

The following Field records should now be in place for your UpdateIncidentInbound messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor.

Your Script Editor fields should initially look like this:

Navigate to View > Inbound to view the auto-generated code.

Your Script Editor fields should now look like this:

Message Scripts

The Message Scripts reflect the mappings as per this Guide. Your scripts might differ depending on which Fields you chose to map (& defined in the payload). We will look at the Message Scripts in turn.

Payload to Stage:

Your Payload to Stage Message Script should look like this:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping message.header [x_snd_eb_field.do?sys_id=ca3a65dc1ba57c1090dfdb9ebd4bcb90]", function () {
  log.debug("Field map: PI - Message Header [x_snd_eb_field_map.do?sys_id=a225651c1ba57c1090dfdb9ebd4bcbeb]");
  payload = payload || {};
  payload.message = payload.message || {};
  var $payload = payload.message;
  
  // Messge identifiers
  $stage.$message_name = $payload.name;
  $stage.$time_stamp   = $payload.time_stamp;
  
  // Task references
  stage.internal_reference = $payload.target_reference || '';
  stage.external_reference = $payload.source_reference || '';
  
  // Transaction identifiers
  transaction.external_message_id = $payload.source_id || '';
  
  

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=168aa99c1ba57c1090dfdb9ebd4bcbee]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory && $payload.short_description == undefined) {
    throw 'Mandatory field short_description was not provided';
  } else {
    $stage.short_description = $payload.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=6178b5181be57c1090dfdb9ebd4bcbb1]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory && $payload.description == undefined) {
    throw 'Mandatory field description was not provided';
  } else {
    $stage.description = $payload.description;
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Stage to Target:

Your Stage to Target Message Script should look like this:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=168aa99c1ba57c1090dfdb9ebd4bcbee]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory && $stage.short_description == '') {
    throw 'Mandatory field short_description was not provided';
  } else {
    target.short_description = '' + ($stage.short_description || default_value);
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=6178b5181be57c1090dfdb9ebd4bcbb1]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory && $stage.description == '') {
    throw 'Mandatory field description was not provided';
  } else {
    target.description = '' + ($stage.description || default_value);
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Before we test, we need to make a few changes. The first is to our Integration - to allow for inbound Message Identification.

To turn off the Poller, in the Unifi Integration Designer window, navigate to the 'Pollers' icon & set Active to false.

In order to test our integration we will need some bonded tickets in the remote instance. If there aren't any already in place, then they'll need to be created.

Create Test Incidents

In the native ServiceNow window, navigate to Incident > Create New.

The Incident fields to configure are as follows:

Your Incident form should look like this:

Note the Info Message confirming the CreateIncident Message is being sent to your Integration.

Note the Bond is 'Open' and both the Internal & External reference are in place.

Update from Originating Instance

Update one of the bonded tickets in the originating instance to cause the UpdateIncident Message to fire:

View the Transactions that have been sent. This can be done either in Native ServiceNow, or in Unifi Operations Manager.

Confirm the Transaction has updated the bonded ticket in the remote instance:

Poll for Updates

In Unifi Integration Designer, click on the 'Pollers' icon. Navigate to & open < Your Poller > (created earlier). & click Execute Now:

In native ServiceNow, navigate to Unifi > Polling > Poll Requests. Click to Open & view the generated Poll Request. Confirm that no Incident was found (this is exactly as we expect because we are only polling for updates made by the remote instance):

Update from Remote Instance

In the remote instance, update two of the bonded tickets in turn_._

Poll for Updates

Back in the originating instance, navigate to & open < Your Poller >. Click Execute Now.

Open the corresponding Poll Request & confirm that both Incidents were found (and only those):

View the Transactions that have been sent. This can be done either in Native ServiceNow, or in Unifi Operations Manager.

Confirm the Transactions have updated the bonded tickets in the originating instance.

Challenge

For completeness, to prove we are only querying and pulling back data from bonded records, update an incident in the remote system which isn't bonded (Correlation ID is empty) & run the Poller again.

What do you expect to happen?