We will configure a scheduled poll to query the remote system at regular intervals and pull back data from the relevant, newly created, unbonded records which it will pass to Unifi to process.
To set up a scheduled poll that will query the remote system at regular intervals, check whether any new records have been created 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 the relevant inbound and outbound messages to process and respond to the returned data. We will also need to make some further changes before we can test our create scenario (in order to identify which records to poll for). We will look at the polling records in turn over the next couple of pages.
Before configuring those polling records, let's first look at Connection Variables.
Connection Variables can be especially useful if you have multiple connection environments - e.g. Dev, Test, Prod - each containing different data.
Although having multiple environments may not apply to this integration, we will create Connection Variables to contain certain data values which will be substituted into the Poll Processor scripts.
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.
We will use Connection Variables to identify which Assignment group to look for and which field elements to return data from when polling.
Before continuing we would like to draw your attention to some of the relevant icons that will be visible down the left hand navigation strip in the Unifi Integration Designer.
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.
g) 'Connections' icon: Opens the current integration's Connections page.
It is necessary to identify which of the non-bonded records in the external instance (your PDI) are applicable to the integration. One way of doing this is to define a specific Assignment group to which all incidents will be assigned for the integration.
We will create a new group which will be used only for this integration. We will then use the Sys ID of that group in a Connection Variable to pass into the Poll Processor scripts to enable Unifi to identify which records should be bonded.
In your PDI, navigate to User Administration > Groups. Click New.
The fields to be configured for the Group New record are as follows:
Your Group New record should look like this:
Submit the record.
This variable will contain the sys id of the group created above. It will be used in the Poll Processor Setup script to identify which non-bonded Incidents to query.
To open Unifi Integration Designer, navigate to [ws] 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 'external_group' New Connection Variable fields to be configured are as follows:
*Value: Value may vary. Use the sys id of the group created in your PDI.
Your 'external_group' New Connection Variable modal should look like this:
Click Submit.
You will be redirected back to the Variables page of the Connection record.
This variable will contain the minimum set of fields required to identify and select records in the remote system.
Click New.
The 'base_fields' New Connection Variable fields to be configured are as follows:
Your 'base_fields' New Connection Variable modal should look like this:
Click Submit.
You will be redirected back to the Variables page of the Connection record.
This variable will contain fields which will be retrieved from the remote system, in addition to the required base_fields. We have chosen a sample selection of fields. You may choose different fields if you wish. However, the fields you select here must also be mapped with corresponding Field Records (more on that on the CreateIncidentInbound Fields page).
Click New.
The 'data_fields' New Connection Variable fields to be configured are as follows:
Your 'data_fields' 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 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.
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:
Your New Poll Processor modal should look like this:
Submit and view to further configure the Poll Processor.
The Setup Script is the first script to run (it runs at the point in time the Poll Request is created). It is used to build the environment for the poll and define what it will do. We will use it to setup the URL that will be called.
Navigate to Scripts > Setup Script.
The Setup script field is to be configured as follows:
The code in the Setup script field should look like this:
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.
Note: We have included the /table/incident
element of the endpoint url because we used the truncated url in the Connection when following the Outbound Incident Guide. If you have used the full url there, then this element can be excluded here.
&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:
Navigate to Request Script.
The Request Script is used to reach into the remote system and execute the request. We will use the ServiceNow RESTMessageV2() web service to make a REST call to the URL defined in the Setup Script.
The Request script field is to be configured as follows:
The code in the Request script field should look like this:
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:
Navigate to Response Script.
The Response Script is used to process the information returned from the remote system. We will pass this data to Unifi to process.
The Response script field is to be configured as follows:
The code in the Response script field should look like this:
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
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:
Save the Poll Processor.
Now let's move on and configure the Poller.
A Poller is a configuration record which defines the frequency of polling and which logic to use.
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.
Click the 'Pollers' icon & then New.
The fields to be configured for the New Poller modal are as follows:
*These fields are mandatory, or automatically defaulted to true.
Your New Poller modal should look like this:
Submit and view to further configure the Poller.
The fields to be configured for the Details form are as follows:
Your Details form should look like this:
Navigate to 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 and respond to the inbound Requests, we next need to configure our Messages.
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|---|---|
Field | Description | Value |
---|
Field | Description | Value |
---|
Field | Description | Value |
---|
Name
Descriptive name, e.g. DBAs, Network, etc.
<Your Name>
Description
The description of the Group.
<Your Description>
Key
A unique name that will be used to get the value.
'external_group'
Value
The variable value to be used in the integration.
<Your Value>*
Description
Describe what this connection variable is for and how it should be used.
<Your Description>
Key
A unique name that will be used to get the value.
'base_fields'
Value
The variable value to be used in the integration.
'sys_id,number,correlation_id,sys_updated_on,sys_updated_by'
Description
Describe what this connection variable is for and how it should be used.
<Your Description>
Key
A unique name that will be used to get the value.
'data_fields'
Value
The variable value to be used in the integration.
'caller_id,short_description,description,state,impact,urgency'
Description
Describe what this connection variable is for and how it should be used.
<Your Description>
Name
The name of the Processor.
<Your Name>
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
Request script
The script that executes the request.
Update the code in the Request script field so that it looks like the code below
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
Name* | The name of your Poller. | <Your Name> |
Poll processor* | The Poll Processor to use when running this Poller. | <Your Poll Processor> |
Run | The frequency at which the Poller should run. | 'Periodically' |
Run as | Poller will run with credentials of specified user. | <Your Inbound user> (from Connection) |
Active* | Set to true to use this Poller record for processing. | <true> |
Description | A description of what this Poller is for and/or how it works. | <Your description> |
Repeat interval* | The interval at which the Poller should repeat. | '15' (Minutes) |
Starting | The date/time the Poller should start. | <Your Start date/time> |