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:
1) 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.
2) Click on Build Message.
You will see the 'Message build successful' Info Message.
3) 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.
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:
Your CreateIncidentInbound New Message modal should look like this:
5) 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:
8) Navigate to Message > Bond.
The Bond fields to be configured are as follows:
*These fields are automatically populated.
Your Bond form should look like this:
10) 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:
12) Navigate to Advanced > Script Editor.
As well as being the place where Bond state & ownership are set, the Scripts are where the request processing and data mapping occurs.
Click on View > Inbound.
The Script Editor fields to be configured are as follows:
In the current release, there is no OOTB Field Map record with which we can set the state on the Bond. We shall, therefore, script that manually. For more information , see the `Fields` & `Field Maps` pages in our technical documentation.
The code in the 'Stage to Target' script field should look like this:
Your Script Editor fields should look like this:
14) Click Save.
15) Close the Script Editor to navigate back to the Message.
We are now ready to configure the Fields for our CreateIncidentInbound Message.
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:
Your CreateIncidentInboundReceipt New Message modal should look like this:
5) 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:
7) Navigate to Outbound > Settings.
The Outbound Settings fields to be configured are as follows:
Your Outbound Settings form should look like this:
10) Click Save.
We are now ready to configure the Fields for our CreateIncidentInboundReceipt Message.
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.
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.
1) 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:
3) 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:
1) 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).
For a full description of the available Field Maps, please see the relevant page in our technical documentation.
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:
7) Click Submit and view to further configure the Field record.
The incident.caller_id Field record opens to the Details page.
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).
Navigate to Field > Defaults.
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:
9) 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:
10) Find the incident.short_description (Integration level) Field & set Active to true.
11) 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.
Navigate to Field > Settings.
Edit the incident.short_description Field record as follows:
Your incident.short_description Field record should look like this:
15) 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:
16) Find the incident.description (Integration level) Field & set Active to true.
17) Click to open the incident.description (Message level) Field to make a few minor changes.
The incident.description Field record opens to the Details page.
Navigate to Field > Settings.
Edit the incident.description Field record as follows:
Your 'incident.description' Field record should look like this:
21) Save the record.
If you had previously completed the Incident Update Poller Guide, then the Settings may already match because the Integration level Field record would have been updated when configuring the Fields for the UpdateIncidentinbound Message. Confirm that the settings match those 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.
To quickly navigate back to the CreateincidentInbound Message from the Details page of the incident.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:
22) Find the incident.state (Integration level) Field & set Active to true.
23) 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.
Navigate to Field > Settings.
Edit the incident.state Field record as follows:
Your 'incident.state' Field record should look like this:
27) 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:
33) 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.
34) 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.
35) Navigate to Field > Field Choices.
36) Click Generate field choices.
37) 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’ (IS - 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:
38) 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:
41) 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.
42) 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.
43) Navigate to Field > Field Choices.
44) Click Generate field choices.
45) 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:
46) Click on Build Message.
You will see the 'Message build successful' Info Message.
47) 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:
The code we had previously added when configuring our Message on the 'CreateIncidentInbound Message' page is still in place and can be seen after the End Comment.
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.
#
Field
Description
Value
6
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>
7
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'>
#
Field
Description
Value
*
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'
9
Bond new
Process this message when a new bond is required.
<true>
#
Field
Description
Value
*
Bond reference method
Method of searching for and validating an existing bond for incoming messages.
'External'
11
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
#
Field
Description
Value
13
Stage to Target (Inbound)
The script to run.
Replace the commented out instructions with the following code: bond.setOpen();
#
Field
Description
Value
6
Response
The immediate synchronous response to this message.
<lookup: 'Response'>
#
Field
Description
Value
8
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}.
'/{bond.getValue("external_reference")}'
9
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'
#
Field
Description
Value
2
Name*
The name of your field map. (If left unedited, it will append the word 'Copy' to the existing name.)
<Your Name>
Incident Field
Field Map
caller_id
'IS - Reference'*
short_description
'IS - String'*
description
'IS - String'*
state
'IS - Choice'*
impact
'IS - Choice'*
urgency
'IS - Choice'*
#
Field
Description
Value
*
Message
The Message this Field record is linked with.
'CreateIncidentInbound'
2
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>
3
Field map
The Field Map this Field record is linked with.
'IS - 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]
4
Element
The field on the source/target table this Field record is mapped to.
'Caller'
5
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>
6*
Outbound
Set to true to use for outbound Messages.
<false>
#
Field
Description
Value
8
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
#
Field
Description
Value
12
Path
Where in the payload the data will be placed.
‘detail’
13
Inbound
Set to true to use for inbound Messages.
<true>
14
Outbound
Set to true to use for outbound Messages.
<false>
#
Field
Description
Value
18
Path
Where in the payload the data will be placed.
‘detail’
19
Inbound
Set to true to use for inbound Messages.
<true>
20
Outbound
Set to true to use for outbound Messages.
<false>
#
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>
#
Field
Description
Value
*
Message
The Message this Field record is linked with.
'CreateIncidentInbound'
28
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>
29
Field map
The Field Map this Field record is linked with.
'IS - 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]
30
Element
The field on the source/target table this Field record is mapped to.
'Impact'
31
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>
32*
Outbound
Set to true to use for outbound Messages.
<false>
#
Field
Description
Value
39
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
40
Description
Describe what this field is for and any specific details that might help you in future.
'The urgency of the incident.'
#
Field
Description
Value
1
Message name
The message name that is unique for this integration.
'CreateIncidentInbound'
2
Type
The primary purpose of the message.
'Create'
3
Direction
The direction(s) this message is configured to support.
'Inbound'
4
Description
The description for this message and the requirement it is meeting.
<Your description>
#
Field
Description
Value
1
Message name
The message name that is unique for this integration.
'CreateIncidentInboundReceipt'
2
Type
The primary purpose of the message.
'Receipt'
3
Direction
The direction(s) this message is configured to support.
'Outbound'
4
Description
The description for this message and the requirement it is meeting.
<Your description>
