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 inbound Messages to process the returned data. We will look at the polling records in turn over the next couple of pages.

We're now ready to configure the Poll Processor.

In order to process the data that is returned from the remote system, we will need to create the appropriate Messages in Unifi. The following Messages will be required:

• UpdateIncidentInbound

• ResolveIncidentInbound

To satisfy the requirements of this Guide (and because we have already configured one of those Messages in the previous Incident Update Poller Guide, we will only need to configure the one message i.e. ResolveIncidentInbound.

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 ResolveIncidentInbound Message.

Welcome

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

If you have been following along with the Outbound Incident Guide and the previous Poller Guide you will know that they are given as examples of how you might configure such integrations. They are not meant to be prescriptive. The same applies here.

Having said that, this Guide has been written to follow on from those previous ones 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 Incident Update Poller Guide demonstrated how you might poll for updates from the table API of your PDI and then configure an inbound Message to process that data. This Guide will also demonstrate how you might poll for updates from the table API of your PDI, but will also require that we store local data in order to decide which Message to use and then configure multiple 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

As well as storing and checking some returned data in order to evaluate when the data was changed and which system has made the updates (we don’t want to pull back data we have changed), we will also need to store and check other data in order to decide which Message to use to process that data.

We will begin by polling for updates and then process those requests using multiple Messages in Unifi.

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.

Edit Update Poller

Click to open the previously configured Incident Update Poller.

The fields to be edited for our Poller record are as follows:

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

Your Multiple Message Poller should look like this:

Save the Poller.

In order to process the inbound Requests, we need to configure the Inbound Messages.

Click on the 'Messages' icon to open the Messages page.

Click the ellipsis to the right of the UpdateIncidentInbound Message & then click Copy.

Copy Message Modal

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

Your Copy Message modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created ResolveIncidentInbound Message.

Details Fields

The Details fields to be edited are as follows:

Your Details form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be edited are as follows:

Your Bond form should look like this:

Click Save.

We are now ready to configure the Fields for the ResolveIncidentInbound Message.

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 & Incident Update Poller 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 initial Poll Processor fields to be configured are as follows:

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

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 next Poll Processor field to be configured is as follows:

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

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, telling it which Message to use to process the data.

The last Poll Processor field to be configured is as follows:

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

Your Response Script form should look like this:

Save the Poll Processor.

Now let's move on and configure the Poller.

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 multiple inbound messages to process that data (deciding which Message to use in the process). As such, we created the following records:

• Poll Processor

• Poller

• Inbound Message

• Fields

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.

We also proved that we were able to store previously returned records in order to facilitate comparison & to enable the decision as to which Message to use to process the data - successfully telling Unifi which Message to use.

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.

It may help to esure the Poller we created is turned off (Active set to 'false') whilst conducting these tests and to manually execute it as required (this can still be done even if the Poller is inactive). This is so that we don't have to wait for the Poller to run, but rather manually activate it when needed by clicking 'Execute Now'.

To turn off the Poller, in the Unifi Integration Designer window, navigate to the 'Pollers' icon & set Active to false. (If you've created this Multiple Message Poller by editing the previously configured Update Poller, it may already be inactive.)

Our Poll Processor has been configured to poll for updates from our PDI and make a decision, telling Unifi which Message to use to process that data. We will therefore test our poller by means of testing both of the inbound Messages on our Integration:

• UpdateIncidentInbound

• ResolveIncidentInbound

We will look in more detail at the steps for each over the next couple of pages.

First, we shall test the UpdateIncidentInbound Message.

Resolve Test Incident

In the remote instance (your PDI), navigate to < Your Incident > created in the earlier test.

Update the Incident record as follows:

Your Incident record should look like this:

Right-click & Save.

Poll for Updates

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

Open the corresponding Poll Request & confirm that the Incident was found (and the Message name was ResolveIncidentInbound):

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 originating instance:

Navigate to the Notes tab to view the Activities stream:

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

The 'message.header', 'incident.description' and 'incident.short_description' Field records are already be in place because they were also copied when we copied the Message. We will now configure Field records for the remaining field elements we have chosen to map.

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 chosen to include the state, close_notes & close_code elements in both the Setup script & Response script of the Poll Processor, this Guide will focus on those three only. 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.state (Message level)

From the ResolveIncidentInbound Message, navigate to Message > Fields.

Your ResolveIncident Message Fields page should look like this:

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

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

Click to open the newly created incident.state (Message level) Field record for further editing.

The incident.state 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.

The fields to be changed to configure the incident.state (Message level) Field record are as follows:

Your incident.state (Message level) Settings form should look like this:

Save the record.

Field: incident.close_notes

To quickly navigate to the ResolveIncidentInbound Message from the Details page of the incident.state Field record...

...click the ‘Preview’ icon to the left of the Message field.

From the ResolveIncidentInbound Message, navigate to Message > Fields.

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

Click to open the newly created incident.close_notes (Message level) Field record for further editing.

The incident.close_notes 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.

The fields to be changed to configure the incident.close_notes (Message level) Field record are as follows:

*Mandatory should already be set to true.

Your 'incident.close_notes' (Message level) Settings form should look like this:

Save the record.

Field: incident.close_code

From the ResolveIncidentInbound Message, navigate to Message > Fields.

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

Click to open the newly created incident.close_code (Message level) Field record for further editing.

The incident.close_code 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.

The fields to be changed to configure the incident.close_code (Integration level) Field record are as follows:

*Mandatory should already be set to true.

Your ‘incident.close_code’ (Message level) Field record should look like this:

Save the record.

Build

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

From the ResolveIncidentInbound message., navigate to Message > Fields.

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

Click on Build Message.

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

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

Your Script Editor fields should 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=0f7216b21be9f05090dfdb9ebd4bcb22]", 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=077216b21be9f05090dfdb9ebd4bcb1c]", 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=0f7216b21be9f05090dfdb9ebd4bcb20]", 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;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=daba16b21be9f05090dfdb9ebd4bcb4e]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  var is_mandatory = false;  
  
  if (is_mandatory && $payload.state == undefined) {
    throw 'Mandatory field state was not provided';
  } else {
    $stage.state = $payload.state;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_code [x_snd_eb_field.do?sys_id=bdfa22be1be9f05090dfdb9ebd4bcb9b]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  var is_mandatory = true;  
  
  if (is_mandatory && $payload.close_code == undefined) {
    throw 'Mandatory field close_code was not provided';
  } else {
    $stage.close_code = $payload.close_code;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_notes [x_snd_eb_field.do?sys_id=c9532af61be9f05090dfdb9ebd4bcbb4]", 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 = true;
  
  if (is_mandatory && $payload.close_notes == undefined) {
    throw 'Mandatory field close_notes was not provided';
  } else {
    $stage.close_notes = $payload.close_notes;
  }

});

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=077216b21be9f05090dfdb9ebd4bcb1c]", 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=0f7216b21be9f05090dfdb9ebd4bcb20]", 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);
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=daba16b21be9f05090dfdb9ebd4bcb4e]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var is_mandatory = false;  
  
  if (is_mandatory && $stage.state == undefined) {
    throw 'Mandatory field state was not provided';
  } else {
    var field_choice;
    
    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',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.state);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.state = field_choice.value;
    } else {
      target.state = $stage.state;
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_code [x_snd_eb_field.do?sys_id=bdfa22be1be9f05090dfdb9ebd4bcb9b]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var is_mandatory = true;  
  
  if (is_mandatory && $stage.close_code == undefined) {
    throw 'Mandatory field close_code was not provided';
  } else {
    var field_choice;
    
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',          '=', 'incident');
    field_choice.addQuery('element',        '=', 'close_code');
    field_choice.addQuery('integration',    '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message',  '=', '');
    field_choice.addQuery('direction',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.close_code);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.close_code = field_choice.value;
    } else {
      target.close_code = $stage.close_code;
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_notes [x_snd_eb_field.do?sys_id=c9532af61be9f05090dfdb9ebd4bcbb4]", 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 = true;
  
  if (is_mandatory && $stage.close_notes == '') {
    throw 'Mandatory field close_notes was not provided';
  } else {
    target.close_notes = '' + ($stage.close_notes || default_value);
  }

});

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

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

Because we have already made a few changes to allow for inbound Message & Bond Identification in our earlier 'Incident Update Poller' Guide, we can now move on to Testing.

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 native ServiceNow, 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) and that the Message name was UpdateIncidentInbound:

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?

Next, we shall test the ResolveIncidentInbound Message.