For the complete documentation index, see llms.txt. This page is also available as Markdown.

Set the object UUID on first save

Generate and assign the object's _uuid when the object is created.

Use case

You want every new object to receive a UUID that you control, available from the moment the object is created (for example to build a stable external reference).

The object's _uuid is a system field, so it lives on the envelope dataPath[0], not on objNew. On the first save it is still empty: the server generates a _uuid only while it writes the object to the database, which happens after the db_pre_save formula runs. Because it is empty at that point, the formula can set it — and the value it sets is kept (the server only auto-generates a UUID when none is present).

Snippet

// On the first save the object has no _uuid yet, so generate one and assign it
// to the envelope. The "formula-" prefix makes it recognisable that the formula
// set this UUID. On later saves _uuid is already present, so leave it untouched.
if (!dataPath[0]._uuid) {
    dataPath[0]._uuid = "formula-" + require("crypto").randomBytes(16).toString("hex");
}
return dataPath[0]._uuid;

The same value is returned, so it is also stored in this column — handy for checking the result.

📷 Screenshot: the detail view of a freshly created object, showing the formula column value equal to the object's _uuid.

How it works

  • dataPath[0] is the object envelope, where _uuid lives. Assigning dataPath[0]._uuid changes the UUID the object is created with.

  • The if (!dataPath[0]._uuid) guard makes this happen only on the first save. On every later save the UUID already exists, so it stays stable and is never regenerated.

  • The server keeps a _uuid that is already set and only generates one when it is empty, so the value from the formula survives the save.

Common mistakes

These do not work:

Always assign to dataPath[0]._uuid (the envelope), not to objNew.

Last updated