The official ServiceNow documentation says: Reference fields store a Sys ID, for each referenced record in the database, but the Sys ID is not shown. The reference field shows the display value. And then some other bits and pieces on how to configure display values and a very unconvincing algorithm how the display value fields are being evaluated. SnowMirror supports the ServiceNow display values out of the box so we had to gather all the information available and the rest comes from observations and reverse engineering.
In ServiceNow, there is concept of display values and actual values. The actual value represents the raw value in the database, whereas the display value represents the user-understandable value that is usually shown in the UI. For some fields, there are significant differences in how these values display in the UI vs. in the database. For example:
- Encrypted text: The database value is encrypted, while the displayed value is unencrypted based on the user’s encryption context.
- Reference fields: The database value is sys_id, but the display value is a display field of a referenced record.
- Date fields: The database value is in UTC format, while the display value is based on the user’s time zone.
- Choice fields: The database value may be a number, but the display value will be more descriptive.
Let’s focus on the reference fields. How does ServiceNow evaluate which field to use as a display value? It is not so straightforward as it might seem. Imagine a table hierarchy Security Incident :: Incident :: Task. It is possible to specify display values in each table or just in one of them. It is possible to omit the display values at all and rely on the defaults and finally, have you heard of Dictionary Overrides?
Here is the actual evaluation algorithm ServiceNow uses:
- Dictionary Override – Current Table – The highest priority in the evaluation algorithm has a flag called Override Display Value in the Dictionary Override (i.e. table called sys_dictionary_override). It is possible to set a different display value then the parent table is specifying. E.g. the Task table has the field number as a display value. In the child table Security Incident it is possible to set up an override configuring short_description as a display value.
- Dictionary Override – Parent Table – same as previous. If there is no override in the referenced table then the algorithm searches for overrides in the table hierarchy from the child to the parent. E.g. override in the Incident table takes precedence over a display value field specified in the Security Incident table but not over an override in the Security Incident table.
- Display value field – Current Table – if there are no overrides then the standard display value fields come into play. The display value on the child table overrides the display value on the parent. E.g. Security Incident can specify its own field u_security_code as a display value for security incidents which would override the number field in Task.
- Display value field – Parent Table – same as previous. If there is no display value field in the referenced table then the algorithm searches for display fields in the table hierarchy from the child to the parent.
- Default fields – even if there are no display values explicitly set up, ServiceNow searches for default fields to make them as display value fields. These fields are “name“, “u_name“, “sys_name“, “number“, “u_number“. The algorithm first searches the whole table hierarchy for a field called name. Then, if not found, it searches for u_name, etc. Please note that the child-parent mechanism does not work here. Name has always precedence over Number.
- Sys ID – if everything fails then ServiceNow uses sys_id as a display value.
Note that the display value field can be another reference field or can be a choice list field. Transitive relation applies here so ServiceNow is traversing through the display values to find the last in the row.
SnowMirror is using the same algorithm to evaluate sizes of the display value fields so it can create the correct data types with correct sizes for the display value columns. SnowMirror should always look simple on its surface but, in fact, the internals are rather complicated.
