Do you get Reference fields getting the wrong matching? Then use setDisplayValue. Enviably developed within this highly regarded field type that displays as a string is just one click away from another table that includes our famous dot walk features. Dot-walking provides an ideal way to join table records. When you define a reference field, the system creates a relationship between the two tables. Adding a reference field to a form makes the other fields in the referenced table available to the form. When on the incident table, both Caller and Assigned to are referenced to the sys_user table.
Here is the story of an example of what happens when you try to set a reference field value like any other ordinary field! Reference fields are special. I mean, they are REALLY special. A lion disguised as cat.
Example of populating a reference field by setValue vs setDisplayValue
I have created two users on sys_user (in this order):
First user: user_name = 2, First name = Mike, Last Name = Yes (Display value : "Mike Yes") - (e.g. sysid:de5e388d4f1932002c9e4b8d0210c7f3)
Second user: user_name = user_2, First name = "", Last Name = 2 (Display value : "2")
When executing the following background script :
---background script----
// Create a new Incident
var gr = new GlideRecord('incident');
// Set the caller ID by setValue but using the Display value
gr.caller_id = "2";
gr.short_description = "testing sys_user.name and sys_user.user_name matching display value";
var vsid = gr.insert();
// Now, retrieving the record inserted
var gr2 = new GlideRecord('incident');
gr2.get('sys_id',vsid);
gs.print ('inserted ' + gr2.number +' OK. Caller: ' + gr2.caller_id.name + ' Caller sys_id: ' + gr2.caller_id.sys_id);
The result is the incident is created with caller_id = "Mike Yes". It matches the incorrect value.
> [0:00:00.228] Script completed in scope global: script
> *** Script: inserted INC0010002 OK. Caller: Mike Yes Caller sys_id: de5e388d4f1932002c9e4b8d0210c7f3
On reference fields to sys_user, user_name is used to match the user before using the "Display value." This is because I have use setValue ( = is setValue)
> gr.caller_id = "2";
Please note gr.<field> = "xxx" is the same as gr.setValue('field',"xxxx")
Same behavior will be seen on email inbound actions, scripts and data imports (loading the data into reference fields). If you are not using the sys_id on reference fields, the appropriate method is:
> gr.setDisplayValue('caller_id', "2");
Use setDisplayValue to assign Reference fields or Choice values when the data provided it is the "Display" value
Here is the correct script for this example
---background script----
// Create a new record
var gr = new GlideRecord('incident');
// IMPORTANT: As "2" is the Display value of the user "2", setDisplayValue needs to be used.
gr.setDisplayValue('caller_id', "2");
// as short_description is just string, setValue is enough.
gr.short_description = "testing sys_user.name and sys_user.user_name matching display value";
var vsid = gr.insert();
// Retrieving the information back to review:
var gr2 = new GlideRecord('incident');
gr2.get('sys_id',vsid);
gs.print ('inserted ' + gr2.number +' OK. Caller: ' + gr2.caller_id.name + ' Caller sys_id: ' + gr2.caller_id.sys_id);
The result is the incident is created with caller_id = "2" . Yeah!
>[0:00:00.067] Script completed in scope global: script
>*** Script: inserted INC0010003 OK. Caller: 2 Caller sys_id: d1de7cc94f1932002c9e4b8d0210c7ce
It correctly matches the Caller "2".
When dealing with reference fields, please ensure to use setDisplayValue if you are not passing the sys_id to avoid surprises! If you are creating a script, or a inbound action, a data source (to import data), etc
More information here:
3 Comments
