Formula Language

Formula Language is the original, @function-based scripting language built into Lotus Notes - and now HCL Notes/Domino - since the platform’s debut in 1989. Often simply called “the @formula language” or just “@formulas,” it is a compact, expression-oriented macro language designed specifically for working with documents, fields, and views inside a Notes database. For more than three decades it has been the everyday tool of Notes application developers, used everywhere from a one-line computed field default to elaborate view selection criteria driving mission-critical enterprise workflows.

History & Origins

Notes and the Birth of Groupware

The story of Formula Language is inseparable from the story of Lotus Notes itself. Ray Ozzie, who had previously worked on PLATO Notes and Symphony, founded Iris Associates in 1984 to build a new kind of collaborative software. Lotus Development Corporation - then famous for the Lotus 1-2-3 spreadsheet - funded the work in exchange for marketing rights. The result, Lotus Notes 1.0, shipped in December 1989 and is widely credited with popularizing the term “groupware.”

From the very first release, Notes needed a way for end-user developers to express small bits of logic: “set this field’s default to today’s date,” “show only documents where status equals Open,” “hide this section unless the user is in the Managers group.” Rather than require a full programming language for these small jobs, Iris built Formula Language - a function-call-driven expression language that felt familiar to anyone who had ever written a formula in Lotus 1-2-3.

IBM and HCL Eras

Lotus was acquired by IBM in 1995, and Notes/Domino became one of IBM’s flagship collaboration products through the 2000s. In 2018-2019, HCL took over development and ownership of Notes, Domino, and the surrounding product family. Throughout these transitions, Formula Language has remained remarkably stable: formulas written for Notes R3 in the early 1990s very often still run in modern HCL Domino releases.

Design Philosophy

Formula Language was designed for document-oriented programming. A Notes database is a collection of documents (semi-structured records), and almost every place you can put a formula is a place that needs to compute a value for, or about, a document.

Key design ideas:

• Expression-oriented: A formula is fundamentally an expression that produces a value. Even side-effecting features (like @SetField or @MailSend) are written as function calls inside that expression.
• Field-aware: Field names are first-class identifiers. Writing LastName in a formula refers to the value of the LastName field on the current document; you do not need to fetch it explicitly.
• List-native: Many values in Notes are multi-valued. Formula Language treats lists as a first-class data type, and most operators (including arithmetic and comparison) automatically pair lists element by element.
• @functions everywhere: Built-in capabilities are exposed as functions prefixed with @, such as @If, @Today, @Name, @DbLookup, and @UserName. The @ prefix keeps user-defined field names and built-ins visually distinct.
• No declarations: There is no variable declaration syntax in the classical sense. Temporary variables are introduced inline with assignment-style statements separated by semicolons.

Where Formulas Live

Formula Language is not used to write standalone programs. Instead, formulas are attached to design elements inside a Notes application. Common attachment points include:

• Computed field formulas - compute the value of a field when a document is opened, refreshed, or saved
• Default value formulas - provide the initial value of an editable field
• Input translation / input validation formulas - normalize or check user input on save
• View selection formulas - decide which documents appear in a view (SELECT Form = "Memo")
• View column formulas - compute what each row in a view displays in a given column
• Hide-when formulas - show or hide form sections, fields, or buttons based on a boolean expression
• Action button and agent formulas - run on demand to update documents, send mail, or navigate the UI
• Replication formulas - select which documents replicate between a server and a workstation

The same language is used in all of these places, with the evaluation context (current document, current user, server vs. client) determining what makes sense.

Key Features

@Functions

The defining feature of the language is its enormous library of @functions. A small sampling:

@If(condition; trueResult; falseResult)
@Today
@Now
@Name([CN]; UserName)
@UserName
@DbLookup("":"NoCache"; ""; "PeopleView"; key; 2)
@DbColumn("":"NoCache"; ""; "ProductsView"; 1)
@Trim(rawText)
@Left(s; n) ; @Right(s; n) ; @Middle(s; start; n)
@Sum(numericList)
@Unique(list)
@Sort(list; [Ascending])
@Prompt([OK]; "Title"; "Message")
@MailSend(sendTo; copyTo; blindCopyTo; subject; remark; bodyFields; flags)
@SetField("Status"; "Approved")
@Command([FileSave])

@functions cover string and list manipulation, dates and times, mathematical operations, user and server identity, database lookups, UI prompts, mail sending, and Notes client commands.

