NotesName in XPages: getCommonUserName Saves a Step, Comparing Still Needs Normalizing

NotesName in XPages: getCommonUserName Saves a Step, Comparing Still Needs Normalizing

Nov 17, 2026 485 words

In XPages, to show the logged-in user’s name, the common write-up is session.createName(session.getUserName()).getCommon() — build a NotesName, then ask for its common name.

You don’t have to make that round trip. The session itself has shortcuts: getCommonUserName() gives you the logged-in user’s common name in one step, and getUserNameObject() hands you a NotesName object directly. That’s where XPages is more convenient than back-end Java.

But one thing XPages can’t skip: the moment you compare — an approver, or an OU deciding whether a block is shown — you hit the “same person, canonical and abbreviated aren’t equal” trap. This covers the session name shortcuts, comparing and checking OU correctly in XPages, and which form to use writing a name into a Readers field.


Display: the session name shortcuts

NotesSession gives you ready-made values about “the current user,” no createName needed:

  • session.getCommonUserName() — the docs: “The common name of the user that created the session.” Use this to show “Hello, John B Goode” on the page.
  • session.getUserNameObject() — the docs: “The name, in the form of a NotesName object, of the user or server that created the session.” When you need to pull OU apart or get the canonical form, take this NotesName directly — no getUserName() then createName.
  • session.getUserName() (full name) and session.getEffectiveUserName() (login name) are there too.

For the current user, these shortcuts are the cleanest. Only for “someone else’s” name (a field value in a document) do you reach for session.createName(thatValue).

Comparing: XPages can’t skip normalizing either

This is the trap that runs from back-end Java all the way into XPages. The approver stored in a document might be the abbreviated John B Goode/Acme, while the logged-in getUserName() is the canonical CN=John B Goode/O=Acme — same person, unequal strings. The fix is still to normalize both sides:

var me = session.getUserNameObject(); // already a NotesName
var him = session.createName(doc.getItemValueString("Approver"));
var same = me.getCanonical().equalsIgnoreCase(him.getCanonical());

The full story behind normalizing is in the Java Name piece — the same logic, reused in SSJS.

Using OU for conditional visibility

A common XPages need: show a block only to people in a given org unit, bound to rendered. Here, don’t use contains("Sales") — someone whose name happens to include “Sales” gets let in. Compare the specific component with getOrgUnit1():

// a panel's rendered property
var ou = session.getUserNameObject().getOrgUnit1();
"Sales".equalsIgnoreCase(ou);

A NotesName’s components are all there: getOrganization() (O=), getOrgUnit1() through getOrgUnit4() (OU=), getCountry() (C=).

Write canonical into a Readers field

A related practical point: if you write a name into a Readers / Authors field in XPages (controlling who can see the document), store the canonical form. Readers fields match on the full hierarchical name; store abbreviated or common and the match can miss, or wrongly let someone in. Normalize with createName(...).getCanonical() before writing. Readers/Authors behavior is in the Readers and Authors fields piece.

What about LotusScript and Java?

The same Name:

  • LotusScript: NotesName, with Common / Canonical / OrgUnit1 and the rest; the format details are in the NotesName formats piece.
  • Java: Name, same API; the comparison bug and normalizing are covered in the Java Name piece, but Java has no XPages session.getCommonUserName()-style “current user” shortcut.
  • What’s SSJS-specific isn’t the API (the methods are shared) — it’s the NotesSession “current user” conveniences in XPages, getCommonUserName() / getUserNameObject(): a step saved when showing yourself, while the canonical≠abbreviated trap is still there the moment you compare.

Sources

← Back to all posts