CreateIncidentInbound Fields

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

Copy Field Maps

It is worth copying all relevant OOTB Field Maps as are necessary for your integration before using any of them in your Field Records - thereby mitigating the risk of any potential issues with future upgrades

Some Field Maps should already have been copied for this Integration whilst following the Outbound Incident Guide and the previous two Poller Guides. There is one more that will need to be copied. The remaining Field Map we shall use for our CreateIncidentInbound Field record is:

  • Reference

To copy the Reference Field Map, navigate to the 'Field Maps' icon.

Click on the ellipsis to the right of the Reference Field Map & then click Copy.

Copy Field Map Modal

The fields to edit for the Copy Field Map modal are as follows:

Field
Description
Value

Name*

The name of your field map. (If left unedited, it will append the word 'Copy' to the existing name.)

<Your Name>

Your Copy Field Map modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created Field Map.

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). We will begin by configuring a Field record to deal with the transaction specific data.

Field: message.header

The ‘message.header’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Incident Update Poller Guide. We will now create its Message level counterpart.

From the CreateIncidentInbound Message, navigate to Message > Fields.

Your CreateIncidentInbound Fields page should look like this:

Find the message.header (Integration level) Field & set Active to true.

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. There is no need to edit the settings any further for this Message level Field as the ones copied from the Integration level record already match our requirements.

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 only chosen to include the caller_id, short_description, description, state, impact & urgency elements in both the Setup script & Response script of the Poll Processor, this Guide will focus on those six. 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

caller_id

'PI - Reference'*

short_description

'PI - String'*

description

'PI - String'*

state

'PI - Choice'*

impact

'PI - Choice'*

urgency

'PI - Choice'*

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

Field: incident.caller_id

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

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

Field
Description
Value

Message*

The Message this Field record is linked with.

'CreateIncidentInbound'

Description

Describe what this field is for and any specific details that might help you in future.

'The caller on this incident. Used for inbound messages from the table API.'

Active*

Set to true to use this Field record for processing.

<true>

Field map

The Field Map this Field record is linked with.

'PI - Reference'**

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'

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.

<false>

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

Click Submit and view to further configure the Field record.

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

To edit, set Inherit to False.

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.

Navigate to Field > Defaults.

Defaults

Returning data from reference fields poses some challenges. When dealing with referential data, values in each system would need to match (this would apply whether we were receiving actual or display values). The ways of dealing with that fall outside of the scope and purpose of this Guide.

We have configured the endpoint so that the table API is returning the display_value element for reference data objects. This means that we can set a default value to ensure that the Caller field on the Incident is populated with a meaningful value should it not find a matching record (instead of throwing a process error).

The fields to be configured for the Defaults page are as follows:

Field
Description
Value

Default inbound

Generate a default value that can be used when an inbound request does not contain a value for this field.

Update the Default inbound script field so that it looks like the code below

The code in the 'Default inbound' script field should look like this:

var default_value = (function () {
  return gs.getUserID();
})();

Your Defaults page should look like this:

Save the record.

Field: incident.short_description

The ‘incident.short_description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.

To quickly navigate back to the CreateIncidentInbound Message, from the Details page of the incident.caller_id Field record...

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

From the CreateIncidentInbound Message, navigate to Message > Fields.

Your CreateIncidentInbound Fields page should look like this:

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

Click to open the incident.short_description (Message level) Field to make a few minor changes.

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

To edit, set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.short_description Field record as follows:

Field
Description
Value

Path

Where in the payload the data will be placed.

‘detail’

Inbound

Set to true to use for inbound Messages.

<true>

Outbound

Set to true to use for outbound Messages.

<false>

Your incident.short_description Field record should look like this:

Save the record.

Field: incident.description

The ‘incident.description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.

To quickly navigate back to the CreateincidentInbound Message from the Details page of the incident.short_description Field record...

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

From the CreateIncidentInbound Message, navigate to Message > Fields.

Your CreateIncidentInbound Fields page should look like this:

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

There is no need to edit the settings any further for this Message level Field as the ones copied from the Integration level record already match our requirements.

Field: incident.state

The ‘incident.state’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we first created the Message level record when completing the Outbound Incident Guide. We will now create its Message level counterpart.

Your CreateIncidentInbound Fields page should look like this:

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

Click to open the incident.state (Message level) Field to make a few minor changes.

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

To edit, set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.state Field record as follows:

Field
Description
Value

Path

Where in the payload the data will be placed.

‘detail’

Inbound

Set to true to use for inbound Messages.

<true>

Outbound

Set to true to use for outbound Messages.

<false>

Your 'incident.state' Field record should look like this:

Save the record.

Field: incident.impact (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.

As with 'incident.state' the 'incident.impact' 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). We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

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

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

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

The fields to be configured for the incident.impact (Message level) New Field modal are as follows:

Field
Description
Value

Message*

The Message this Field record is linked with.

'CreateIncidentInbound'

Description

