ResolveIncidentInbound Fields

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

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

The 'message.header', 'incident.description' and 'incident.short_description' Field records are already be in place because they were also copied when we copied the Message. We will now configure Field records for the remaining field elements we have chosen to map.

Fields & Field Maps

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 chosen to include the state, close_notes & close_code elements in both the Setup script & Response script of the Poll Processor, this Guide will focus on those three only. 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.

Incident Field	Field Map
state	'PI - Choice'*
close_notes	'PI - String'*
close_code	'PI - Choice'*

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

Field: incident.state (Message level)

Unifi created the incident.state (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. It is, therefore, displayed in the Fields list on the ResolveIncidentInbound Message with Active set to false.

From the ResolveIncidentInbound Message, navigate to Message > Fields.

Your ResolveIncident Message Fields page should look like this:

1) Find the incident.state (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) when we set Active to true. (The ‘Build Integration’ button became visible in the banner when we copied the UpdateIncidentInbound Message).

By simply setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has created the Message level counterpart.

2) Click to open the newly created incident.state (Message level) Field record for further editing.

The incident.state Field record opens to the Details page.

3) To edit, set Inherit to False.

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

For more information on Field Inheritance click here.

5) Navigate to Field > Settings.

The fields to be changed to configure the incident.state (Message level) Field record are as follows:

#	Field	Description	Value
6	Path	Where in the payload the data will be placed.	'detail'
7	Inbound	Set to true to use for inbound Messages.	<true>
8	Outbound	Set to true to use for outbound Messages.	<false>

Your incident.state (Message level) Settings form should look like this:

9) Save the record.

Field: incident.close_notes

As with incident.state, Unifi created the incident.close_notes (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. We will now create the Message level counterpart for the ResolveIncidentInbound Message.

To quickly navigate to the ResolveIncidentInbound Message from the Details page of the incident.state Field record...

...click the ‘Preview’ icon to the left of the Message field.

From the ResolveIncidentInbound Message, navigate to Message > Fields.

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

11) Click to open the newly created incident.close_notes (Message level) Field record for further editing.

The incident.close_notes Field record opens to the Details page.

12) To edit, set Inherit to False.

13) Save the record (the fields now become editable).

14) Navigate to Field > Settings.

The fields to be changed to configure the incident.close_notes (Message level) Field record are as follows:

#	Field	Description	Value
15	Path	Where in the payload the data will be placed.	'detail'
16	Inbound	Set to true to use for inbound Messages.	<true>
17	Outbound	Set to true to use for outbound Messages.	<false>
*	Mandatory	Set to true to make mandatory.	<true>

*Mandatory should already be set to true.

Your 'incident.close_notes' (Message level) Settings form should look like this:

18) Save the record.

Field: incident.close_code

Again, Unifi created the incident.close_code (Integration level) Field when we first created the Message level record whilst following the Outbound Incident Guide. We will also create the Message level counterpart for the ResolveIncidentInbound Message.

As with 'incident.state' the 'incident.close_code' Field record is a Choice 'type' Field. We have already configured the choices at the Integration level, so there's no need to 'Generate field choices' for this Message level record because the Field Map always looks for them on an Integration level Field which has the same name.

From the ResolveIncidentInbound Message, navigate to Message > Fields.

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

20) Click to open the newly created incident.close_code (Message level) Field record for further editing.

The incident.close_code Field record opens to the Details page.

21) To edit, set Inherit to False.

22) Save the record (the fields now become editable).

23) Navigate to Field > Settings.

The fields to be changed to configure the incident.close_code (Integration level) Field record are as follows:

#	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>
*	Mandatory	Set to true to make mandatory.	<true>

*Mandatory should already be set to true.

Your ‘incident.close_code’ (Message level) Field record should look like this:

27) Save the record.

Build

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

From the ResolveIncidentInbound message., navigate to Message > Fields.

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

28) Click on Build Message.

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

29) Navigate to Advanced > Script Editor > View > Inbound to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

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:

