Welcome

We will be configuring two Pollers and two Poll Processors in order to pull data which has been updated from an external instance, pass the relevant data between them and then pass it to Unifi. We will then use the relevant inbound Messages in order to process that data.

If you have been following along with the Outbound Incident Guide and each of the previous Poller Guides 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 parent and child poller integration - polling the table API of your Personal Developer Instance (PDI).

Both the Incident Update Poller Guide and the Incident Multiple Message Poller Guide demonstrated how you might poll for updates from the table API of your PDI and then configure inbound Messages to process that data. This Guide will also demonstrate how you might poll for updates from the table API of your PDI, but will poll in two stages - an initial light poll, periodically scanning for updated records and a subsequent, on-demand poll, pulling back more detail from the relevant records and deciding how to process that data with the relevant inbound Messages.

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.

The first (parent) Poll Processor will pull back a list of the relevant records (polling enough data to identify the records). Each record it identifies will be passed on to a second (child) Poll Processor which will then make a fuller Poll Request against that record and process it deciding between multiple Messages in Unifi.

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

• Poll Processor

• Poller

We will look at the polling records in turn over subsequent pages. Before configuring those records, let’s first look at Connection Variables.

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 our Poller record 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:

Save the Poller.

Update Connection Variable

Update the value of the 'incident_poller' Connection Variable with the sys_id of the child Poller.

Click on the Hamburger Menu and select Open in platform.

The Poller opens in a new window.

Right-click the Header & 'Copy sys_id'.

Open the variable created on the 'Connection Variables' page of this Guide and update the value with the copied sys_id.

Next, we will configure the Parent Poll Processor.

Instead of scripting data values directly into the code of your Poll Processor scripts, it may be better practice to use Connection Variables in their place. Not only does it make those scripts cleaner, but it also means that changes in requirements can be more easily enacted by changing the values of the data in those variables, without having to change the code in the scripts.

Icons

The icons are:

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

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

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

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

Variable: list_fields

This variable will contain the minimum set of fields required to identify and select records in the remote system.

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

Click the 'Connections' icon, then navigate to and open < Your Connection >.

From the Connection, navigate to Connection > Variables & click New.

The 'list_fields' New Connection Variable fields to be configured are as follows:

Your 'list_fields' New Connection Variable modal should look like this:

Click Submit.

You will be redirected back to the Variables page of the Connection record.

Variable: child_fields

This variable will contain all the fields which will be retrieved from the remote system by the child Poller.

Click New.

The 'child_fields' New Connection Variable fields to be configured are as follows:

Your 'child_fields' New Connection Variable modal should look like this:

Click Submit.

You will be redirected back to the Variables page of the Connection record.

Variable: incident_poller

This variable will contain the sys_id of the child Poller which we will create on the 'Child Poller' page of this Guide. Once you have created the Poller, copy the sys_id and paste it as the value in this variable.

The 'incident_poller' New Connection Variable fields to be configured are as follows:

Your 'incident_poller' New Connection Variable modal should look like this:

Click Submit.

The following Connection Variables should now be in place for your Connection:

Now let's move on and configure the Child 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.

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 initial Poll Processor fields to be configured are 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 cvars = connection.getVariables();

    // We only need to retrieve a minimal set of fields
    var fields = cvars.list_fields;

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

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

    // Nothing to do if no results were returned
    if ( body.result.length == 0 ) {
        poll_request.response_status = 'No Incidents returned\n\n' + JSON.stringify(body,null,2);
        return;
    }

    // Sample result
/*
{
  "result": [
    {
      "sys_id": "0ecc4865db734010c3ebde82ca961960",
      "number": "INC0010107",
      "correlation_id": "INC0010345",
    },
    {
      ... next Incident
    }
  ]
}   
*/

    // Establish the environment
    var integration = poller.getIntegration();
    var conn  = integration.getActiveConnection();
    var cvars = conn.getVariables();

    var info = [];

    // Process each result
    body.result.forEach(function(inc){

        // Set up a Poll to retrieve an Incident (returns PollRequest object)
        var pr = x_snd_eb.Poller.execute( cvars.incident_poller, {
            incident_id : inc.sys_id
        });

        info.push('Incident: ' + inc.number + ' - PollRequest: ' + pr.getValue('number'));

    });

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

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

Your Response Script form should look like this:

Save the Poll Processor.

Update Child Poll Processor

Navigate to and open < Your Child Poll Processor > (created on the 'Child Poll Processor' page) and update the value of the Parent field by selecting the parent Poll Processor created above.