Describe what this field is for and any specific details that might help you in future.

'The impact of the 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 - 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.

'Impact'

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.

<false>

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

Submit the record.

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

Field: incident.impact (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.impact (Integration level) Field record (the one where Message is empty).

The incident.impact 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.

Field: incident.urgency (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.

Navigate back to the CreateIncidentInbound Message, then navigate to Message > Fields.

Your CreateIncidentInbound Fields page should look like this:

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

'Urgency'

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 urgency of the incident.'

*This field is automatically populated.

Your 'incident.urgency' Copy Field modal should look like this:

Click Copy.

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

Field: incident.urgency (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.urgency (Integration level) Field record (the one where Message is empty).

The incident.urgency 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.

Build

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

Navigate back to the CreateIncidentInbound Message, then navigate to Message > Fields.

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

Click on Build Message.

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

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=28a49cf2dbfdbc501831aab35b9619d1]", 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.caller_id [x_snd_eb_field.do?sys_id=6f6260bedbfdbc501831aab35b961935]", function () {
  log.debug("Field map: PI - Reference [x_snd_eb_field_map.do?sys_id=6cf2987edbbdbc501831aab35b9619d1]");
  payload = payload || {};
  payload.detail = payload.detail || {};
  var $payload = payload.detail;
  
  if (false && $payload.caller_id == undefined) {
    throw 'Mandatory field caller_id was not provided';
  } else {
    $stage.caller_id = $payload.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=3ede2cf2db31fc501831aab35b961918]", 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.short_description [x_snd_eb_field.do?sys_id=3669287edbfdbc501831aab35b9619ed]", 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.state [x_snd_eb_field.do?sys_id=48493c3adb31fc501831aab35b9619c5]", 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.impact [x_snd_eb_field.do?sys_id=765ff07adb31fc501831aab35b9619ea]", 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.impact == undefined) {
    throw 'Mandatory field impact was not provided';
  } else {
    $stage.impact = $payload.impact;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.urgency [x_snd_eb_field.do?sys_id=0947904bdb79fc501831aab35b96194d]", 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.urgency == undefined) {
    throw 'Mandatory field urgency was not provided';
  } else {
    $stage.urgency = $payload.urgency;
  }

});

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

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

Stage to Target:

The code we had previously added when configuring our Message on the 'CreateIncidentInbound Message' page is still in place and can be seen after the End Comment.

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.caller_id [x_snd_eb_field.do?sys_id=6f6260bedbfdbc501831aab35b961935]", function () {
  log.debug("Field map: PI - Reference [x_snd_eb_field_map.do?sys_id=6cf2987edbbdbc501831aab35b9619d1]");
  
  var default_value = (function () {
    return gs.getUserID();
  })();
  
  if (false && $stage.caller_id == undefined) {
    throw 'Mandatory field caller_id was not provided';
  } else {
    var table = target.caller_id.getReferenceTable(),
        ref,
        gr,
        value;
  
    value = $stage.caller_id.value || default_value;
  
    if (value != '') {
      gr = new GlideRecord(table);
      gr.addQuery('sys_id', '=', value);
      gr.query();
  
      if (gr.next()) {
        target.caller_id = gr.sys_id;
      } else {
        target.setDisplayValue("caller_id", $stage.caller_id.display_value);
        ref = target.caller_id.getRefRecord();
  
        if (!ref.isValidRecord()) {
          target.caller_id = ''; 
          throw 'Related record for field caller_id with value ' 
            + $stage.caller_id.display_value + ' not found.';
        }
      }
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=3ede2cf2db31fc501831aab35b961918]", 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.short_description [x_snd_eb_field.do?sys_id=3669287edbfdbc501831aab35b9619ed]", 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.state [x_snd_eb_field.do?sys_id=48493c3adb31fc501831aab35b9619c5]", 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.impact [x_snd_eb_field.do?sys_id=765ff07adb31fc501831aab35b9619ea]", 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.impact == undefined) {
    throw 'Mandatory field impact 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',        '=', 'impact');
    field_choice.addQuery('integration',    '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message',  '=', '');
    field_choice.addQuery('direction',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.impact);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.impact = field_choice.value;
    } else {
      target.impact = $stage.impact;
    }
  }

});


x_snd_eb.ws_console.execute("Mapping incident.urgency [x_snd_eb_field.do?sys_id=0947904bdb79fc501831aab35b96194d]", 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.urgency == undefined) {
    throw 'Mandatory field urgency 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',        '=', 'urgency');
    field_choice.addQuery('integration',    '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message',  '=', '');
    field_choice.addQuery('direction',      '=', 'Inbound');
    field_choice.addQuery('external_value', '=', $stage.urgency);
    field_choice.addQuery('active',         '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      target.urgency = field_choice.value;
    } else {
      target.urgency = $stage.urgency;
    }
  }

});

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

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

Before we test, let's take a quick look at running Build at the Integration level.

Was this helpful?