UpdateIncident Fields

We will utilise the Field & Field Map records to configure the Message Scripts for the UpdateIncident Message.

Field: incident.short_description

The 'incident.short_desccription' (Integration level) Field record should already be in place (i.e. with Active set to false). Creating the Message level counterpart is now easier than ever.

From the UpdateIncident page, navigate to Message > Fields.

Find the incident.short_description (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).

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

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, if a Field is required for multiple Messages, create it once for the first Message and then simply set active to true for its Integration level counterpart from the Fields list of each of the relevant Messages that Field is required on.

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.

Incident Field	Field Map
comments	'PI - String'*
work_notes	'PI - String'*

We have chosen String type here because we are integrating with the table API. This will return the contents of those fields as a string value. If we were integrating Unifi to Unifi we may use a Journal field type which would return an array of comments objects with "text", "created_on", "created_by" & "published" elements.

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

Field	Description	Value
Element	The field on the source/target table this Field record is mapped to.	Additional comments
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 incident's comments'

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

Field	Description	Value
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
Description	Describe what this field is for and any specific details that might help you in future.	'The incident's work notes'

*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

The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that may already be there (pre-existing code will be retained).

//===== [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.