Welcome

We will again be configuring two Pollers and two Poll Processors acting as parent and child. This time, we will use them to pull attachments from bonded records on an external instance, pass the relevant data between them and then pass the attachments to Unifi. We will then configure the relevant inbound Message in order to process those attachments.

The relevant pages for configuring those records are:

• Get Attachment Poll Processor

• Get Attachment Poller

• Select Attachments Poll Processor

• Select Attachments Poller

• AddAttachmentInbound Message

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 Attachment API of your Personal Developer Instance (PDI).

The Incident Parent and Child Poller Guide demonstrated how you might poll for updates from the table API of your PDI, but 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. We will edit the Child Poll Processor so that it also kicks off another on-demand poll, scanning for attachments.

This guide will also demonstrate polling in two stages - an initial, on-demand poll, scanning for attachments added to bonded records and a subsequent, on-demand poll, that takes each of the attachments and passes them to Unifi to process.

The initial, on-demand poll (for attachments) will be kicked off by the edited Child Poll Processor.

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 be utilising the previously configured Parent & Child Pollers as follows.

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.

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), this Child Poll Processor will also need to store and check other data in order to decide which Message to use to process that data. We will also edit it so that it will kick off the initial, on-demand Poller to scan for attachments.

The two new Parent & Child Pollers will be configured as follows.

The first (Parent) Poll Processor will scan for and identify any attachments added to bonded Incidents - passing details to the second (Child) Poll Processor, which will retrieve each attachment - building a payload & passing it to Unifi to process.

Inbound Messages

In order to process the attachments returned from the remote system we will configure a new inbound Message.

• AddAttachmentInbound

If you have edited the Endpoint URLs in the Connection, the Create Poll Processor and the Parent & Child Poll Processors, it will be necessary to utilise the Messages we created in the earlier Guides in order to test the Integration and process the data that is returned from the remote system. The following Messages will be used:

• CreateIncidentInbound

• UpdateIncidentInbound

• ResolveIncidentInbound

• CreateIncidentResponse

Outbound Messages

For the same reason as above and if you have edited the outbound Message Path for the previously configured Messages, it will be necessary to test those also. The following Messages will be used:

• CreateIncident

• UpdateIncident

• ResolveIncident

• CreateIncidentInboundReceipt

Let's now configure the AddAttachmentInbound Message.

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: get_attachment_poller

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

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 'get_attachment_poller' New Connection Variable fields to be configured are as follows:

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

Click Submit.

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

Variable: select_attachments_poller

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

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

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

