Three Kinds of Date in XPages — You Have to Know Which One You're Holding
The thing that actually bites you with dates in XPages SSJS isn’t a method you can’t call — it’s not noticing that three different “dates” are flowing through your code at once:
NotesDateTime: the back-end Domino date type. What you read from a document field, or fromgetCreated(), is this.java.util.Date: the Java-layer date. SSJS runs on Java underneath, and plenty of things hand you one of these.- JavaScript’s
Date: the one you know from the client — but in server-side SSJS it is not the same thing as the two above.
The same “2026-11-03,” wrapped in a different type, has different capabilities, compares differently, and writes back to a document differently. Put the wrong one in the wrong place and, at best, you get a type error; at worst, you store a value that looks right but has drifted by a time zone or a time-of-day. This piece covers how to build a NotesDateTime in SSJS, how to convert between the three types, the common methods, and the two traps that catch everyone.
TL;DR
- There’s one reliable way to build a
NotesDateTime:session.createDateTime(...). Officially it “Creates a NotesDateTime object that represents a specified date and time” — the argument is a string (date, space, time) or a Date. - To convert to a Java
Date, usetoJavaDate()— officially “Converts a NotesDateTime object to a Date object.” It’s the bridge you’ll cross most between the three types. - Common methods:
adjustDay/adjustHour/adjustMonth… (shift),setNow(set to now),timeDifference(seconds between two values),convertToZone(change zone). - Trap one: “Today” has no time.
createDateTime("Today")gives a date with no time; the docs tell you to thensetNow()or write an explicit time like"Today 12:00:00 AM". - Trap two:
@Todayisn’t necessarily aNotesDateTime. To write a date into a document field,session.createDateTime("Today")is the safe path — don’t just drop@Today()’s result intoreplaceItemValue(details below).
Building a NotesDateTime: session.createDateTime
In SSJS you don’t new a NotesDateTime — officially it “Represents a date and time,” and there’s a single entry point to create one: session.createDateTime. The official NotesSession page describes it as “Creates a NotesDateTime object that represents a specified date and time.”
// string: date space timevar dt:NotesDateTime = session.createDateTime("2026-11-03 09:30:00");
// keywords work toovar today:NotesDateTime = session.createDateTime("Today");
// or feed it a Datevar fromDate:NotesDateTime = session.createDateTime(new Date());It’s the same concept as LotusScript’s New NotesDateTime(...) and Java’s session.createDateTime(...), just the SSJS spelling.
Three types, how to convert
This is where SSJS gets messier than LS or Java, because all three date types brush past each other in the same block. Keep the directions straight:
- Read from a document →
NotesDateTime.doc.getCreated(),doc.getLastModified(), or a date field read back are allNotesDateTime. - Hand it to anything that wants a Java
Date(formatting, other Java APIs) →toJavaDate(). This is the officially stated conversion: “Converts a NotesDateTime object to a Date object.” - Back to a
NotesDateTime(e.g. to write to a document) →session.createDateTime(thatDate).
var created:NotesDateTime = doc.getCreated(); // back end → NotesDateTimevar jdate:java.util.Date = created.toJavaDate(); // to a Java Date for formatting/math// ... process ...var back:NotesDateTime = session.createDateTime(jdate); // convert back to writedoc.replaceItemValue("ProcessedAt", back);In one line: keep back-end work in NotesDateTime, cross to the Java world with toJavaDate(), and createDateTime your way back to write to a document.
Common methods
NotesDateTime’s methods share the names you know from LS and Java; SSJS uses them directly. The official ddwiki SSJS samples demonstrate all of these:
var dt:NotesDateTime = session.createDateTime("Today");dt.setNow(); // set to now (date + time)dt.adjustDay(7); // +7 days; officially: Increments a date-time by a number of daysdt.adjustHour(-3); // -3 hours
// seconds between two valuesvar a:NotesDateTime = session.createDateTime("2026-11-03 09:00:00");var b:NotesDateTime = session.createDateTime("2026-11-03 17:30:00");var secs = b.timeDifference(a); // officially: difference in seconds
// change zonedt.convertToZone(8, false); // officially: Changes the TimeZone and IsDST propertiesThe read-out properties are worth remembering too: DateOnly (just the date string), TimeOnly (just the time), GMTTime (the value converted to GMT), LocalTime (the local-zone string).
Trap one: “Today” has no time
This one the docs name themselves. createDateTime("Today") (and "Tomorrow", "Yesterday") uses Domino’s current date but sets no time — the official wording tells you to either setNow() afterwards or write an explicit time from the start, like "Today 12:00:00 AM".
The consequence is concrete: a NotesDateTime that’s “date only, no time” has an invalid TimeZone (the docs say it returns 0 then), and comparing or subtracting it against a value that does have a time gives you results you didn’t want. To do time math, fill it out to a full date-and-time first.
var d:NotesDateTime = session.createDateTime("Today");d.setNow(); // add a time, so timeDifference / adjustHour behaveTrap two: @Today isn’t necessarily a NotesDateTime
This one is subtler, and it’s exactly where mixing the three types catches you. In SSJS, @Today() / @Now() don’t necessarily return a NotesDateTime — the community (the HCL developer forum) reports they hand back a Java Date, and dropping @Today()’s result straight into doc.replaceItemValue(...) for a date field has thrown type errors for people.
This is a community report, not official black-and-white — confirm it in your own Domino version with
typeof/getClass(). But whatever@Todayreturns, the conclusion is the same and safe: to write a date value to a document, make an explicitNotesDateTimewithsession.createDateTime("Today")and don’t gamble on the type.
// the safe way: make an explicit NotesDateTimedoc.replaceItemValue("DueDate", session.createDateTime("Today"));Time zones, in one line
A NotesDateTime’s zone comes from Domino’s setting, convertToZone changes it, and GMTTime gives you the GMT string directly. When XPages passes a +08:00 value between layers (back end, display, request zone), off-by-an-hour / off-by-a-day is an old problem — the full time-zone story is in the LotusScript NotesDateTime time-zone piece, and it’s the same rules underneath.
What about Java and LotusScript?
The same NotesDateTime, but the emphasis shifts by language:
- LotusScript:
New NotesDateTime(...)orsession.CreateDateTime(...), same method names; the basics are in the NotesDateTime piece. There’s no “three types to juggle” — in LS it’s justNotesDateTime. - Java:
session.createDateTime(...), with the sametoJavaDate()/java.util.Dateround-trip, plus one extra chore —recycle()when done. Java date handling is in Java’s NotesDateTime. - The SSJS-specific pain is exactly this piece’s subject: you’re caught between
NotesDateTime,java.util.Date, and JavaScript’sDateall at once —toJavaDate()is the bridge,session.createDateTimeis the way back, and knowing which one you’re holding is how dates stop drifting.
Sources
- NotesDateTime (JavaScript) (class, methods, properties, time zones; toJavaDate) — HCL Domino Designer (official)
- NotesSession (JavaScript) (createDateTime) — HCL Domino Designer (official)
- NotesDateTime sample JavaScript code for XPages (SSJS samples: setNow / adjustDay / convertToZone / toJavaDate) — HCL ddwiki (official)