//===== [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 message.header [x_snd_eb_field.do?sys_id=0f7216b21be9f05090dfdb9ebd4bcb22]", function () {
  log.debug("Field map: PI - Message Header [x_snd_eb_field_map.do?sys_id=a225651c1ba57c1090dfdb9ebd4bcbeb]");
  payload = payload || {};
  payload.message = payload.message || {};
  var $payload = payload.message;
  
  // Messge identifiers
  $stage.$message_name = $payload.name;
  $stage.$time_stamp   = $payload.time_stamp;
  
  // Task references
  stage.internal_reference = $payload.target_reference || '';
  stage.external_reference = $payload.source_reference || '';
  
  // Transaction identifiers
  transaction.external_message_id = $payload.source_id || '';
  
  

});


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

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=0f7216b21be9f05090dfdb9ebd4bcb20]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory && $payload.description == undefined) {
    throw 'Mandatory field description was not provided';
  } else {
    $stage.description = $payload.description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=daba16b21be9f05090dfdb9ebd4bcb4e]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  var is_mandatory = false;  
  
  if (is_mandatory && $payload.state == undefined) {
    throw 'Mandatory field state was not provided';
  } else {
    $stage.state = $payload.state;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_code [x_snd_eb_field.do?sys_id=bdfa22be1be9f05090dfdb9ebd4bcb9b]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  var is_mandatory = true;  
  
  if (is_mandatory && $payload.close_code == undefined) {
    throw 'Mandatory field close_code was not provided';
  } else {
    $stage.close_code = $payload.close_code;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_notes [x_snd_eb_field.do?sys_id=c9532af61be9f05090dfdb9ebd4bcbb4]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = true;
  
  if (is_mandatory && $payload.close_notes == undefined) {
    throw 'Mandatory field close_notes was not provided';
  } else {
    $stage.close_notes = $payload.close_notes;
  }

});

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

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

Stage to Target:

Your Stage to Target Message Script should look like this:

//===== [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=077216b21be9f05090dfdb9ebd4bcb1c]", 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 == '') {
    throw 'Mandatory field short_description was not provided';
  } else {
    target.short_description = '' + ($stage.short_description || default_value);
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=0f7216b21be9f05090dfdb9ebd4bcb20]", 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.description == '') {
    throw 'Mandatory field description was not provided';
  } else {
    target.description = '' + ($stage.description || default_value);
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=daba16b21be9f05090dfdb9ebd4bcb4e]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var is_mandatory = false;  
  
  if (is_mandatory && $stage.state == undefined) {
    throw 'Mandatory field state was not provided';
  } else {
    var field_choice;
    
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',          '=', 'incident');
    field_choice.addQuery('element',        '=', 'state');
    field_choice.addQuery('integration',    '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message',  '=', '');
    field_choice.addQuery('direction',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.state);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.state = field_choice.value;
    } else {
      target.state = $stage.state;
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_code [x_snd_eb_field.do?sys_id=bdfa22be1be9f05090dfdb9ebd4bcb9b]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var is_mandatory = true;  
  
  if (is_mandatory && $stage.close_code == undefined) {
    throw 'Mandatory field close_code was not provided';
  } else {
    var field_choice;
    
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',          '=', 'incident');
    field_choice.addQuery('element',        '=', 'close_code');
    field_choice.addQuery('integration',    '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message',  '=', '');
    field_choice.addQuery('direction',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.close_code);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.close_code = field_choice.value;
    } else {
      target.close_code = $stage.close_code;
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.close_notes [x_snd_eb_field.do?sys_id=c9532af61be9f05090dfdb9ebd4bcbb4]", 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 = true;
  
  if (is_mandatory && $stage.close_notes == '') {
    throw 'Mandatory field close_notes was not provided';
  } else {
    target.close_notes = '' + ($stage.close_notes || default_value);
  }

});

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

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

Because we have already made a few changes to allow for inbound Message & Bond Identification in our earlier 'Incident Update Poller' Guide, we can now move on to Testing.