Now let's move on and configure the Parent Poller.

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.

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 initial Poll Processor fields to be configured are 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 connection = poller.getIntegration().getActiveConnection();
    var cvars = connection.getVariables();

    // The list of fields to retrieve
    var fields = cvars.child_fields;

    // Target a specific incident whose sys_id has been passed in the params object
    poll_request.endpoint_url += '/table/incident/' + params.incident_id +
        '?sysparm_fields=' + encodeURIComponent(fields);

})(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 next Poll Processor field to be configured is 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, 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:

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

    // Nothing to do if no results were returned
    if ( body.result.length == 0 ) {
        poll_request.response_status = 'No Incidents returned\n\n' + JSON.stringify(body,null,2);
        return;
    }

    // Sample result (single Incident)
/*
{
  "result": {
    "sys_id": "0ecc4865db734010c3ebde82ca961960",
    "number": "INC0010107",
    "correlation_id": "INC0010345",
    "short_description": "Demo two - Fixing request",
    "description": "A long description",
    "state":"2",
    "sys_updated_on": "2020-04-02 14:00:00",
    "sys_updated_by": "a.user"
  }
}    
*/

    // Establish the environment
    var integration = poller.getIntegration();
    var config = integration.getConfig();
    var conn   = integration.getActiveConnection();
    var cvars  = conn.getVariables();

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

    // Use Unifi code to find the Bond for an Incident
    function get_bond(inc) {
        var bond = new x_snd_eb.Bond(config);
        bond.locateReference(integration,inc.correlation_id,inc.sys_id);
        if ( !bond.isValidRecord() ) { return null; }
        return bond; 
    }

    // Work out the message type to send to Unifi based upon the change of state
    function get_message_name(curr,prev) {

        // Default message type is an update
        var message_name = 'UpdateIncidentInbound';

        // Use the default type if we have no previous state
        if ( !prev || !prev.state ) { 
            return message_name; 
        }

        // Use the default type if there is no change in state
        if ( curr.state == prev.state ) { 
            return message_name; 
        }

        // We know the state has changed, check if it is Resolved (6)
        if ( curr.state == '6' ) {
            message_name = 'ResolveIncidentInbound';
        }

        return message_name;
    }

    function process_incident(inc) {

        // Log the incident number and time
        var inc_time = inc.sys_updated_on;
        info.push('Incident : ' + inc.number + ' (' + inc_time + ')');

        // Find the bond on which the previous data is stored
        var bond = get_bond(inc);

        // If no bond was found, ignore this incident
        if ( !bond ) {
            info.push('- Bond not found - Incident ignored');
            return;
        }

        // Get the data stored for the incident by a previous poll
        var previous_inc = bond.getDataObject('previous_inc',{ state : '2' });

        // Work out the message type to send into Unifi 
        var message_name = get_message_name(inc,previous_inc);
        info.push('- Message name: ' + message_name);

        // Set up the payload object for passing into Unifi
        var payload = {
            message : {
                name: message_name,
                source_reference: inc.sys_id
            },
            detail : {
                short_description : inc.short_description,
                description : inc.description,
                state : inc.state,
                close_code : inc.close_code,
                close_notes : inc.close_notes
            }
        };

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

        // Save the current incident as the previous incident for the next poll
        bond.setDataObject('previous_inc',inc);

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

    }

    // Process the single result
    process_incident(body.result);

    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({
            payload : JSON.stringify(payload)
        });

Your Response Script form should look like this:

Save the Poll Processor.

Now let's move on and configure the Child Poller.

It may help to turn off the Parent Update Poller we created (set Active 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.

Our Poll Processors have 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 Update type 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.

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 our Poller record 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 will utilise already configured Inbound Messages.

In order to process the data that is returned from the remote system, we will utilise the Messages we created in earlier Guides. The following Messages will be used:

• UpdateIncidentInbound

• ResolveIncidentInbound

Because we have already configured those Messages in the previous Incident Update Poller Guide & Incident Multiple Message Guide, we will not be configuring any of those messages here.

If you haven't already, please review & complete the following sections of the Incident Update Poller Guide:

Please also review & complete the following sections of the Incident Multiple Message Poller Guide:

We can now move on to Testing.

This Guide has shown us how we might configure a parent and child poller integration - polling data from the table API of a Personal Developer Instance (PDI) in two stages - an initial light poll, periodically scanning for updated records and a subsequent, on-demand poll, pulling back more detail from the relevant records and deciding how to process that data with the relevant inbound Messages. As such, we created the following records:

• Child Poll Processor

• Child Poller

• Parent Poll Processor

• Parent Poller

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. For each returned record, more detailed child Poll Requests were triggered, generating transactions for each updated ticket.

We also proved that we were able to store previously returned records in order to facilitate comparison & 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 .

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

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 Parent 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 Parent Poll Request & confirm that both Incidents were found (and only those) and that subsequent child Poll Requests were also triggered:

Notice the Parent & Child Poll Requests:

Open each of the corresponding Child Poll Requests & confirm 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.

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 Child Poll Request & confirm that the Incident was found (and the Message name was ResolveIncidentInbound) & Notice the incident_id passed in as a parameter:

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: