Field: incident.short_description

From the UpdateIncident page, navigate to Message > Fields.

Find the incident.short_description (Integration level) Field & set Active to true.

By simply setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart. The Integration level record still exists (and can be seen when you click on the 'Fields' icon to navigate to the Fields page), but is no longer visible in the list view on the Message because the Message level record has been created.)

We will now configure Field records for two other Incident record field elements.

Fields & Field Maps

The table below lists the Incident fields above and the relevant Field Maps required to configure each Field record.

*Field map: Values may vary (dependent on your configuration of the copies). Choose the copy Field Maps you created earlier.

Field: incident.comments

Because the incident.comments Field record is the same 'type' (IS - String) & the majority of the settings are the same as the previously configured Field, it will be quicker to copy the incident.short_description Field & make a few minor changes.

Click the ellipsis next to the incident.short_description 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:

Click Copy.

You will be redirected to the Details page of the newly created incident.comments Field record.

Field: incident.work_notes

It will again be quicker to copy the previously configured incident.comments Field & make a few minor changes.

To quickly navigate back to the UpdateIncident Message, click the 'Preview' icon next to the Message field on the Details page of newly created incident.comments Field record.

Navigate to Message > Fields.

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:

Click Copy.

You will be redirected to the Details page of newly created incident.work_notes Field record.

Build

Now that we’ve configured the Field records for the UpdateIncident message, we are ready to build our message scripts.

Navigate to the UpdateIncident Message, then navigate to Message > Fields.

The following Field records should now be in place for your UpdateIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

We will now examine our new, auto-generated Message Scripts.

Source to Stage:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=a70b854b1b15b81090dfdb9ebd4bcbb2]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.short_description = '' + (source.short_description || default_value);
  } else if (source.short_description != '') {
    $stage.short_description = '' + source.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.comments [x_snd_eb_field.do?sys_id=1a5efe331b953c1090dfdb9ebd4bcbfc]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.comments = '' + (source.comments || default_value);
  } else if (source.comments != '') {
    $stage.comments = '' + source.comments;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.work_notes [x_snd_eb_field.do?sys_id=99ffb6371b953c1090dfdb9ebd4bcb22]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.work_notes = '' + (source.work_notes || default_value);
  } else if (source.work_notes != '') {
    $stage.work_notes = '' + source.work_notes;
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Stage to Request:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=a70b854b1b15b81090dfdb9ebd4bcbb2]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.short_description = '' + $stage.short_description;
  } else if ($stage.short_description) {
    $payload.short_description = '' + $stage.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.comments [x_snd_eb_field.do?sys_id=1a5efe331b953c1090dfdb9ebd4bcbfc]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.comments = '' + $stage.comments;
  } else if ($stage.comments) {
    $payload.comments = '' + $stage.comments;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.work_notes [x_snd_eb_field.do?sys_id=99ffb6371b953c1090dfdb9ebd4bcb22]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.work_notes = '' + $stage.work_notes;
  } else if ($stage.work_notes) {
    $payload.work_notes = '' + $stage.work_notes;
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

We are now ready to Test the UpdateIncident Message.

As previous, after clicking the 'Messages' icon, you will see the following screen (note: both the previously configured messages are now visible in the list):

Click New.

New Message Modal

The fields to be configured for the Response New Message modal are as follows:

Your Response New Message modal should look like this:

Click Submit.

You will be redirected to the Messages page. You need not configure the Response Message any further.

Now it's time to move on and configure the UpdateIncident Message.

After submitting the 'Response' Message, you were redirected to the Messages page (note: the three previously configured messages are now visible in the list):

Click New.

New Message Modal

The fields to be configured for the UpdateIncident New Message modal are as follows:

Your UpdateIncident New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

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.

Bond Fields

The Bond fields to be configured are as follows:

*These fields are automatically populated.

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger fields to be configured (as required)* are as follows:

Your Outbound Trigger form should look like this:

Navigate to Outbound > Settings.

Outbound Settings Fields

The Outbound Settings fields to be configured are as follows:

Your Outbound Settings form should look like this:

Click Save.

We are now ready to configure the Fields for our UpdateIncident Message.

Update The Incident

Navigate to < Your Incident > created in the previous test.

Your Incident record should look like this:

Enter < Your Work notes > in the 'Work notes' field.

Click Post.

The following activities are added to the 'Notes' tab (confirming sending the UpdateIncident Message to your integration):

View the Bond

Click through to the Bond record from the related list on the Incident.

Your Bond record should have been updated as follows:

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)

View the Transaction

Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

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)

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)

Stage:

• Direction: 'Outbound'

• Message: 'UpdateIncident'

• Internal reference: < ServiceNow ticket reference > (Same as 'Document')

• External reference: < External system's ticket reference >

View the Stage

Click through to the Stage record from the related list on the Transaction.

Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage details:

• Direction: 'Outbound'

• External reference: < External system's ticket reference >

• Internal reference: < ServiceNow ticket reference >

• Snapshot: < Snapshot record reference >

• Message: 'UpdateIncident'

• Transaction: < Your Transaction >

• Integration: < Your Integration >

Mapped Staged Data fields:

• Work notes: < Your Work note >

View the HTTP Request

Click through to the HTTP Request record from the related list on the Transaction.

Your HTTP Request record should look like this:

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: 'PUT'

• Request headers: < The header of the request being sent >

• Request payload: < The payload of the request being sent >

Response details:

• Status code: '200'

• Response headers: < The header of the response being received >

• Response payload: < The payload of the response being received >

Compare with the External System's Incident

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):

Activities: < Your Work note > (added by < your.external.system.user >)

Challenge

• Repeat the steps above - this time placing a check in the 'Additional comments (Customer visible)' checkbox.

• What do you expect to happen?

The Messages we shall be configuring for the Update Scenario are:

1. Response

2. 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.