Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Follow this guide to configure a poller integration - polling the table API of your Personal Developer Instance (PDI) for creates only. This is the third of five Poller Guides. See 'Scope' for more.
We will be configuring a Poller and Poll Processor in order to pull Incident records which have been created in an external instance and pass the data to Unifi. We will then configure the relevant Messages in order to process and respond to 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.
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 is complementary to and 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:
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 demonstrate how you might poll for newly created, unbonded records from the table API of your PDI and then configure an inbound Create Message (along with its outbound Receipt) to process and respond to 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.
We will need to store and check some returned data in order to evaluate when the data was changed and which system has made the updates to the data (we don’t want to pull back data we have changed).
We will begin by polling for newly created, unbonded records only and processing those requests using a create message in Unifi.
We will also need to make some additional changes in order to identify which unbonded records to poll.
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:
| Field | Description | Value |
|---|---|---|
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:
| Field | Description | Value |
|---|---|---|
*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.
We will configure an outbound receipt message to respond to the data returned from the poll and update the originating record in the remote instance with the correlation id.
Click the 'Messages' icon, then New.
The fields to be configured for the CreateIncidentInboundReceipt New Message modal are as follows:
| Field | Description | Value |
|---|---|---|
Your CreateIncidentInboundReceipt New Message modal should look like this:
Click Submit and view to further configure the Message.
Navigate to Message > Response.
The Response fields to be configured are as follows:
Your Response form should look like this:
Navigate to Outbound > Settings.
The Outbound Settings fields to be configured are as follows:
*Path
Only add the /table/incident element of this value if you have used the truncated Endpoint URL in the Connection. If you have used the full Endpoint URL, this element can be excluded here.
Your Outbound Settings form should look like this:
Click Save.
We are now ready to configure the Fields for our CreateIncidentInboundReceipt Message.
We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncidentInboundReceipt Message.
The ‘incident.number’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Incident Update Poller Guide. We will now create its Message level counterpart.
From the CreateIncidentInboundReceipt Message, navigate to Message > Fields.
Your CreateIncidentInboundReceipt Fields page should look like this:
Find the incident.number (Integration level) Field & set Active to true.
The ‘Build Integration’ button becomes visible in the banner and 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. (Note: the empty 'circle icon' indicates that the Integration level Field is available to add to the Message.).
By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.
We don't need to configure any more the Field records for the CreateIncidentInboundReceipt Message, so we are ready to build our message scripts.
Click on Build Message.
You will see the 'Message build successful' Info Message.
Navigate to Advanced > Script Editor > View > Outbound to view the auto-generated code.
Your Script Editor fields should look like this:
We will look at the Message Scripts in turn.
Source to Stage:
Your Source to Stage Message Script should look like this:
Stage to Request:
Your Stage to Request Message Script should look like this:
Next, we'll configure the CreateIncidentInbound Message.
You should have successfully configured a Poll Processor and Poller. You should also have configured an inbound create type Message and its outbound receipt. Follow these steps to test.
It may help to turn off the 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.
In order to test our Integration we will need to create test Incidents in the remote instance.
In your PDI, navigate to Incident > Create New.
The Incident fields to configure are as follows:
*Assignment group: This should be the group you created in your PDI to enable Unifi to identify which newly created, non-bonded tickets to poll and whose sys id was stored in a connection variable and passed into the Setup Script of the Poll Processor.
Your Incident form should look like this:
Note the values entered (including State), so that you can check them against the mapped fields on the corresponding record in the instance being integrated to.
Repeat the above steps, this time choosing a different Assignment group.
Your Incident form should look like this:
Repeat the above steps for a third time, this time leaving Assignment group (empty).
Your Incident form should look like this:
Repeat the above steps for a fourth time, again setting the Assignment group to <Your Assignment group> (as per Step 4 in the table above).
Your Incident form should look like this:
You should now have at least four non-bonded tickets in the remote instance (two of which are assigned to <Your Assignment group>):
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 only the two Incidents were 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.
Navigate to Unifi > Transport > Transactions.
Navigate to Unifi > Unifi Operations Manager.
We can see that two CreateIncidentInbound message has been received. They are Complete & Accepted and display the relevant Incident & Bond numbers.
For each Transaction, confirm the following:
The Transaction has created the bonded ticket in this instance.
Your first new Incident should look like this:
Your second new Incident should look like this:
The calller_id was populated with the default value gs.getUserID() because the table API was returning display_value instead of value. If the Create Poller was active and running then the caller_id would be the Integration User. Because the Create Poller was manually executed whilst inactive, then the value is the user who executed the poll.
The Transaction has updated the bonded ticket in the remote instance (your PDI) (with the correlation id).
Your first originating Incident should look like this:
Your second originating Incident should look like this:
For completeness, to prove we are only querying and pulling back data from non-bonded records, create an incident in this instance which causes the outbound CreateIncident Message to fire - as per the Outbound Incident Guide - (creating a new Incident in the remote instance) & run the Poller again.
What do you expect to happen?
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.
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.
Congratulations on successfully polling your PDI for non-bonded Incidents using this Create Poller Guide.
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 the relevant message to process and respond to that data. As such, we created the following records:
Connection Variables
Poll Processor
Poller
Messages
Fields
We also created & used a specific Assignment group in the remote instance (PDI), in order to facilitate the following:
Ticket Identification
In testing our integration, we created some incidents in the remote instance which were non-bonded and assigned to a range of groups. We then polled for newly created tickets. We successfully proved that we were only querying non-bonded records which were assigned to a specific group, pulling back records created 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 non-bonded ticket.
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 .
It is possible to run the Build process at the Integration level. This will cause the process to cycle through each of the Messages on the Integration in turn.
We have been running the Build process at the Message level in order to see the changes in our Message Scripts as we go. This may be considered good practice (particularly when first starting out) as any discrepancies can be discovered & rectified as you go (in potentially fewer, smaller batches). Once you are more practiced and confident in the accuracy of your configurations, you can run the Build process at the Integration level. This means that the process will cycle through all the Field records on each of the Messages on the Integration in turn & auto-generate all the relevant Message Script code.
As mentioned on the page, we saw that a 'Build Integration' button had appeared in the banner at the top of the page. This was because, whenever a change is made to a Field record that is associated to a Message (whether that is being created, updated, or deleted) the button will be available and act as a visual reminder that changes have been made and Message Script(s) need to be built.
To run the Build Process at the Integration level we have two choices. We can either either run it from the Integration record, or we can use the 'Build Integration' button which appears in the banner at the top of the page.
To run it from the Integration record. In Unifi Integration Designer, navigate to: 'Integration' icon.
Click Build.
On the Build Integration modal, click Build.
When complete, you will see the following Integration Build Worker modal:
Click Done.
Running Build on the Integration has processed all 9 Messages (i.e. all the Messages created following the Outbound Incident Guide, Incident Update Poller Guide & Incident Multiple Message Guide as well as this Guide)
Navigate to: 'Messages' icon.
Feature Alert: The widget at the bottom of the page also shows when 'Build' was last run.
Click through each of the relevant Messages in turn, navigating to Advanced > Script Editor to view the auto-generated code in the Message Scripts.
We are now ready to move on and Test the Create Poller.
We will configure an inbound create message to process the data returned from the poll and create a new target record.
Click the 'Messages' icon, then New.
The fields to be configured for the CreateIncidentInbound New Message modal are as follows:
| Field | Description | Value |
|---|
Your CreateIncidentInbound New Message modal should look like this:
Click Submit and view to further configure the Message.
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.
The Bond fields to be configured are as follows:
*These fields are automatically populated.
*Set bond state choices: None, Pending, Open, Suspended, Vendor suspended, Closed
Your Bond form should look like this:
Navigate to Inbound > Settings.
The Inbound Settings fields to be configured are as follows:
*Bond reference method (defaulted to 'External' & not editable for Create type Messages):
Internal - lookup using the internal reference only.
External - lookup using the external reference only.
Both - lookup using both the internal and external references.
Bond reference method: The perspective of the available choices is in relation to the receiving instance i.e. Internal (internal reference) means the bonded ticket in our instance and External (external reference) means the bonded ticket in their instance. These settings define which values to lookup against to search for and validate whether or not a bond already exists.
In the case of a create type message (as per our requirement), it is defaulted to 'External' because there is not yet a bonded ticket in the receiving instance to reference (if we were to receive a create type message which referenced a bond that already existed it would be rejected because we don't want to create another bond for a record we've already seen ).
The code in the 'Reference lookup script' field should look like this:
Reference lookup script: It’s important to identify which message an asynchronous receipt is replying to. This script extracts the transaction’s unique identifier.
In the case of an inbound create/update (as per our requirement) it would return their external message id (source id) to identify which transaction our asynchronous receipt belongs to. (In the case of an inbound asynchronous receipt it would return our internal message id (target id) to identify which transaction their asynchronous receipt belongs to.)
Your Inbound Settings form should look like this:
Click Save.
We are now ready to configure the Fields for our CreateIncidentInbound Message.
We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncidentInbound Message.
It is worth copying all relevant OOTB Field Maps as are necessary for your integration before using any of them in your Field Records - thereby mitigating the risk of any potential issues with future upgrades
Some Field Maps should already have been copied for this Integration whilst following the Outbound Incident Guide and the previous two Poller Guides. There is one more that will need to be copied. The remaining Field Map we shall use for our CreateIncidentInbound Field record is:
Reference
To copy the Reference Field Map, navigate to the 'Field Maps' icon.
Click on the ellipsis to the right of the Reference Field Map & then click Copy.
The fields to edit for the Copy Field Map modal are as follows:
*Name: We have chosen to prefix the existing Field Map Name with the initials of our Integration (you are free to choose any appropriate means of identifying/differentiating).
Your Copy Field Map modal should look like this:
Click Copy.
You will be redirected to the Details page of the newly created Field Map.
Hints & Tips: Unifi automatically creates Integration level Fields when we first create the Message level equivalent records; those Integration level Fields are visible on the Fields list of the Messages we subsequently create. Therefore, a number of Fields already exist at the Integration level and are available to be added to the CreateIncidentInbound Message. In order to create the Message level records all we need to do is to set Active to 'true' for each of the relevant Integration level records and Unifi will create the Message level record for us. However, there may still be a few minor configuration changes to make, dependent on whether their Integration level configuration matches the requirements for this Message.
The relevant Integration level Fields that should already be in place are as follows: message.header, incident.short_description, incident.description & incident.state. We will deal with each in turn in the subsequent sections, detailing any changes that are needed to their configuration. For speed, you may wish to set Active to 'true' for each of them.
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). We will begin by configuring a Field record to deal with the transaction specific data.
The ‘message.header’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Incident Update Poller Guide. We will now create its Message level counterpart.
From the CreateIncidentInbound Message, navigate to Message > Fields.
Your CreateIncidentInbound Fields page should look like this:
Find the message.header (Integration level) Field & set Active to true.
As before, when we set Active to true the ‘Build Integration’ button becomes visible in the banner (which acts as a visual reminder that Field configuration has changed and the Message Scripts need to be built) and 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).
(The empty 'circle icon' indicates that the Integration level Field is available to add to the Message.).
By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart. There is no need to edit the settings any further for this Message level Field as the ones copied from the Integration level record already match our requirements.
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 only chosen to include the caller_id, short_description, description, state, impact & urgency elements in both the Setup script & Response script of the Poll Processor, this Guide will focus on those six. 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.
Important: Although the ‘incident.caller_id’ (Integration level) Field record is already in place (automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide), we will NOT be using it to create the Message level counterpart for the CreateIncidentInbound Message. This is because that is a String 'type' Field. Instead, we shall create a new Reference 'type' Field record.
The reason for using different Field 'types' for inbound & outbound for the Caller field is because of the requirements of integrating with the ServiceNow table API. Sending to the table API requires the value whereas pulling from the table API gives us an object which contains the value. This is the reason we use a String Field Map for sending and a Reference Field Map for receiving.
Note: This would apply to all reference fields (not just caller_id).
From the CreateIncidentInbound Message, navigate to Message > Fields. Click New.
The fields to be configured for the 'incident.caller_id' New Field modal as follows:
*These fields are automatically defaulted to true, or automatically populated.
**Field map: Value may vary. Choose the copy Field Map you created for your Integration.
Your 'incident.caller_id' New Field modal should look like this:
Click Submit and view to further configure the Field record.
The incident.caller_id Field record opens to the Details page.
To edit, set Inherit to False.
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).
Navigate to Field > Defaults.
Returning data from reference fields poses some challenges. When dealing with referential data, values in each system would need to match (this would apply whether we were receiving actual or display values). The ways of dealing with that fall outside of the scope and purpose of this Guide.
We have configured the endpoint so that the table API is returning the display_value element for reference data objects. This means that we can set a default value to ensure that the Caller field on the Incident is populated with a meaningful value should it not find a matching record (instead of throwing a process error).
The fields to be configured for the Defaults page are as follows:
The code in the 'Default inbound' script field should look like this:
Your Defaults page should look like this:
Save the record.
The ‘incident.short_description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.
To quickly navigate back to the CreateIncidentInbound Message, from the Details page of the incident.caller_id Field record...
...click the ‘Preview’ icon to the left of the Message field.
From the CreateIncidentInbound Message, navigate to Message > Fields.
Your CreateIncidentInbound Fields page should look like this:
Find the incident.short_description (Integration level) Field & set Active to true.
Click to open the incident.short_description (Message level) Field to make a few minor changes.
The incident.short_description Field record opens to the Details page.
To edit, set Inherit to False.
Save the record (the fields now become editable).
Navigate to Field > Settings.
Edit the incident.short_description Field record as follows:
Your incident.short_description Field record should look like this:
Save the record.
The ‘incident.description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.
To quickly navigate back to the CreateincidentInbound Message from the Details page of the incident.short_description Field record...
...click the 'Preview' icon to the left of the Message field.
From the CreateIncidentInbound Message, navigate to Message > Fields.
Your CreateIncidentInbound Fields page should look like this:
Find the incident.description (Integration level) Field & set Active to true.
There is no need to edit the settings any further for this Message level Field as the ones copied from the Integration level record already match our requirements.
If you had previously completed the Incident Update Poller Guide, then the Settings will already match because the Integration level Field record would have been updated when configuring the Fields for the UpdateIncidentinbound Message. Confirm that the Path, Inbound & Outbound settings match those configured for the incident.short_description Field record above.
The ‘incident.state’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.
Your CreateIncidentInbound Fields page should look like this:
Find the incident.state (Integration level) Field & set Active to true.
Click to open the incident.state (Message level) Field to make a few minor changes.
The incident.state Field record opens to the Details page.
To edit, set Inherit to False.
Save the record (the fields now become editable).
Navigate to Field > Settings.
Edit the incident.state Field record as follows:
Your 'incident.state' Field record should look like this:
Save the record.
There is no need to 'Generate field choices' for Message level Field records because the Field Map always looks for them on an Integration level Field which has the same name.
As with 'incident.state' the 'incident.impact' Field record is a Choice 'type' Field. These are used when you’re mapping choice field elements with static values that don't change per Message (e.g. State, Impact, Urgency). We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.
To quickly navigate back to the CreateincidentInbound Message from the Details page of the incident.state Field record...
...click the 'Preview' icon to the left of the Message field.
From the CreateIncidentInbound Message, navigate to Message > Fields. Click New.
The fields to be configured for the incident.impact (Message level) New Field modal are as follows:
*These fields are automatically defaulted to true, or automatically populated.
**Field map: Value may vary. Choose the copy Field Map you created for your Integration.
Your 'incident.impact' (Message level) New Field modal should look like this:
Submit the record.
You will be redirected back to the Fields page of the CreateIncidentInbound Message.
We will need to 'Generate field choices' for this Integration level Choice 'type' Field.
Navigate to the 'Fields' icon to open the Fields page.
Click to open the incident.impact (Integration level) Field record (the one where Message is empty).
The incident.impact Field record opens to the Details page.
Navigate to Field > Field Choices.
Click Generate field choices.
Click Generate on the 'Generate field choices' modal which displays.
The Field Choices are generated & now visible in the list.
There is no need to 'Generate field choices' for Message level Field records because the Field Map always looks for them on an Integration level Field which has the same name.
Because the incident.urgency Field record is the same ‘type’ (PI - Choice) & the majority of the settings are the same as the previously configured Field, it will be quicker to copy the incident.impact Field & make a few minor changes.
Navigate back to the CreateIncidentInbound Message, then navigate to Message > Fields.
Your CreateIncidentInbound Fields page should look like this:
Click the ellipsis next to the incident.impact Field record & click Copy.
The fields to edit for the Copy Field modal are as follows:
*This field is automatically populated.
Your 'incident.urgency' Copy Field modal should look like this:
Click Copy.
You will be redirected to the Details page of the newly created incident.urgency Field record.
We will need to 'Generate field choices' for this Integration level Choice 'type' Field.
Navigate to the 'Fields' icon to open the Fields page.
Click to open the incident.urgency (Integration level) Field record (the one where Message is empty).
The incident.urgency Field record opens to the Details page.
Navigate to Field > Field Choices.
Click Generate field choices.
Click Generate on the 'Generate field choices' modal which displays.
The Field Choices are generated & now visible in the list.
Now that we’ve configured the Field records for the CreateIncidentInbound message, we are ready to build our message scripts.
Navigate back to the CreateIncidentInbound Message, then navigate to Message > Fields.
The following Field records should now be in place for your CreateIncidentInbound messsage:
Click on Build Message.
You will see the 'Message build successful' Info Message.
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:
Before we test, let's take a quick look at running Build at the Integration level.
We will need to configure messages to process and respond to the data returned from the poll.
In order to process and respond to the data that is returned from the remote system, we will need to create the appropriate Messages in Unifi. To satisfy the requirements of this Guide, we will need to configure the following Messages:
CreateIncidentInboundReceipt
CreateIncidentInbound
We shall look in detail at how to configure each of those Messages and the appropriate Fields to configure the Message Scripts over the next few pages.
Let's begin by configuring the CreateIncidentInboundReceipt Message.
| 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 |
|---|---|---|
| Field | Description | Value |
|---|---|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
For a full description of the available Field Maps, please see the relevant page in our .
| Incident Field | Field Map |
|---|
| Field | Description | Value |
|---|
For more information on Field Inheritance click .
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
| Field | Description | Value |
|---|
The code we had previously added when configuring our Message on the '' page is still in place and can be seen after the End Comment.
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
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>
Response
The immediate synchronous response to this message.
lookup: 'Response'
Path*
A path to append to the URL defined in the connection. Specify a full URL to override the connection. Define inline scripts to reference Stage to Request script variables by wrapping code in braces {}, e.g. /{transaction.message_id}.
'/table/incident/{bond.getValue("external_reference")}'
Action method
The SOAP Action or the REST Method to use for this message. If this field is empty the SOAP Action will default to the message name and the REST Method will default to POST.
'PUT'
Caller
Person who reported or is affected by this incident.
<Your Caller>
Impact
Measure of the business criticality of the affected service.
<Your Impact>
Urgency
The extent to which resolution of an incident can bear delay.
<Your Urgency>
Assignment group*
The group to which the ticket is assigned.
<Your Assignment group>
Short description
A brief description of the incident.
<Your Short description>
Description
Detailed explanation on the incident.
<Your Description>
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>
Response | The immediate synchronous response to this message. | lookup: 'Response' |
Async* | Turn this option on if you want inbound processing to occur asynchronously or this message is the first of an asynchronous message pair. | <true> |
Async receipt | The asynchronous receipt to this message. Leaving this blank will cause the message to be processed async without sending a receipt. | lookup: 'CreateIncidentInboundReceipt' |
Bond ownership* | Determine if the sender should own the bond or not in order for this message to be processed? Use 'Ignore' to process regardless of the owner flag. (Choices: Ignore, Must own, Must not own.) | 'Ignore' |
Bond condition type* | The type of conditional check made on the bond. (None: no checks are made. State: checks against the state are made using the conditional checkboxes. Scripted: the 'Bond condition' script is used.) | 'State' |
Bond new | Process this message when a new bond is required. | <true> |
Set bond state inbound* | Set the Bond State when receiving this message. Use 'None' to leave the Bond State alone or to modify it via a Message/Field Stage to Target script. | 'Open' |
Bond reference method* | Method of searching for and validating an existing bond for incoming messages. | 'External' |
Reference lookup script | The script containing functions for extracting internal and external references from the request payload. | Update the code in the Reference lookup script field so that it looks like the code below |
Name* | The name of your field map. (If left unedited, it will append the word 'Copy' to the existing name.) | <Your Name> |
caller_id | 'PI - Reference'* |
short_description | 'PI - String'* |
description | 'PI - String'* |
state | 'PI - Choice'* |
impact | 'PI - Choice'* |
urgency | 'PI - Choice'* |
Message* | The Message this Field record is linked with. | 'CreateIncidentInbound' |
Description | Describe what this field is for and any specific details that might help you in future. | 'The caller on this incident. Used for inbound messages from the table API.' |
Active* | Set to true to use this Field record for processing. | <true> |
Field map | The Field Map this Field record is linked with. | 'PI - Reference'** |
Map to field* | Use this Field record to represent a field on a source/target table. | <true> |
Table* | The primary source/target table that this Field record is mapped to. | 'Incident '[incident] |
Element | The field on the source/target table this Field record is mapped to. | 'Caller' |
Path | Where in the payload the data will be placed. | ‘detail’ |
Property* | The property in the payload the data will be written to. | Automatically populated |
Inbound* | Set to true to use for inbound Messages. | <true> |
Outbound* | Set to true to use for outbound Messages. | <false> |
Default inbound | Generate a default value that can be used when an inbound request does not contain a value for this field. | Update the Default inbound script field so that it looks like the code below |
Path | Where in the payload the data will be placed. | ‘detail’ |
Inbound | Set to true to use for inbound Messages. | <true> |
Outbound | Set to true to use for outbound Messages. | <false> |
Path | Where in the payload the data will be placed. | ‘detail’ |
Inbound | Set to true to use for inbound Messages. | <true> |
Outbound | Set to true to use for outbound Messages. | <false> |
Message* | The Message this Field record is linked with. | 'CreateIncidentInbound' |
Description | Describe what this field is for and any specific details that might help you in future. | 'The impact of the incident.' |
Active* | Set to true to use this Field record for processing. | <true> |
Field map | The Field Map this Field record is linked with. | 'PI - Choice'** |
Map to field* | Use this Field record to represent a field on a source/target table. | <true> |
Table* | The primary source/target table that this Field record is mapped to. | 'Incident' [incident] |
Element | The field on the source/target table this Field record is mapped to. | 'Impact' |
Path | Where in the payload the data will be placed. | 'detail' |
Property* | The property in the payload the data will be written to. | Automatically populated |
Inbound* | Set to true to use for inbound Messages. | <true> |
Outbound* | Set to true to use for outbound Messages. | <false> |
Element | The field on the source/target table this Field record is mapped to. | 'Urgency' |
Property* | The property in the payload the data will be written to. | Automatically populated |
Description | Describe what this field is for and any specific details that might help you in future. | 'The urgency of the incident.' |
Name
The name of the Processor.
<Your Name>
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>
Message name
The message name that is unique for this integration.
'CreateIncidentInboundReceipt'
Type
The primary purpose of the message.
'Receipt'
Direction
The directions(s) this message is configured to support.
'Outbound'
Description
The description for this message and the requirement is is meeting.
<Your description>
Message name | The message name that is unique for this integration. | 'CreateIncidentInbound' |
Type | The primary purpose of the message. | 'Create' |
Direction | The direction(s) this message is configured to support. | 'Inbound' |
Description | The description for this message and the requirement it is meeting. | <Your description> |
