Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
We will configure a scheduled poll to query the remote system at regular intervals and pull back data that has changed 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 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.
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.
Rather than create a new poller, you can edit the previously configured 'Update Poller', changing the Name, Description & Poll Processor.
(You could choose to copy the previous Poller instead. However, there is no need to have two pollers polling for updates every 5 minutes, so if copying the previous poller, remember to deactivate it.)
1) 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:
5) Save the Poller.
In order to process the inbound Requests, we need to configure the Inbound Messages.
#
Field
Description
Value
2*
Name
The name of your Poller.
<Your Name>
3
Description
A description of what this Poller is for and/or how it works.
<Your Description>
4*
Poll processor
The Poll Processor to use when running this Poller.
<Your Poll Processor> (the one just created)
Follow this second of five Poller Guides to configure an integration - polling the table API of your Personal Developer Instance (PDI) for updates & deciding between multiple messages to process.
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.
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).
This Guide is complementary to the Outbound Incident Guide. It assumes that both the Integration and the Connection are still in place and will be using those same elements as configured there. It also assumes that you know how to use the REST API of your PDI to query for information and read ticket data.
If you haven’t completed the Outbound Incident Guide, please review & complete the following sections of that document, as they must be in place before continuing with this Guide:
This document also builds on the Incident Update Poller Guide. As such, it assumes that the changes made in that Guide are still in place and will make use of some of those same elements.
If you haven’t completed the Incident Update Poller Guide, please review & complete the following sections of that document at least, as they must be in place before continuing with this Guide:
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
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.
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.
A Poll Processor contains the logic that will be applied when polling a remote system for data. It contains three main scripts:
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).
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.
The Response Script is used to process the information returned from the remote system.
Do not build integrations directly within the Unifi application scope. This can create issues with upgrades and application management.
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.
We will configure another inbound update type message to process the data returned from the poll and update our target record.
Rather than create the ResolveIncidentInbound Message from scratch, it will be quicker to copy the UpdateIncidentInbound Message and make some minor changes.
Click on the 'Messages' icon to open the Messages page.
1) Click the ellipsis to the right of the UpdateIncidentInbound Message & then click Copy.
The fields to edit for the Copy Message modal are as follows:
Your Copy Message modal should look like this:
3) Click Copy.
You will be redirected to the Details page of the newly created ResolveIncidentInbound Message.
The Details fields to be edited are as follows:
Your Details form should look like this:
5) Navigate to Message > Bond.
The Bond fields to be edited are as follows:
Your Bond form should look like this:
9) Click Save.
We are now ready to configure the Fields for the ResolveIncidentInbound Message.
We will utilise the Field & Field Map records to configure the Message Scripts for the ResolveIncidentInbound Message.
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.
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).
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.
Unifi created the incident.state (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. It is, therefore, displayed in the Fields list on the ResolveIncidentInbound Message with Active set to false.
From the ResolveIncidentInbound Message, navigate to Message > Fields.
Your ResolveIncident Message Fields page should look like this:
1) Find the incident.state (Integration level) Field & set Active to true.
The empty circle icon next to the Field name turns green & contains a green ‘check’ (to indicate that Message level configuration exists for this Field) when we set Active to true. (The ‘Build Integration’ button became visible in the banner when we copied the UpdateIncidentInbound Message).
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.
2) 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.
3) To edit, set Inherit to False.
4) Save the record (the fields now become editable).
Field inheritance is set to true by default. This means the record will be updated with integration-level Field values when saved (except for Active, Inherit and Message values).
You can either uncheck the Inherit field to configure locally, or edit the integration-level Field record. We will choose to uncheck the Inherit field and configure locally, because we want this inbound Field to be different to the outbound one (and the integration-level Field which was automatically created at that time).
5) 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:
9) Save the record.
As with incident.state, Unifi created the incident.close_notes (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. We will now create the Message level counterpart for the ResolveIncidentInbound Message.
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.
10) Find the incident.close_notes (Integration level) Field & set Active to true.
11) 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.
12) To edit, set Inherit to False.
13) Save the record (the fields now become editable).
14) 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:
18) Save the record.
Again, Unifi created the incident.close_code (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. We will also create the Message level counterpart for the ResolveIncidentInbound Message.
As with 'incident.state' the 'incident.close_code' Field record is a Choice 'type' Field. We have already configured the choices at the Integration level, so there's no need to 'Generate field choices' for this Message level record because the Field Map always looks for them on an Integration level Field which has the same name.
From the ResolveIncidentInbound Message, navigate to Message > Fields.
19) Find the incident.close_code (Integration level) Field & set Active to true.
20) 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.
21) To edit, set Inherit to False.
22) Save the record (the fields now become editable).
23) 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:
27) Save the record.
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:
28) Click on Build Message.
You will see the 'Message build successful' Info Message.
29) Navigate to Advanced > Script Editor > View > Inbound to view the auto-generated code.
Your Script Editor fields should look like this:
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:
Stage to Target:
Your Stage to Target Message Script should look like this:
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.
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.
Before continuing we would again like to remind you of the relevant icons that are visible down the left hand navigation strip of 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.
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:
2) 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 initial Poll Processor fields to be configured are 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.
query: Instead of querying all the records on the remote instance, we deliberately limit the records to those where the correlation id is not empty (i.e. it's bonded), that haven't been updated by the Authentication user (our system) and that were 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.
(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.
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:
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.
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:
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; these include the essential PollHelper() function (which we initialise from the poll_request) along with two other functions: get_bond() to find the Bond for an Incident & get_message_name() to work out the message type to send to Unifi based upon the change of state.
After that it loops through each of the returned tickets. For each ticket, it logs the incident number & time, finds the bond & returns any previous data stored on the bond, decides which Message to use, sets up a payload object and submits it to Unifi by calling the processInbound() method. It then saves the current incident as the previous incident for the next poll & 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 (processing each result), 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 enable Unifi
processInbound(): Having the 'poll_helper.processInbound()' function 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 payload
) as we have. There is no obligation to keep the same structure. Yours can be defined to suit your requirements.
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 declare a variable that sets it which is passed into the processInbound() function along with the payload. (Unifi will always check processInbound() first. If no Message name is set here it will use the 'Identify message script' on the Integration).
Your Response Script form should look like this:
8) Save the Poll Processor.
Now let's move on and configure the Poller.
For a full description of the available Field Maps, please see the relevant page in our .
For more information on Field Inheritance click .
Note: We have included the /table/incident
element of the endpoint url because we used the truncated url in the Connection when following the . If you have used the full url there, then this element can be excluded here.
#
Field
Description
Value
2
Message name
The message name that is unique for this integration.
'ResolveIncidentInbound'
#
Field
Description
Value
4
Description
The description for this message and the requirement it is meeting.
<Your description>
#
Field
Description
Value
6
Bond pending
Process this message when the bond state is Pending.
<true>
7
Bond suspended
Process this message when the bond state is Suspended.
<true>
8
Bond vendor suspended
Process this message when the bond state is Vendor suspended.
<true>
Incident Field | Field Map |
state | 'PI - Choice'* |
close_notes | 'PI - String'* |
close_code | 'PI - Choice'* |
# | Field | Description | Value |
6 | Path | Where in the payload the data will be placed. | 'detail' |
7 | Inbound | Set to true to use for inbound Messages. | <true> |
8 | Outbound | Set to true to use for outbound Messages. | <false> |
# | Field | Description | Value |
15 | Path | Where in the payload the data will be placed. | 'detail' |
16 | Inbound | Set to true to use for inbound Messages. | <true> |
17 | Outbound | Set to true to use for outbound Messages. | <false> |
* | Mandatory | Set to true to make mandatory. | <true> |
# | Field | Description | Value |
24 | Path | Where in the payload the data will be placed. | 'detail' |
25 | Inbound | Set to true to use for inbound Messages. | <true> |
26 | Outbound | Set to true to use for outbound Messages. | <false> |
* | Mandatory | Set to true to make mandatory. | <true> |
# | Field | Description | Value |
1 | Name | The name of the Processor. | <Your Name> |
# | 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 |
# | 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 |
# | 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 |
Follow these steps to test the UpdateIncidentInbound Message.
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.
In native ServiceNow, navigate to Incident > Create New.
The Incident fields to configure are as follows:
Though the CreateIncident Message has been configured to map more than just the Short Description & Description fields, we have only filled these fields because that is all whe have included in the payload of our Poller.
Your Incident form should look like this:
4) Note the Info Message confirming the CreateIncident Message is being sent to your Integration.
5) Note the Bond is 'Open' and both the Internal & External reference are in place.
Repeat as necessary so that there are two or three bonded tickets in the remote 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.
We can see that the three CreateIncident messages & one UpdateIncident message have been sent. All are Complete & Accepted & display the relevant Incident & Bond numbers.
Confirm the Transaction has updated the bonded ticket in the remote instance:
We can see that the update has reached the bonded ticket (& that the correlation id matches the outbound Incident number)
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):
in the remote instance, update two of the bonded tickets in turn.
Updates have been made to the Description field only. Correlation ID is highlighted for us to identify the correct bonded ticket.
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.
We can see that two UpdateIncidentInbound messages have been received. Both are Complete & Accepted & display the relevant Incident & Bond numbers.
Confirm the Transactions have updated the bonded tickets in the originating instance.
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.
You should have successfully configured a Poll Processor and Poller. You should also have configured the ResolveIncidentInbound message. The next thing to do is to test.
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.
Congratulations on using this Multiple Message Poller Guide to successfully poll your PDI for updates - deciding between multiple messages in Unifi to process the returned data.
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.
Follow these steps to test the ResolveIncidentInbound Message.
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:
4) Right-click & Save.
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.
We can see that the ResolveIncidentInbound message has been received, is Complete & Accepted and displays the relevant Incident & Bond numbers.
Confirm the Transaction has updated the bonded ticket in the originating instance:
We can see that the State, Resolution code & Resolution notes have been updated on the bonded ticket.
Navigate to the Notes tab to view the Activities stream:
We can see that the update has also been logged in the Activities stream.
For further information please see our .
If you have any feedback or questions, please contact us via our website .
#
Field
Description
Value
1
Caller
Person who reported or is affected by this incident.
<Your Caller>
2
Short description
A brief description of the incident.
<Your Short description>
3
Description
Detailed explanation on the incident.
<Your Description>
# | Field | Description | Value |
1 | State | The Incident lifecycle state. | ‘Resolved’ |
2 | Resolution code | The Incident resolution code. | <Your Resolution code> |
3 | Resolution notes | The Incident resolution notes. | <Your Resolution notes> |
We will need to configure inbound Messages to process the data returned from the poll.
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.