Mapping Catalog & Record Producer Date Variables to Record Fields - ben-vargas/servicenow-wiki GitHub Wiki

When users interact with ServiceNow Catalog Items or Record Producers, they often provide date values as part of the request. In many scenarios, these dates must be mapped into actual fields on the resulting record (e.g., Incidents, Change Requests, custom tables). Ensuring the correct interpretation of the date—particularly with time zones, formatting differences, and display values—is critical for maintaining accurate data.

Understanding Date Storage and Display

  • Display Value vs. Storage Value:
    ServiceNow’s date/time fields have both an internal storage format (UTC-based) and a user-friendly display format. Variables collected via Catalog Items or Record Producers often provide date values in a display format consistent with the user’s locale.

  • GlideDateTime Class:
    The GlideDateTime (GDT) object allows you to parse, manipulate, and convert dates between display values and their numeric (epoch) or UTC-based equivalents.

  • Setting Field Values:
    To store a date in a record field accurately, you often need to:

    1. Retrieve the user-selected date from the variable pool.
    2. Convert it from a display string into a GlideDateTime object.
    3. Apply that GlideDateTime value to the record’s field, ensuring proper conversion to the internal format.

Example Code Snippet

Below is an example script that might run in a server-side context (e.g., a Record Producer’s script or a Script Include processing a catalog request):

// Retrieve the date value from the Record Producer's variable pool
var dueDate = current.variable_pool.due_date;

// Create a new GlideDateTime object
var gdt = new GlideDateTime();

// Set the GDT to the display value obtained from the variable
gdt.setDisplayValue(dueDate);

// Convert and store it properly into the record's due_date field
current.due_date.setDateNumericValue(gdt.getNumericValue());

Explanation:

  1. Retrieve the Variable:
    var dueDate = current.variable_pool.due_date; gets the date string selected by the user from the record producer variables.

  2. Initialize GlideDateTime:
    var gdt = new GlideDateTime(); creates a new GDT object that can parse and manipulate date values.

  3. Set Display Value:
    gdt.setDisplayValue(dueDate); interprets the dueDate string according to the system’s display format and converts it into the GDT’s internal representation.

  4. Apply to the Record Field:
    current.due_date.setDateNumericValue(gdt.getNumericValue()); sets the record’s due_date field using the numeric value (milliseconds since epoch) from the GDT. This ensures that the date is stored accurately according to the system’s internal UTC-based format.

Why Use This Approach?

  • Accurate Time Zone Handling:
    By using setDisplayValue() and retrieving getNumericValue(), you ensure the date is consistently interpreted according to the system’s date/time settings, preventing confusion caused by different user locales or time zones.

  • Reliability:
    Relying on the native GlideDateTime methods instead of manually parsing strings reduces errors and makes your code more resilient to format changes.

  • Flexibility:
    Once you have a GlideDateTime object, you can perform other date/time manipulations, such as adding days, comparing times, or formatting the output differently.

Best Practices

  1. Always Use GlideDateTime for Date Conversion:
    Avoid manually parsing strings. The platform’s APIs are robust and accommodate diverse date/time formats.

  2. Validate Variable Values:
    If user input is optional or may be empty, check for null or empty values before parsing to avoid unexpected errors.

  3. Consistent Formatting:
    If you have a known format for display values (e.g., "MM/dd/yyyy"), confirm it matches the system’s expected format to prevent misinterpretation.

  4. Test in Multiple Locales:
    If you support users in multiple locales or time zones, test the script to ensure correct date interpretations globally.

Additional Resources

  • ServiceNow GlideDateTime Documentation:
    GlideDateTime API for reference on the GlideDateTime API, its methods, and best practices.

Conclusion

Mapping Catalog Item or Record Producer date variables to record fields in ServiceNow is straightforward with the right approach. By using GlideDateTime methods to interpret display values and convert them into the system’s numeric storage format, you ensure data integrity, time zone correctness, and easier maintenance of your date-related logic.