Poll Processor

The Poll Processor contains the logic that will be applied when polling a remote system for data.

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, click the 'Poll Processors' icon & then New.

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

#	Field	Description	Value
1	Name	The name of the Processor.	<Your Name>

Your New Poll Processor modal should look like this:

2) 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:

#	Field	Description	Value
3	Setup script	The script to setup the Poll Request record.	Update the code in the Setup script field so that it looks like the code below

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 cvar = connection.getVariables();

    var user = connection.getBasicAuthUser();
    var time = connection.getData('last_update_time', (gdt + ''));
    var group = cvar.external_group + ''; //Poller Integration Support 
    var fields = cvar.base_fields + ',' + cvar.data_fields;

    var query = [
        'active=true',
        'correlation_idISEMPTY',
        'assignment_group=' + group,
        'sys_updated_by!=' + user,
        'sys_updated_on>' + time,
        'ORDERBYsys_updated_on'
    ];

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

    poll_request.endpoint_url += '?sysparm_query=' + uri_query +
        '&sysparm_fields=' + encodeURIComponent(fields) + '&sysparm_display_value=true' + '&sysparm_limit=10';

})(poll_request, poller, params);

Setup script: The parameters for which data to return are contained in the endpoint url.

fields: The table API will return all the data by default, so we choose to deliberately limit what is returned to the fields listed in this variable. Instead of hardcoding them into the script, we have chosen to substitute Connection Variables containing those values.

query: Instead of querying all the records on the remote instance, we deliberately limit the query to those active records where the correlation id is empty (i.e. it's not bonded), that have been assigned to a specific Assignment group and haven't been updated by the Authentication user (i.e. not created by our system), and that were also updated since either since the last update time (if one exists), or in the last 30 minutes.

Endpoint URL: The value used in the poll_request.endpoint_url was initially generated using the ServiceNow REST API Explorer, substituting variables in for the uri query and fields. This value is appended to the existing endpoint url in the active connection before being added to the Poll Request.

&sysparm_display_value=true: Adding this parameter means that reference data will return an object containing the 'display_value' element instead of the 'value' element. We will talk more about the relevance of this when mapping the caller_id field on the 'CreateIncidentInbound Fields' page.

(We have also chosen to limit the number of records returned to 10.)

params: The params object is passed through to the subsequent scripts (and on to further Pollers, if required).

Your Setup Script form should look like this:

4) 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:

#	Field	Description	Value
5	Request script	The script that executes the request.	Update the code in the Request script field so that it looks like the code below

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

Request script: This script uses the ServiceNow RESTMessageV2() web service to make a REST call to the endpoint url created in the Setup script. It returns the body of the request as the answer which it passes to the Response script

Your Request Script form should look like this:

6) 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:

#	Field	Description	Value
7	Response script	The script that processes the response to the request.	Update the code in the Response script field so that it looks like the code below

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: 'CreateIncidentInbound',
                source_reference: inc.sys_id
            },
            detail: {
                caller_id: inc.caller_id,
                short_description: inc.short_description,
                description: inc.description,
                state: inc.state,
                impact: inc.impact,
                urgency: inc.urgency
            }
        };

        // Set up the options object for message submission
        var opts = {
            //message_name: 'CreateIncidentInbound',
            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', "");
        info.push('Conn Time : ' + conn_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);

Response script: This script parses the response into a body object to contain the result, (returning if it doesn't contain anything). It then sets up some objects to help us (including the essential PollHelper() function which we initialise from the poll_request). After that it loops through each of the returned tickets; for each it sets up a payload object and the options for submitting it to Unifi before calling the processInbound() method. It then checks whether the ticket was updated later than the last update time; if so, it sets and stores the last update time as that 'sys_updated_on' value (this 'last_update_time' is what the Setup script checks against when defining what the Poll will do).

After looping through all the records, the results are logged to the Response status field of the Poll Request.

Essential code: the following lines of code must be included in the Response script to send the data to Unifi

var poll_helper = new x_snd_eb.PollHelper(poll_request);

poll_helper.processInbound(opts);

processInbound(): Having 'poll_helper.processInbound(opts);' inside the loop means that an update message will be generated for each updated ticket.

Payload object: We have chosen to structure the payload object (var pl) as we have. There is no obligation to keep the same structure. Yours can be defined to suit your requirements.

Payload options: In the payload options (var opts), we have commented out //message_name: 'UpdateIncidentInbound',. This is because we have chosen to include the message name in the structure of the payload object.

Message name: Unifi needs to know the message name in order to know how to process the inbound request. We can either set it in the payload (as we have), or in the options (as per the commented out line).

Your Response Script form should look like this:

8) Save the Poll Processor.

Now let's move on and configure the Poller.