We will utilise the Field & Field Map records to configure the Message Scripts for the UpdateIncident Message.
The 'message_header' (Integration level) Field record should already be in place (i.e. with Active set to false). We will now create its Message level counterpart.
From the UpdateIncident Message, navigate to Message > Fields.
Your UpdateIncident Fields page should look like this:
1) Find the message.message_header (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). Note: the empty 'circle icon' indicates that the Integration level Field is available to add to the Message.
As before, 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.
Next, repeat the process for the incident.short_description Field.
The 'incident.short_desccription' (Integration level) Field record should already be in place (i.e. with Active set to false). We will now create its Message level counterpart.
Your UpdateIncident Fields page should look like this:
2) Find the incident.short_description (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).
We will now configure Field records for two other Incident record field elements.
As with the CreateIncident Message and depending on your requirements, you will need to create Field records for each of the relevant Incident record field elements (see the table in Fields & Field Maps on the 'CreateIncident Fields' page for an example). For the sake of brevity, this Guide will focus on two of those. If you wish, however, you are free to configure other Field records as required.
The table below lists the Incident record field elements we will map and the relevant Field Maps required to configure each Field record.
If you haven't already, you will need to copy the relevant additional Field Maps for the UpdateIncident Field records as follows:
Journal field
See Copy Field Maps (on the 'CreateIncidentReceipt Fields' page) for details.
From the UpdateIncident Message, navigaate to Message > Fields & click New.
The fields to be configured for our incident.comments 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.comments' New Field modal should look like this:
7) Submit the record.
You will be redirected back to the Fields page of the UpdateIncident Message.
Because the incident.work_notes Field record is the same 'type' (IG Journal field) & the majority of the settings are the same as the previously configured Field, it will be quicker to copy the incident.comments Field & make a few minor changes.
8) Click the ellipsis next to the incident.comments Field record & click Copy.
The fields to edit for the Copy Field modal are as follows:
*This field is automatically populated.
Your Copy Field modal should look like this:
11) Click Copy.
You will be redirected to the Details page of the newly created incident.work_notes Field record.
Now that we’ve configured the Field records for the UpdateIncident message, we are ready to build our message scripts.
To quickly navigate to the UpdateIncident Message from the Details page of the newly created incident.work_notes Field record…
...click the 'Preview' icon to the left of the Message field.
From the UpdateIncident message, navigate to Message > Fields.
The following Field records should now be in place for your UpdateIncident messsage:
12) Click on Build Message.
You will see the 'Message build successful' Info Message.
13) Navigate to Advanced > Script Editor to view the auto-generated code.
Your Script Editor fields should look like this:
The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that was already there.
We are now ready to Test our UpdateIncident Message.
Follow these steps to test the UpdateIncident Message.
Navigate to < Your Incident > created in the previous test.
Your Incident record should look like this:
1) Enter < Your Work notes > in the 'Work notes' field.
2) Click Post.
You should see an Info Message, confirming the UpdateIncident Message is being sent to your Integration:
The Work note is added to the Activities stream on the 'Notes' tab:
Click through to the Bond record from the related list on the Incident.
Your Bond record should have been updated as follows:
3) History:
< History updated on the Bond > (Sending UpdateIncident...)
4) Transaction:
Message: 'Updateincident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)
Click through to the Transaction record from the related list on the Bond.
Your Transaction record should look like this:
5) Transaction details:
Table: 'Incident [incident]'
Document: < Your Incident >
Integration: < Your Integration >
Connection: < Your Connection >
Bond: < Your Bond >
Message: 'UpdateIncident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)
6) Errors:
Error: (If there was a transactional error the Transaction state would show as 'Error' and the details would be captured here).
Process error: (If there was a process error the Process state would show as 'Rejected' and the details would be captured here)
7) Stages:
Direction: 'Outbound' & 'Inbound'
Message: 'UpdateIncident' & 'Receipt'
Internal reference: < ServiceNow ticket reference > (Same as 'Document')
External reference: < External system's ticket reference >
Click through to the Outbound Stage record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound Stage record.)
Check the values in the fields match what you expect.
Your Stage record should look like this:
8) Stage details:
Direction: 'Outbound'
External reference: < External system's ticket reference >
Internal reference: < ServiceNow ticket reference >
Message: 'UpdateIncident'
Transaction: < Your Transaction >
Integration: < Your Integration >
9) Mapped stage fields:
work_notes: < Your Work note >
Click through to the Outbound HTTP Request record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound HTTP Request record.)
Your HTTP Request record should look like this:
10) HTTP Request details:
Integration: < Your Integration >
Connection: < Your Connection >
Transaction: < Your Transaction >
Message: 'UpdateIncident'
Direction: 'Outbound'
Request state: 'OK' (There are no errors with the HTTP Request.)
Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the Integration.)
Endpoint URL: < The external system’s access URL >
Action Method: 'POST'
Request headers: < The header of the request being sent >
Request payload: < The payload of the request being sent >
11) Response details:
Status code: '200'
Response headers: < The header of the response being received >
Response payload: < The payload of the response being received >
Navigate to the corresponding Incident in the external system.
Check the values in the fields match those you noted when you saved the Incident in the internal system.
Your external system's Incident record should look like this (depending on the system you're integrating with, your record may look different; the important matter is that the values match):
12) Activities: < Your Work note > (added by < your.external.system.user >)
Repeat the steps above - this time placing a check in the 'Additional comments (Customer visible)' checkbox.
What do you expect to happen?
As when testing our CreateIncident Message, if completing this test after having integrated with the external system (as opposed to connecting to your own instance), it would be good to test the UpdateIncident Message in both directions.
We are now ready to move to the Resolve Scenario.
The Receipt Message is the asynchronous receipt that is sent after processing update type messages.
Again, after clicking the 'Messages' icon, you are directed to the following screen (note: the three previously configured messages are now visible in the list):
1) Click on the ellipsis to the right of the CreateIncidentReceipt Message & click Copy.
Rather than create the Receipt Message from scratch, it will be quicker to copy the CreateIncidentReceipt Message and make one minor change.
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 Receipt Message.
Navigate to Advanced > Script Editor, then View > Inbound.
Your Script Editor fields should initially look like this:
The Script Editor fields to be edited are as follows:
The code in the 'Stage to Target' script field should look like this:
Your Script Editor fields should now look like this:
5) Click Save.
6) Click Build Message.
You will see the 'Message build successful' Info Message.
7) Click the 'Messages' icon to move on & configure the UpdateIncident Message.
There is no further configuration required for the Receipt Message.
For each of our Scenarios we will need to configure the relevant Messages & Fields. This scenario will need to be tested before moving on to the next.
The Messages we shall be configuring for our Update Scenario are:
Receipt
UpdateIncident
We will define which Field records require configuring for each of those Messages at the appropriate time.
The scenario will need to be successfully tested before we can say it is complete.
We shall look in detail at each of the Messages and their respective Fields in turn over the next few pages, before moving on to Test.
The UpdateIncident Message is an update type message that sends updates to the bonded record.
Again, after clicking the 'Messages' icon, you are directed to the following screen (note: the four previously configured messages are now visible in the list):
1) Click New.
The fields to be configured for the UpdateIncident New Message modal are as follows:
Your UpdateIncident New Message modal should look like this:
5) 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:
11) Navigate to Outbound > Trigger.
The Outbound Trigger fields to be configured (as required)* are as follows:
*Outbound condition (as required):
It is not necessary for you to enter a condition. The value given is an example. You may create any condition (or not) to align with your business process requirements. In this case it makes sense to use this message to send an update where the state doesn't change. Typically, we would configure different messages to align with state changes (e.g. Close, Resolve).
The code in the 'Outbound condition' script field should look like this:
Your Outbound Trigger form should look like this:
13) Navigate to Inbound > Settings.
The Inbound Settings fields to be configured are as follows:
*Bond reference method:
Internal - lookup using the internal reference only.
External - lookup using the external reference only.
Both - lookup using both the internal and external references.
As mentioned earlier, because this is an update type message, we use 'Both' as it's a more accurate method of validating updates are being sent to/received from the correct bonded records.
The code in the 'Reference lookup script' field should look like this:
Your Inbound Settings form should look like this:
16) Click Save.
We are now ready to configure the Fields for our UpdateIncident Message.
Incident Field
Field Map
comments
Journal field
work_notes
Journal field
#
Field
Description
Value
*
Message
The Message this Field record is linked with.
'UpdateIncident'
3
Description
Describe what this field is for and any specific details that might help you in future.
'The incident's comments'
*
Active
Set to true to use this Field record for processing.
<true>
4
Field map
The Field Map this Field record is linked with.
'IG Journal field'**
*
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]
5
Element
The field on the source/target table this Field record is mapped to.
'Additional comments'
6
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.
<true>
#
Field
Description
Value
9
Element
The field on the source/target table this Field record is mapped to.
'Work notes'
*
Property
The property in the payload the data will be written to.
Automatically populated
10
Description
Describe what this field is for and any specific details that might help you in future.
'The incident's work notes'
# | Field | Description | Value |
2 | Message name | The message name that is unique for this integration. | 'Receipt' |
# | Field | Description | Value |
4 | Stage to Target (Inbound) | The script to run. | Delete the following code that sits outside of the End tag: bond.setOpen(); |
# | Field | Description | Value |