Lists Everywhere

A Notes field can naturally hold multiple values. Formula Language reflects this with rich list semantics:

names := "Alice" : "Bob" : "Carol";
greetings := "Hello, " + names + "!";
@Implode(greetings; ", ")

The : operator builds a list. The + operator paired with a single string broadcasts across the list, producing "Hello, Alice!" : "Hello, Bob!" : "Hello, Carol!". @Implode then joins them into a single string.

Comparisons also work across lists. For example:

status := "Open" : "Pending" : "Closed";
@If(@IsMember("Open"; status); "Has open"; "None open")

@IsMember checks whether "Open" appears in the list, returning a boolean.

Temporary Variables and Sequencing

Statements are separated by semicolons. Temporary variables are introduced with :=:

firstName := @Trim(FirstName);
lastName := @Trim(LastName);
fullName := firstName + " " + lastName;
@If(fullName = " "; "(no name)"; fullName)

The value of the formula is the value of its final expression. There is no explicit return keyword in classical Formula Language; the final expression’s value is what gets used (for computed fields, view columns, and so on).

View Selection Formulas

View selection has its own minor convention: a selection formula must start with SELECT:

SELECT Form = "Memo" & @Created >= [01/01/2024]

This decides which documents are eligible to appear in the view.

Database Lookups

@DbLookup and @DbColumn let formulas read data from other Notes views and even other databases, which historically made Formula Language sufficient for a surprisingly large class of dynamic applications without writing any LotusScript:

manager := @DbLookup("":"NoCache"; ""; "EmployeeView"; EmployeeID; "Manager");
@If(@IsError(manager); ""; manager)

A Small, Complete Example

A “computed when composed” subject line that prefills a memo with the current user’s display name and today’s date:

user := @Name([CN]; @UserName);
"Status report from " + user + " - " + @Text(@Today; "D0S0")

A view selection formula that shows only open tickets assigned to the current user:

SELECT Form = "Ticket" & Status = "Open" & AssignedTo = @UserName

A validation formula that ensures a numeric field is positive:

@If(Amount > 0;
    @Success;
    @Failure("Amount must be greater than zero"))

Evolution

Formula Language has evolved more conservatively than most languages of its age - which is, for Notes shops, often a feature rather than a bug.

• Notes 1.x-3.x (1989-1993): Establishes the core @function set, list semantics, and the major attachment points (fields, views, hide-when).
• Notes 4 (1996): Adds LotusScript as a companion language for richer, BASIC-style programming, while Formula Language continues to be the right tool for short, document-bound expressions. Formula Language gains additional @functions and @commands over this era.
• Notes/Domino 6 (2002): A notable Formula Language expansion, introducing functions such as @Transform (apply a sub-formula to each list element), @Sort, looping/iteration patterns, and richer list manipulation, narrowing the gap between Formula Language and full scripting.
• Notes/Domino 7-9 (2005-2013): Incremental improvements, better integration with web and XPages applications, and continued support for legacy formulas.
• HCL era (2019-present): HCL Notes/Domino 10, 11, 12, and 14 continue to ship Formula Language as a first-class feature, with documentation maintained on the HCL Domino product site.

Current Relevance

Formula Language is unusual: it is not a language anyone reaches for to start a new project from scratch, and it has no presence outside the Notes/Domino ecosystem. Yet within that ecosystem it is unavoidable. Any organization still running Notes applications - and many large enterprises, government agencies, and regulated industries do - has Formula Language embedded throughout their forms, views, and agents.

For developers maintaining or modernizing those systems, Formula Language remains a daily working tool. HCL continues to publish reference documentation for @functions and @commands as part of the HCL Domino product family.

Why It Matters

Formula Language is one of the earliest and most successful examples of an embedded, domain-specific scripting language baked into an end-user application platform. It influenced how developers think about:

• Spreadsheet-style formulas extended to a document database
• Field-oriented expression languages where identifiers transparently reference data
• List-native operators with implicit broadcasting
• The “@function library” pattern, where capability discovery is a flat namespace of well-named functions

For an entire generation of corporate developers, “writing code” first meant typing an @If(...) into a Notes design element. That cultural footprint - millions of small formulas keeping the world’s enterprise paperwork moving - is what makes Formula Language worth remembering, and worth maintaining, decades after Notes 1.0 first shipped.