Your 'select_attachments_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 edit the Endpoint URLs.

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 'get_attachment_poller' Connection Variable with the sys_id.

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 Select Attachments 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) {

    // Params contain an attachment object containing details of the remote attachment
    // remote_id : The sys_id of the attachment in the remote system
    // Also contains: file_name, content_type, size_bytes

    var attach_id = params.attachment.remote_id;

    poll_request.endpoint_url += '/attachment/' + attach_id + '/file';

})(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 request, response;

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

    // Save the response as a new attachment (on the poll request)
    request.saveResponseBodyAsAttachment(
      poll_request.getTableName(), poll_request.sys_id, params.attachment.file_name
    );

    response = request.execute();

    poll_request.response_code   = response.getStatusCode();
    poll_request.response_status = response.getErrorMessage();
    if (response.haveError()) {
      throw '\nResponse Code: ' + response.getErrorCode() + '\nResponse error: ' + response.getErrorMessage();
    }

    // Return the sys_id of the saved attachment
    answer = response.getResponseAttachmentSysid() + '';

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

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

    // Establish the environment
    var poll_helper = new x_snd_eb.PollHelper(poll_request);
    var info = [
        'Incident : ' + params.int_ref,
        '- Attachment file name: ' + params.attachment.file_name,
        '- Attachment id: ' + response
    ];

    // The response should be the sys_id of the created attachment
    params.attachment.data = '<x-attachment-data sys_id="' + response + '" />';

    // Build the payload for Unifi
    var payload = {
        sys_id : params.ext_ref,
        correlation_id : params.int_ref,
        attachment : params.attachment
    };

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

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

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

var poll_helper = new x_snd_eb.PollHelper(poll_request);

poll_helper.processInbound({
        message_name : 'AddAttachmentInbound',
        payload : JSON.stringify(payload)
    });

Your Response Script form should look like this:

Save the Poll Processor.

Now let's move on and configure the Get Attachment Poller.

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 'select_attachments' 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 edit our previously configured Child Poll Processor so that it becomes the parent of this.

We will edit the previously created Child Update Poller, so that it runs our new "Unifi - SN REST Poller Single Incident with Attachments" (as created in the previous section) instead of the originally configured Poll Processor.

To edit the Child update Poller, click the 'Pollers' icon.

Click to open < Your Child Update Poller > (created following the Incident Parent and Child Poller Guide)

Details

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

*Poll Processor: Value may vary. Choose the Poll Processor you created in the previous section.

Your Details form should look like this:

Save the Poller.

In the next section, we will look at the Inbound Messages.

To facilitate polling both the Table API and Attachment API, we will need to edit the Endpoint URLs configured in earlier Guides in the following places:

• Connection

• Outbound Message Path

• Previously Configured Poll Processors

Edit Connection

First, edit the Endpoint URL in the Connection.

In Unifi Integration Designer, navigate to the 'Connections' icon. Click to open & edit < Your Connection > (configured following the Outbound Incident Guide).

Remove /table/incident from the Endpoint URL and Save. (This will be prepended to the Outbound Message Path & previously configured Poll Processors.)

Edit Outbound Message Path

Edit each of the previously configured Outbound Messages:

• CreateIncident

• UpdateIncident

• ResolvIncident

• CreateIncidentInboundReceipt

To edit the CreateIncident Message, navigate to the 'Messages' icon & click to open the CreateIncident Message.

Navigate to Outbound > Settings. Add the previously cut /table/incident to the Path & Save.

Edit Previously Configured Poll Processors

Edit the Endpoint URL in the Setup script for each of the previously configured Poll Processors_:*_

To edit the Unifi - SN REST Poll Processor, navigate to the 'Poll Processors' icon & click to open the Unifi - SN REST Poll Processor.

Navigate to Scripts > Setup Script.

Edit the code by prepending the existing Endpoint URL with /table/incident i.e. insert it immediately after the poll_request.endpoint_url += ' value & click Save. That line of code should now read as follows:

Your Unifi - SN REST Poll Processor Setup Script should now look like this:

Once complete we can configure the first of our Child Poll Processors, the Get Attachment Poll Processor.

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

New Message Modal

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

Your AddAttachmentInbound 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:

Navigate to Advanced > Script Editor.

Script Editor Fields

Click on View > Inbound.

The Script Editor fields to be configured are as follows:

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

Your Script Editor fields should look like this:

Click Save.

We can now move on to Testing.

We will create some bonded tickets in the remote instance - initially testing the outbound Message scenarios. Those bonded tickets will then also be available to test the inbound Message scenarios.

Test CreateIncident

In native ServiceNow, navigate to Incident > Create New.

The Incident fields to configure are as follows:

Your Incident form should look like this:

After you right-click & 'Save', 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.

Test UpdateIncident

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:

Test ResolveIncident

Resolve the same bonded ticket in the originating instance to cause the ResolveIncident 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:

Navigate to the Notes tab to view the Activities stream:

Next, we shall test the CreateIncidentInbound Message.

If active, 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 it off, in Unifi Integration Designer, click the 'Pollers' icon, locate the Parent Update Poller & set Active to false.

If you have edited the Connection, Poll Processors & Outbound Message Paths and because 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, it will be necessary to test, utilising all the previously configured Messages, along with the new one. The Message Scenarios we shall be testing are:

• CreateIncident

• UpdateIncident

• ResolveIncident

• CreateIncidentInbound

• UpdateIncidentInbound

• ResolveIncidentInbound

• AddAttachmentInbound

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

First, we shall test the Outbound Scenarios.

To set up an on-demand poll that will query the remote system for attachments and pass each to a subsequent poll, which will then retrieve them and pass them to Unifi to process, we will need to configure a further two each of the following records:

• Child Poll Processor

• Child Poller

(Note: one of the children will be a parent to the other)

We will also need to edit the previously configured (per the Parent & Child Poller Guide) to kick-off the first of our attachment Child Pollers.

To facilitate polling both the Table API and Attachment API, we may also need to make changes to the Endpoint URLs* configured in earlier Guides in the following places: (*only if the Connection contains the full endpoint url)

• Connection

• Outbound Message Path

• Poll Processor Setup Script

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

Create Test Incident

In your PDI, navigate to Incident > Create New.

The Incident fields to configure are as follows:

Your Incident form should look like this:

You should now have a non-bonded ticket in the remote instance (assigned to <Your Assignment group>):

Poll for Creates

In native ServiceNow, navigate to Unifi > Polling > Poll Requests. Click to Open & view the generated Poll Request. Confirm that only the one Incident was found (this is exactly as we expect because we are only polling for Incidents assigned to a specific Assignment group):

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

Confirm the following:

The Transaction has created the bonded ticket in this instance.

Your new Incident should look like this:

The Transaction has updated the bonded ticket in the remote instance (your PDI) (with the correlation id).

Your originating Incident should look like this:

Next, we shall test the UpdateIncidentInbound 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.

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:

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 use it to build an attachment object to pass this data to the next Poll Processor.

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.

Update Child Poll Processor

Now let's move on and configure the Select Attachments Poller.

Copy Child Poll Processor

To copy the Child Poll processor, in Unifi Integration Designer, click the 'Poll Processors' Icon.

Copy Poll Processor Modal

Click Copy.

Your Copy Poll Processor modal should look like this:

You will be redirected to the Details page of the newly copied Poll Processor.

Edit Copied Poll Processor

The fields to edit for the Copied Poll Processor are as follows:

Your Copied Poll Processor should look like this:

Navigate to Scripts > Response Script.

Response Script

The Response Script field is to be edited as follows:

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

Your Response Script form should look like this:

Click Save.

Update Select Attachments Poll Processor

The following Poll Processors should now be in place on the Integration:

Now let's move on and edit the Child Update Poller (configured when following the Incident Parent and Child Poller Guide) so that it runs the Poll Processor created above.

This Guide has shown us how we might configure a Parent and Child Poller integration - polling data from both the Table API and Attachment API of a Personal Developer Instance (PDI) (building on the previously configured Parent & Child Pollers). We polled for attachments in two stages - an initial on-demand poll, scanning for attachments added to bonded, updated records and a subsequent, on-demand poll, pulling back the attachments and processing that data with the relevant inbound Message. As such, we created the following records:

• Get Attachment Poll Processor

• Get Attachment Poller

• Select Attachments Poll Processor

• Select Attachments Poller

We also copied and edited the previously configured Child Poll Processor so that it kicked off our Select Attachments Poller (editing the Child Poller so that it ran the copied Poll Processor).

To facilitate the ability to poll both the Table API and Attachment API we truncated the Endpoint URL in the Connection and prepended the Endpoint URLs in the Poll Processors and the Outbound Message Paths with either /table/incident or /attachment (as appropriate).

In testing our integration, we created & updated incidents in 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, along with poll requests scanning for & retrieving attachments, 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 technical documentation.

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

Resolve Test Incident

In the remote instance (your PDI), navigate to one of < Your Incidents > updated 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 Parent 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:

Update from Remote Instance

In the remote instance, select one of the bonded tickets.

Add an attachment to the record .

Poll for Updates

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

Open the corresponding Parent Poll Request & confirm that the Incident was found and that subsequent child Poll Requests were also triggered:

Notice the Parent & Child Update Poll Requests and the Select & Get Attachment Poll Requests:

Open the corresponding Child Poll Request & confirm that the Message name was UpdateIncidentInbound.

Open the corresponding Select Attachments Poll Request & confirm that the Attachment was found. Notice the attachment_hwm, ext_ref & int_ref passed in as parameters:

Open the corresponding Get Attachment Poll Request & confirm that the Attachment was found. Notice the attachment, ext_ref & int_ref passed in as parameters:

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

Confirm the Attachment has been added to the bonded ticket in the originating 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 Parent Poller > (as configured on the 'Parent Poller' page of the Incident Parent and Child Poller Guide). 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 Update Poll Requests & confirm that the Message name was UpdateIncidentInbound (found in the Response status).

Open each of the corresponding Select Attachments Poll Requests & confirm that the Response status says No Attachments returned (this is expected because no attachments were added).

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.

Next, we shall test the ResolveIncidentInbound Message.