GlideDateTime.setValue()

What It Does

The setValue() method overwrites the current date/time value in a GlideDateTime object with a new value from multiple input types. ServiceNow accepts string values in its internal format (YYYY-MM-DD HH:mm:ss), JavaScript Date objects, or other GlideDateTime instances, then converts everything to UTC for internal storage.

When you pass a string value, ServiceNow expects it to be in the exact format used internally by the platform. This is always in 24-hour format with the pattern YYYY-MM-DD HH:mm:ss, and the platform assumes the string represents UTC time. The method performs no validation on string input—malformed strings result in invalid GlideDateTime objects that may cause unexpected behavior in subsequent operations.

JavaScript Date objects undergo automatic timezone conversion during the setValue() operation. The platform takes the local time represented by the Date object and converts it to UTC for storage. This conversion uses the server's timezone settings, not the user's session timezone, which frequently causes confusion when working with dates in Business Rules or Script Includes running in different contexts.

The method returns void and modifies the existing GlideDateTime object in place. Unlike methods such as add() or subtract() that perform calculations on existing values, setValue() completely replaces whatever date/time was previously stored.

Edge cases include passing null or undefined values, which result in the GlideDateTime object holding an invalid state rather than clearing it. Empty strings similarly create invalid objects. The platform provides no error handling for these scenarios—invalid GlideDateTime objects will cause problems when you attempt to use them in queries, display values, or pass them to other API methods.

When to Use This

Use setValue() when you need to set a specific date/time value on a GlideDateTime object, typically when populating date fields programmatically or converting between different date representations. This is the primary method for initializing GlideDateTime objects with known values from external sources, database queries that return raw date strings, or when copying dates between records.

Avoid using setValue() when you need to modify existing dates by adding or subtracting time periods—use add() or subtract() instead. When working with user input that might be in various formats, use setDisplayValue() which handles format parsing and timezone conversion more reliably.

Common misuse includes trying to set dates with user-friendly format strings like "12/25/2023 3:30 PM" or assuming that string inputs will be parsed intelligently. The platform expects exact internal format compliance, and deviations cause silent failures that manifest as incorrect dates in the user interface or failed query conditions.

Return Value

The method returns void (undefined in JavaScript), which means it provides no indication of success or failure. The operation either succeeds by modifying the GlideDateTime object's internal state, or fails silently by leaving the object in an invalid state. You cannot chain setValue() calls or use the return value for conditional logic.

To verify that setValue() succeeded, call isValid() on the GlideDateTime object after setting the value. Invalid operations result in GlideDateTime objects that return false from isValid() and produce unexpected results in display values and database operations.

Platform Behavior & Side Effects

• No Business Rules, notifications, or audit records are triggered—this is purely an in-memory operation on the GlideDateTime object
• Database writes only occur when the GlideDateTime object is assigned to a GlideRecord field and the record is saved via update() or insert()
• Performance is extremely fast as it only modifies object state without database interaction or complex calculations
• Timezone conversion from JavaScript Date objects uses the server's system timezone, not the current user's session timezone preferences
• ACLs are not evaluated during the setValue operation since no field access occurs until the GlideDateTime is used in a database context
• Invalid input values create corrupted GlideDateTime objects that persist until explicitly reset, potentially affecting multiple subsequent operations