Field Maps define template code into which details from Field records are substituted. The resulting blocks of code are wrapped and compiled together into their nominated Message Scripts.

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 some of the Field Maps packaged with Unifi:

Name Definition
Boolean Standard Field Map for Boolean values.
Choice Use this to perform the value mapping between the internal & external values.
Date Standard Field Map for Date values.
DateTime Convert a GlideDateTime to and from an ISO 8601 date string.
Receipt Status This is used in receipt messages to send and process the status data sent/received in a receipt. This is the transaction process error.
Reference Standard field map for reference values.
Requested Item This is a specialist Field Map which is used to map Requested Items.
Source ID Use this to extract and add the unique message identifier for THIS instance, i.e. your transaction ID
Source Reference Use this to extract and add the unique record identifier for THIS instance, i.e. your task number, user_id etc
String Standard Field Map for String values
Target ID Use this to extract and add the unique message identifier for THIER instance, i.e. the external message ID
Target Reference Use this to extract and add the unique record identifier for THIER instance, i.e. the other system so their task number, user_id etc
Time Standard Field Map for Time values.

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.

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