CreateIncident Fields

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

Fields & Field Maps

Depending on your requirements, you will need to create Field records for each of the relevant Incident record field elements (see the table below for an example). For the sake of brevity, this Guide will focus on a select few. If you wish, however, you are free to continue & configure the remaining Field records. The table below lists an example of the Incident record field elements you may wish to map and the relevant Field Maps required to configure each Field record. For a fuller definition of available Field Maps, please see the relevant page in our technical documentation.

Incident Field	Field Map
caller_id*	String
short_description	String
description	String
category	Choice
impact	Choice
urgency	Choice
state	Choice
comments	String
worknotes	String

*caller_id: we have chosen String type here because we are integrating with the table API. This will return the sys id of the caller as a string value. Note: If we were integrating Unifi to Unifi we may use a Reference type which would return the caller as an object with "value", "link" & "display_value" elements.

The Field records we will focus on will be for Caller (String), Short description (String) and State (Choice).

Copy Field Maps

If you haven't already, you will need to copy the relevant additional Field Maps for the CreateIncident Field records as follows:

• String

• Choice

See Copy Field Maps (on the 'CreateIncidentResponse Fields' page) for details.

Field: incident.caller_id

In Unifi Integration Designer, from the CreateIncident page, navigate to Message > Fields. Click New.

The fields to be configured for the 'incident.caller_id' New Field modal are as follows:

Field	Description	Value
Message*	The Message this Field record is linked with.	'CreateIncident'
Description	Describe what this field is for and any specific details that might help you in future.	'The caller on this incident'
Active*	Set to true to use this Field record for processing.	<true>
Field map	The Field Map this Field record is linked with.	'PI - String'**
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]
Element	The field on the source/target table this Field record is mapped to.	'Caller'
Property*	The property in the payload the data will be written to.	Automatically populated
Inbound*	Set to true to use for inbound Messages.	<false>
Outbound*	Set to true to use for outbound Messages.	<true>

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

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.short_description

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

Feature Alert: The 'result.sys_id' Field is visible and inactive. It is an integration level Field which was automatically created by Unifi at the time we created the Message level record (in CreateIncidentResponse Fields). We'll talk in more detail about this feature in the following section.

Click the ellipsis next to the incident.caller_id 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.	'Short description'
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 short description of this incident'

*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.short_description Field record.

The following info message is also displayed (which can be closed):

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). Uncheck the Inherit field to configure locally. For more information on Field Inheritance click here.

Field: incident.state

Field records can exist at both the Integration and the Message level (a Field record exists at the Integration level if it isn't linked to a Message i.e. the 'Message' field element is left blank). We noted previously that an Integration level Field record is automatically created when we create one at the Message level. We will utilise and configure both when mapping 'incident.state'.

The 'incident.state' 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) i.e. you're not going to have one set of choices/values for create and another for update.

Rather than configure choices for each Message, configure choices once at the Integration level. This means we only need define them once. The Field Map will take care of it and any 'incident.state' Field records that are set at the Message level (i.e. with a value in the 'Message' field) would use the choices configured at the Integration level.

We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

Field: incident.state (Message level)

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.

To quickly navigate to the CreateIncident Message from the Details page of the newly created incident.short_description Field record...

...click the 'Preview' icon to the left of the Message field.

From the CreatIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our 'incident.state' (Message level) New Field modal are as follows:

Field	Description	Value
Message*	The Message this Field record is linked with.	'CreateIncident'
Description	Describe what this field is for and any specific details that might help you in future.	'The incident lifecycle state'
Active*	Set to true to use this Field record for processing.	<true>
Field map	The Field Map this Field record is linked with.	'PI - 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]
Element	The field on the source/target table this Field record is mapped to.	'State'
Property*	The property in the payload the data will be written to.	Automatically populated
Inbound*	Set to true to use for inbound Messages.	<false>
Outbound*	Set to true to use for outbound Messages.	<true>

*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.state' (Message level) New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.state (Integration level)

We will need to 'Generate field choices' for this Integration level Choice 'type' Field.

Navigate to the 'Fields' icon to open the Fields page.

Click to open the incident.state (Integration level) Field record (the one where Message is empty).

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

Navigate to Field > Field Choices.

Click Generate field choices.

Click Generate on the 'Generate field choices' modal which displays.

The Field Choices are generated & now visible in the list.

At this stage, you could carry on and configure the remaining Field records for the rest of the Incident fields (as per the table at the top of this section). However, we will now run the Build process to auto-generate our Message Scripts.

Build

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

From the CreateIncident Message, navigate to Message > Fields.

The following Field records should now be in place for your CreateIncident 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.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", 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.caller_id = '' + (source.caller_id || default_value);
  } else if (source.caller_id != '') {
    $stage.caller_id = '' + source.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", 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.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var field_choice;
  var is_mandatory = false;  
  
  if (!source.state.nil()) {
    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',     '=', 'Outbound');
    field_choice.addQuery('value',         '=', source.state);
    field_choice.addQuery('active',        '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      $stage.state = '' + field_choice.external_value;
    }
  } 
  
  if (!$stage.state) {
    $stage.state = '' + (source.state || '');
  }
  
  if (is_mandatory) {
    $stage.state = '' + (source.state || '');
  }

});

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.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", 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.caller_id = '' + $stage.caller_id;
  } else if ($stage.caller_id) {
    $payload.caller_id = '' + $stage.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", 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.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  var $payload = payload;
  
  var is_mandatory = false;  
  
  if (is_mandatory) {
    $payload.state = $stage.state;
  } else if ($stage.state) {
    $payload.state = $stage.state;
  }

});

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 our CreateIncident Message.

Before we do, let's view the Trigger which Unifi automatically created when we ran 'Build Message'.