Fields
Field and Field Map configuration records are elements that simplify and bring additional functionality when configuring Messages & Message Scripts and facilitate the auto-generation of documentation.
Field and Field Map configuration records are elements that simplify and bring additional functionality when configuring Messages & Message Scripts and facilitate the auto-generation of documentation.
Adding these elements to the Unifi configuration records brings a wealth of advantages. In the past, each Message Script has been maintained individually and manually. However, the introduction of Fields and Field Maps allows Message Scripts to be broken down into smaller, reusable components. Having these Field records also means we can easily view and manage the use of fields on Messages and Integrations.
A Field record defines the processing of a discrete component of a Message. Although the Field record is distinct from and separate to the field element of a form, it often represents the handling of an individual field on the source/target record (e.g. Short description). Not only that, a Field record is used to define the objects that will carry other Transaction specific data (e.g. Name, Time stamp, Source reference, Target reference).
A Field record identifies the field of a source/target record (optional - as stated above), the element used to stage the information and the property of the payload exchanged between systems. It can define the direction in which it is applied, any default values to use in each direction and whether it is mandatory. It can exist at the Integration or Message level (more on that in the Inheritance section). The behaviour, or ‘type’ of a Field is defined by the Field Map to which it is linked.
Field inheritance allows a Field record to be created at the Integration level rather than at an individual Message level. Individual, Message level Field records can then be configured to inherit their behaviour from the Integration level Field record.
For example, if a field is used by ten Messages, then we would define ten Field records and link them to the Messages (a separate Field record must be created for each of the Messages where the field is used). If we configure those Field records to inherit their behaviour from the Integration level Field record, then modifications made to the Integration level would immediately be available to the Message level Field records.
A Field record is shown to be an Integration level record when it is not linked to a specific Message i.e. the ‘Message’ field is left blank .
The ‘Integration’ field is mandatory for all Field records, meaning that a Field record must always be linked to an Integration.
A Message level Field record can inherit from its Integration level counterpart by simply checking the ‘Inherit’ field.
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.
The image below is an example of an ‘incident.short_description’ Field record:
We can see an example from this list view below that the incident.short_description Field record has been defined for seven different Messages on this Integration (plus the Integration level record):
When configuring a Field record, it is best practice to only link it with a Field Map that belongs to the same Integration as the Field (for details, see the Field Maps page).
As an aid to help identify any issues, in the auto-generated Documentation a warning triangle will appear next to the Field Map and a message will be shown in the Document if the Field Map doesn't belong to the Integration.
To maintain best practice when copying Field records from one Integration to another, if the value of the Integration changes on the Copy Field modal, Unifi automatically clears the value of the Field Map. This means you will need to populate this with the value of the equivalent Field Map on the Integration it was copied to.
In this example, we will copy the incident.impact Field from one Integration to another.
To copy the Field record, navigate to the Fields page. Click on the ellipsis to the right of the incident.impact Field & then click Copy.
On the Copy Field modal, note the value of the Integration and Field Map.
Clear the value of the Integration and the Field Map is automatically cleared.
Select the Integration you wish to copy the Field record to. You are then able to select the equivalent Field Map for that Integration (which you have already created, per Field Maps Best Practice).
Click Copy to save the new Field record.
The Details fields to be configured for the Field record are as follows:
| Field | Type | Description |
|---|---|---|
Description | String | Describe what this field is for and any specific details that might help you in future. |
Inherit | Boolean | Should this field inherit its configuration from the integration-level field of the same name? |
Integration | Reference | The Integration this Field record belongs to. |
Message | Reference | The Message this Field record is linked with. |
Field map | Reference | The Field Map that knows how to process the data in this Field. |
Domain | Reference | The domain that this Field applies to. |
The Settings fields to be configured for the Field record are as follows:
| Field | Type | Description |
|---|---|---|
Field map | Reference | The Field Map that knows how to process the data in this Field. |
Path | String | A path to the node that contains the property. Can be dot or slash notation e.g. parent/child. |
Property | String | The name of the property this field represents in the payload. |
Map to field | Boolean | Should this field map to a specific field on a record? |
Table* | Table name | The primary source/target table that this Field record is mapped to. |
Element* | Field name | The database element, or field, being represented. |
Inbound | Boolean | Is this Field received from another system? |
Outbound | Boolean | Is this Field sent to another system? |
Mandatory | Boolean | Is this Field mandatory? |
Order | Integer | The order at which this Field is processed. |
Depends on | Glide list | Control the order of processing. Specify the Field records that must be processed before this Field record is processed. |
*These fields are visible when ‘Map to field’ is set to true
The Defaults fields to be configured for the Field record are as follows:
| Field | Type | Description |
|---|---|---|
Default inbound* | Script plain | Generate a default value that can be used when an inbound request does not contain a value for this field. |
Default outbound* | Script plain | Generate a default value that can be used when an outbound request does not contain a value for this field. |
*Default inbound/outbound: For a list of available variables, click here.
A Field Choice 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. These are used when you’re mapping choice field elements that have a defined set of values (e.g. State, Impact, Urgency).
Internal values are used and stored by the source and target records.
External values are carried in the payload and exchanged between integrated systems.
Rather than configure choices for each Message, Field Choice records can be defined at the parent integration-level Field meaning you only need to define them once.
When you click on Generate field choices from the Field Choices list, Unifi will go to the Choice [sys_choice] table and automatically pull back the value and label for each of the elements where the table matches the primary source/target table that this Field record is mapped to - creating Field Choice records for each.
You can also use the New button to manually create your own internal/external mappings.
Using the Qualifier field on the Field Choice allows for more complex mappings to take place with dependencies. The Qualifier field is arbitrary and can be used in your own Field Maps as an additional filter so you can build choices with dependencies. For example, a field choice for Status might have a dependency on State. By providing the state value in the qualifier, you can add a new query to your specific Field Map such as addQuery("qualifier", "=", $stage.state).
There are some fields which are visible in native ServiceNow. These can be viewed by clicking the hamburger menu & selecting 'Open in platform'.
The following fields are visible on the platform Integration record:
| Field | Type | Description |
|---|---|---|
Application | Reference | Application containing this record. |
Active | Boolean | Set to true to use this Field record for processing (Inactive Fields will be ignored when building the Message Scripts). |
Name | String | The name of the Field record (auto-populated from the Table & Property fields). |
Fields and Field Map records are not processed during the operational phase (run time) of the Integration. They are processed by a Build process (triggered by a UI action) which takes the information in the records and produces the code which defines the Message Scripts. The Build activity can be performed on an individual Message, or for the entire Integration.
At run time only the Message Scripts are executed and the Field and Field Map records are not accessed at all. This means there is no operational difference between an integration built using Fields and Field Maps and an integration built without.
Next, we will look at Field Maps in more detail.
