Field Maps

Definition

A Field Map defines the template code used by a Field in the various Message Scripts. It has a template script field for each of the Message Script types (Source to Stage, Stage to Request, Payload to Stage, Stage to Target). The template scripts are compiled during the Build activity where details of a Field record are substituted into the template, producing a Message Script specific to the Message and Field.

The Field Map defines the behaviour, or ‘type’ of a Field. Below is a table of the Field Maps packaged with Unifi:

Field Choice

As stated above, Field Choice is strictly a ‘type’ of Field defined by a Field Map. However, it is worth going into a little more detail here. A Field Choice record represents the mapping of an internal value to/from an external value and a set of Field Choice records can be defined for an Integration level Field.

• Internal values are used and stored by the source and target records.

• External values are carried in the payload and exchanged between integrated systems.

Configuration

If, for example, you wanted to map the Description field as part of the CreateIncident Message, you would only need to configure the incident.description Field (see previous page) and allocate it the String ‘type’ Field Map. There would be no need to configure the Field Map record. This would be the case in the majority of instances, using the shipped Field Maps for standard integrations.

If, however, you had a custom requirement to manipulate or transform data in some unique way, then a custom Field Map can be created.

Best Practice

Best practice is to only use Field Maps that belong to an Integration. You can do this by copying the OOTB Field Maps which are shipped with Unifi and labelling them as belonging to a particular Integration. This should be done for each Integration. That way any future updates which may be made to any of the OOTB Field Maps will not impact any of your Integrations and each Integration will comprise its own stack of self-contained records.

Example

In this example we will copy the OOTB String Field and rename it to be used for the Incident Guide Integration.

To copy the String Field Map, navigate to the Field Maps page.

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

On the Copy Field Map modal, update the Name and Integration as appropriate & click Copy.

Code in Action

The following is an example of a Source to Stage Message Script template from the String Field Map. The code between the dollar braces, e.g. $[field.element], is executed as JavaScript during the compile phase. The field variable is the Field GlideRecord object.

// Determines whether this instance of the field map is for a mandatory field
var is_mandatory = $[field.mandatory];

if (is_mandatory) {
  $stage.$[field.element] = '' + source.$[field.element];
} else if (source.$[field.element] != '') {
  $stage.$[field.element] = '' + source.$[field.element];
}

if (default_value) {
  $stage.$[field.element] = default_value;
}

The following block of code is extracted from The Source to Stage Message Script belonging to a CreateIncident Message which was generated using the above String Field Map template against the incident.description Field:

x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=24347d2cdbdd3340957ddd3b5e961917]", function () {
  log.debug("Field map: String [x_snd_eb_field_map.do?sys_id=4719793adb58b700957ddd3b5e961974]");

  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 = '' + (source.description || default_value);
  } else if (source.description != '') {
    $stage.description = '' + source.description;
  }

});

Integration Phases

To help you understand and give some context as to where these configuration records fit, we thought it would be helpful to layout the phases of an Integration as we see them.

Configuration Phase

• Field records are configured and linked to Messages (and/or Integrations) and Field Maps.

• Field Maps can be edited or created as needed.

• Field Choice records are added/edited as needed.

Build Phase

• The configurations defined by Fields and Field Maps are compiled into executable code and stored in Message Scripts. Existing Message Scripts simply have their code updated. Code outside of the demarkation comments in the Message Scripts is retained.

Operational Phase

• Messages and Message Scripts (and Field Choices) are interpreted and executed.

• Operational records such as Bonds, Stages, Transactions and Requests are generated and maintained.