Field Maps

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

Name	Definition
Boolean	Map true/false values.
Choice	Perform value mapping between internal & external values.
Date	Map date values.
DateTime	Convert a GlideDateTime to and from an ISO 8601 date string.
Journal field	Transform journal fields into objects added to an array to handle multiple journal entry sending.
Message Header*	Compose or consume the message protocol header.
Message Name	Map message names.
Receipt Status	Send and process the status data sent/received in a receipt. This is the transaction process error.
Reference	Map reference values.
Requested Item	Map Requested Items.
Source ID	Extract and add the unique message identifier for THIS instance, i.e. your transaction ID.
Source Reference	Extract and add the unique record identifier for THIS instance, i.e. your task number, user_id etc.
String	Map String values
Target ID	Extract and add the unique message identifier for THEIR instance, i.e. the external message ID.
Target Reference	Extract and add the unique record identifier for THEIR instance, i.e. the other system so their task number, user_id etc.
Time	Map time values.
Unifi - SOAP Control	Scripts to control SOAP messages.

*Message Header consists of the following payload object:

message : { name : The message name time_stamp : The time the message was generated in the source system source_reference : The reference of the bonded task in the source system target_reference : The reference of the bonded task in the target system (not present in Create messages) source_id : The transactional identifier of this message target_id : The transactional identifier of the original request message (only present in Receipt messages) }

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.

*Name: We have chosen to prefix the existing Field Map Name with the initials of our Integration (you are free to choose any appropriate means of identifying/differentiating).

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.