Formats

Reference

App files

The files of a Volobox app: app.json keys, entities, roles and access, rules and their helpers, Volobox events, screens and the screen SDK.

This page is the format of a Volobox app as the Builder's agent writes it: app.json, the rules, the screens, and how they reach the rest of Volobox. You do not need it to build an app; read it to review a change under Details > Changed files, or to edit an exported app. Examples are adapted from the Expense Claims template.

Folder layout

Text
app.json            data, roles, access, rules list, screens list, menu, events, secrets
AGENTS.md           the app's guide for the Builder's agent (only the agent reads it)
rules/
  submit.js         one file per rule, default-exporting an async function
  lib/              code the rules share
screens/
  MyClaims.tsx      one React component per screen
  lib/              code the screens share
locales/
  en.json           only in an app with several languages: one file per language
  tr.json
package.json        optional packages the screens use
package-lock.json   written by Volobox after each turn; never edited by hand

Any other file in the workspace (notes, scratch files) is not part of the app. An export holds the model, rules, screens and packages, never records, people or logs.

app.json

app.json validates against app.schema.json. Only version and name are required.

KeyTypeMeaning
$schemastringOptional path or URL of the schema, for editors. Volobox ignores it
versionintegerFormat version. Always 1
namestringThe app's name. People see the Name on the app's Settings; Volobox writes that name here when it saves the files
descriptionstringOne or two sentences on what the app is for
rolesarrayThe app's own roles (see Roles and audiences)
enumsarrayNamed value lists that enum fields use
entitiesarrayThe record types the app stores. Each becomes a table
rulesarrayServer-side JavaScript: operations, endpoints, event handlers and schedules
accessobjectWho may do what, per entity, endpoint and screen
screensarrayThe app's pages, each a React component
startPagestringId of the screen the app opens on. Defaults to the first screen that is not hidden
navigationstringWho draws the navigation: shell (Volobox, the default) or screens (the app, with AppNav)
menuobjectThe menu's layout: items in order (screens, sections, folders, separators, links to other Volobox pages) and footer
languagesobject{ "default": "en", "supported": ["en", "tr"] }; each supported language has locales/<language>.json
eventsarrayThe events this app announces outside itself, so workflows can start from them
sharesarrayWhat this app offers other apps: records to read, events to handle, endpoints to call
usesarrayOther apps' shares this app reads, each under an alias
secretsarrayCredentials the rules send to other systems, read as env.<NAME>
connectionsarrayKinds of accounts at other services that people connect, for rules to act as
listensarrayThe Volobox events the app's rules react to
voloboxobjectThe parts of Volobox's public API the app's screens call

Roles and audiences

Two kinds of roles decide what a person does in an app:

  • Member roles are Volobox's and are never written in the files. An app's Admins give them under Settings > Members: member uses the published app, builder also builds the draft and publishes (and reads and changes every record, whatever access says), admin also manages people and settings. People with Manage all apps count as an Admin of every app.
  • App roles are the app's own, listed under roles and assigned under Settings > Roles. They only add to what a member may do.
JSON
"roles": [
  { "id": "approver", "label": "Approver", "description": "Approves, sends back or rejects the claims that name them." },
  { "id": "finance", "label": "Finance", "description": "Keeps the spending policy and pays approved claims." }
]

access names audiences:

AudienceWho
A role id, such as approverThe people and groups who hold that app role
everyoneEvery member of the app, whatever app roles they hold (everyone in the workspace when the app is public)
anyoneAlso people who are not signed in, on the published app only. Never an entity audience

Unless asked otherwise, a new app starts with one role, editor, that may create, change and delete everything, and everyone with list and read on every entity, every screen and every GET endpoint.

Enums

JSON
{
  "id": "claim-status",
  "name": "ClaimStatus",
  "label": "Status",
  "values": [
    { "name": "draft", "label": "Draft", "value": 0, "color": "gray" },
    { "name": "submitted", "label": "Waiting for approval", "value": 1, "color": "blue" },
    { "name": "approved", "label": "Approved", "value": 3, "color": "green" }
  ]
}

id is stable, lowercase with dashes; name is PascalCase and is what an enum field names. Records hold a value's name; value is the stored number, which publishing flags when it changes for an existing name.

Entities

KeyMeaning
idStable id, lowercase with dashes. Keep it when the entity is renamed
namePascalCase singular name, such as Claim. Fields, rules and access refer to it
label, pluralLabel, descriptionHow people see it
displayFieldThe field that names a record in lists, pickers and references
ownerFieldA reference-to-user field that says whose record it is. scope: "own" compares it with the signed-in person
fieldsThe entity's fields
validationsChecks that compare two fields of the same record
voloboxHow the records take part in Volobox (see The volobox block of an entity)

Every entity also has id, createdAt, createdBy, updatedAt and updatedBy, which are not listed. A record read through the API carries $version, which an update passes back so that a write made in between is refused rather than overwritten.

Removing a table or field parks its data; adding it back with the same id restores it. Publishing never deletes data.

Field types

typeHolds
textText, optionally with maxLength, minLength, pattern or format (email, phone, url)
integer, decimalNumbers, with min, max and, for decimal, scale
moneyAn amount with currency (an ISO 4217 code such as EUR) and scale
booleanYes or no
date, dateTime, timeA day (YYYY-MM-DD), a moment (ISO 8601 in UTC), a time of day (HH:MM)
enumOne value of the enum named in enum
referenceA record of entity: another table of the app, user for a Volobox person, volobox.<kind> for a Volobox item (read only, such as volobox.project), or app.<alias>.<Entity> for another app's shared records (read only)
file, imageA stored file, optionally limited by allowedContentTypes (and image dimensions)
listA list of itemType values (text, integer, decimal, boolean, date or enum), with maxCount and uniqueItems
formulaA computed value: a Power Fx expression over the record's fields, with a resultType
rollupA summary of another entity's records: source, via (its reference field), operation (count, sum, average, min, max) and value
secretA credential each record holds, stored encrypted and never read back

Field options

OptionMeaning
id, nameStable id (lowercase with dashes) and camelCase name
label, descriptionHow people and agents see the field
requiredA record cannot be saved without a value
uniqueNo two records hold the same value
defaultThe value a new record starts with
readOnlyOnly rules write it
serverOnlyNever leaves the server: rules read and write it, screens never see it
onDeleteFor a reference to the app's own entity: restrict (default), cascade or setNull
scopedByFor a Volobox item with a parent, such as volobox.milestone: the field holding the parent, so the picker offers only its items
JSON
{
  "id": "expense",
  "name": "Expense",
  "displayField": "merchant",
  "ownerField": "employee",
  "fields": [
    { "id": "claim", "name": "claim", "type": "reference", "entity": "Claim", "required": true, "onDelete": "cascade" },
    { "id": "employee", "name": "employee", "type": "reference", "entity": "user", "readOnly": true },
    { "id": "amount", "name": "amount", "type": "money", "currency": "USD", "required": true, "min": 0.01 },
    { "id": "receipt", "name": "receipt", "type": "file", "allowedContentTypes": ["image/jpeg", "image/png", "application/pdf"] },
    { "id": "over-limit", "name": "overLimit", "type": "boolean", "readOnly": true, "required": true, "default": false }
  ]
}

The volobox block of an entity

KeyMeaning
screenId of the screen a record opens on in Volobox. It receives the record's id in the query parameter param
paramThe camelCase query parameter name. Defaults to id
copyReferencePeople may copy a record's reference into chats, tasks and documents
agendaPeople may add a record to their Volobox agenda
discussionEach record has a Volobox discussion of its own, open to the people who may read the record
search{ fields, semanticFields }: Volobox's quick search finds records by fields; semanticFields suggests fields an Admin may allow for search by meaning

The block needs a displayField and a screen. It widens nothing: a reference, agenda link or discussion opens a record only for people the app lets read it, and only in the published app.

access

JSON
"access": {
  "entities": {
    "Claim": {
      "everyone": { "list": true, "read": true, "create": true, "update": true, "delete": true, "scope": "own" },
      "approver": { "list": true, "read": true },
      "finance": { "list": true, "read": true }
    }
  },
  "endpoints": { "submit": ["everyone"], "decide": ["approver", "finance"], "pay": ["finance"] },
  "screens": { "claims": ["everyone"], "approvals": ["approver", "finance"], "payments": ["finance"] }
}
KeyMeaning
entities.<Entity>.<audience>A grant: list, read, create, update, delete, optionally scope: "own" (records whose ownerField is the person) and when (a formula limiting update and delete, such as status = "draft")
endpoints.<rule id>The audiences that may call an endpoint. Left out, it is for Builders and Admins only
screens.<screen id>The audiences that see a screen. Seeing a screen grants no data
channels.<name>Who hears a realtime channel a rule publishes on (everyone or role ids)
connections.<name>Who may connect and disconnect accounts of a connection in the published app, besides its Admins
openToAnyoneOne entry per place open to anyone: { "target": "endpoint:<rule id>", "quote": "..." } or screen:<screen id>, with the reason the Review tab shows

Nothing is allowed unless a grant allows it, and grants only add up. A visitor who is not signed in never reads a table: a screen open to anyone gets data only through an endpoint open to anyone, and whatever that endpoint answers is public.

Rules

Rules run on Volobox's server, never in the browser. Each one is an entry in rules and a file under rules/.

KeyApplies toMeaning
id, kind, file, descriptionall (required)Stable id; the kind; the file under rules/; one sentence people read on review
entity, operationoperationThe entity, and which write it takes over: create, update or delete
method, routeendpointget, post, put, patch or delete, and a path such as /claims/{id}/submit
calledByOtherSystemsendpointtrue for an endpoint open to anyone that another system calls, such as a webhook
visitorLimits, uploadsendpointHow often one visitor may call it; files sent with the call, by body key
event, fromeventThe event's name, and where it comes from: left out for the app's own events, a uses alias for another app, volobox for a Volobox event
cron, everyMinutesscheduleA five-field cron expression in UTC, such as 0 9 * * 1-5, or a run every so many minutes
kindRuns
operationIn place of the create, update or delete of one table, after Volobox has checked the person's access. Use it to stamp values or refuse with a message
endpointWhen a screen, an Inbox card button, an agent or another system calls it, such as Submit or Approve
eventIn the background, after a rule announces an event, another app's shared event happens, or a Volobox event the app listens to happens
scheduleOn a timetable in UTC. Only the published app's schedules run
backgroundLong work another rule hands off, in batches
JSON
{ "id": "submit", "kind": "endpoint", "method": "post", "route": "/claims/{id}/submit", "file": "rules/submit.js",
  "description": "Sends the person's claim for approval and gives the approver an Inbox card." },
{ "id": "notify-decision", "kind": "event", "event": "claim.decided", "file": "rules/notify-decision.js",
  "description": "Tells the person whether their claim was approved, sent back or rejected." },
{ "id": "approval-reminders", "kind": "schedule", "cron": "0 9 * * 1-5", "file": "rules/approval-reminders.js",
  "description": "Every weekday at 09:00 UTC, reminds each approver of the claims that wait." }

The rule function

A rule's file default-exports an async function that takes one object. Destructure what you need:

JavaScript
export default async function ({ params, db, inbox, currentUser, badRequest, conflict, notFound }) {
  // ...
}

What it gets depends on its kind:

KindGetscurrentUser is
operation, createvalues: the checked values, with field defaults and the owner filled inThe person creating
operation, updateid; values: only the fields sent; previous: the record as storedThe person updating
operation, deleteid; previousThe person deleting
endpointparams (route segments), query, body (JSON, {} when there is none), headers (lower case, never authorization or cookie), rawBody (the text that arrived), form (a form-encoded body), caller ({ app } for another app's call), visitorThe caller; null for a visitor and for another app's call
eventevent (its name), payload, source ({ app } or { volobox: true })The person whose action published it; null for a schedule, a visitor, another app's event and a Volobox event
scheduleNothing moreAlways null

currentUser is { id, name, email }, or null. It is also null for an agent acting as itself; then agent is { id, name }. A rule that needs a person refuses when currentUser is null.

Values arrive in fixed forms: an enum as its value's name, a date as YYYY-MM-DD, a moment as ISO 8601 in UTC, a reference as the record's id.

What every rule gets

MemberUse
db.<Entity>get(id), find(id) (or null), list(filter, { fields, include, limit }) (100 records unless limit says otherwise), count(filter), aggregate({ operation, field, groupBy, dateBucket, filter }), create(values), update(id, values, { version }), delete(id)
clocknow(), today(), addMinutes, addHours, addDays; moments are ISO 8601 in UTC
authisBuilder, hasRole(roleId) for the person running the rule
currentUser, agentWho is acting (above)
appkey, environment (dev or published), peopleWithRole(roleId), endpointUrl(route, query), screenUrl(slug, params)
peopleholders({ platformRoles, roles }) and rolesOf(userId)
eventspublish(name, payload)
apps.<alias>call an endpoint another app shares with this one
voloboxReads Volobox items: get(kind, id) answers the item's fields, or null
utilsformatDate, formatCurrency, daysBetween, toCsv, escapeHtml, sanitizeHtml and more; each takes one object
files, realtime, backgroundStored files, messages to screens listening on a channel, and long work in batches
envPlaceholders for the declared secrets, never their values
httpRequests to other systems' REST APIs (see Call other systems from an app)
connectionsAccounts connected to the app, for http to act as
cryptoverifyHmac, verifySecret, signing and hashing with secrets, randomId()
inbox, notifications, alertsInbox cards, bell notifications and alerts
loglog(...), log.info, log.warn, log.error, log.debug: lines in the rule's run log
userError, ok, created, noContent, badRequest, forbidden, notFound, conflict, redirect, responseRefusals and answers (below)

db writes with the app's own rights: it skips access, may write readOnly and serverOnly fields, and never runs an operation rule. Required fields, validations and uniqueness still apply. db.create does not fill ownerField; set it yourself. An operation rule replaces the write it is for, so a create rule calls db.<Entity>.create(...) itself and returns what it created. Volobox items are read, never written.

Refusals and answers

  • throw userError("...") refuses with a message the person sees, and undoes everything the run wrote.
  • An endpoint answers with a helper: ok(body), created(body), noContent(), badRequest(message), forbidden(message), notFound(message), conflict(message), redirect(app.screenUrl(...)) (a 303 to one of the app's screens) or response(status, body). A plain returned object is the answer's body. Writes are kept only when the answer is below 400.
  • When Volobox itself refuses a write (a value that does not fit its field, a record that does not exist), the person sees that refusal's own message, and nothing the rule wrote is kept.

A POST, PUT, PATCH or DELETE endpoint declares the body it takes, so Volobox checks every call before the rule runs:

JavaScript
export const input = {
  decision: { type: "enum", values: ["approve", "reject"], required: true, description: "What the approver decided." },
  note: { type: "text", maxLength: 500 },
};

export default async function ({ params, body, db }) { /* body.decision is "approve" or "reject" */ }

A field takes type (text, integer, decimal, boolean, date, dateTime, time, enum, reference, file) and optionally required, values, maxLength, min, max and description. Write it as a plain object literal. A call that breaks it answers 400 with { error, errors: [{ field, code, message }] }, and the rule does not run.

An endpoint rule

rules/submit.js from the template, shortened:

JavaScript
export default async function ({ params, db, app, inbox, clock, currentUser, badRequest, conflict, notFound }) {
  const claim = await db.Claim.find(params.id);
  if (!claim || claim.employee !== currentUser?.id) {
    return notFound("You have no claim with that number.");
  }
  if (claim.status !== "draft" && claim.status !== "returned") {
    return conflict(`${claim.number} is already ${claim.status}.`);
  }
  if (!claim.approver || claim.approver === claim.employee) {
    return badRequest("Choose someone else to approve your claim.");
  }

  const today = clock.today();
  await db.Claim.update(claim.id, { status: "submitted", submittedOn: today });

  // The card is named by the claim, so sending it again for a resubmitted claim brings it back.
  await inbox.notify(claim.approver, {
    id: `approve:${claim.id}`,
    title: `${currentUser.name} asks you to approve ${claim.number}`,
    screen: "claim",
    params: { id: claim.id },
    actions: [
      { key: "approve", label: "Approve", variant: "primary", endpoint: "decide", params: { id: claim.id }, body: { decision: "approve" } },
      {
        key: "reject", label: "Reject", variant: "destructive", placement: "menu",
        endpoint: "decide", params: { id: claim.id }, body: { decision: "reject" },
        confirm: "Reject this claim?", input: { field: "note", label: "Why?", required: true },
      },
    ],
  });

  return { status: "submitted", submittedOn: today };
}

Events

An event a rule publishes reaches the app's own event rules. To let a workflow or another app start from it, declare it under events:

JSON
"events": [
  { "name": "request.submitted", "label": "Request submitted", "description": "A requester submitted a draft.", "entity": "Request" }
]
JavaScript
await events.publish("request.submitted", { id: request.id });

With entity, publish the record's id as id. A workflow started by the event (an App event trigger) is told the app, the event and that id, never the rest of the payload, and reads the record with its own access in the app. A draft's events never start a workflow.

Telling people

CallUse it for
notifications.send(to, { title, screen, params })News that needs no answer. Rings the bell
inbox.notify(to, { id, title, subtitle, screen, params, actions, dismissible })Work someone has to do. A card stays until it is resolved and never rings the bell
inbox.update(id, changes) / inbox.resolve(id)Change a pending card quietly; withdraw it when the work is done
alerts.raise({ key, title, summary, severity, to }) / alerts.resolve(key)A condition that holds until someone fixes it, such as low stock

to is a user id, a list, "everyone", or { users, groups, roles, platformRoles }, where platformRoles is "admin", "builder" or "member". A card or notice opens a screen of the app (screen, params) or a Volobox item (ref: { kind, id }, such as volobox.task). A card's actions open a screen, open an item, or run an endpoint as the person who pressed it, under that endpoint's own access. In the draft, cards, notifications and alerts reach only the app's Admins and Builders; in a Builder's test run nothing is sent.

Rules have no email API. To send mail, call a mail service with http.

listens and Volobox events

An app reacts to a Volobox event (a task closed, a pull request merged, a ticket opened) with an event rule "from": "volobox":

JSON
"listens": [{ "event": "task.closed", "description": "Count closed work against its request." }],
"rules": [
  { "id": "on-task-closed", "kind": "event", "from": "volobox", "event": "task.closed", "file": "rules/on-task-closed.js",
    "description": "Marks the request done when its task closes." }
]
JavaScript
// rules/on-task-closed.js
export default async function ({ payload, db, volobox }) {
  const [request] = await db.Request.list({ task: payload.subject.id }, { limit: 1 });
  if (!request || request.status === "done") return; // a second delivery changes nothing
  const task = await volobox.get("task", payload.subject.id);
  await db.Request.update(request.id, { status: "done", closedTitle: task?.label ?? null });
}
payload fieldMeaning
idNames the event; the same on a second delivery
event, occurredAtWhat happened and when
actor{ userId, agentId }
subject{ kind, id, label, number }: the item it is about
scope{ projectId, repositoryId, supportDeskId, appId }
dataThe event's own fields: ids, states and labels, never a message body or description
causation{ workflowRunId, agentRunId, batchId, batchSize }
  • listens says what the app hears, never where. An Admin of the app binds each event under Settings > Volobox events, to every project (repository, desk) or named ones; until then nothing runs. "required": true stops a publish until it is bound.
  • Only the published app hears Volobox. Test a draft rule with Test with a recent event on that settings page.
  • The rule runs with nobody signed in, in a transaction of its own. An event may arrive twice: write the rule so that a second run changes nothing.
  • The events offered are those webhooks receive that belong to a project, repository or support desk. See the event catalog.

Screens

JSON
{ "id": "claims", "slug": "claims", "title": "My claims", "entry": "screens/MyClaims.tsx", "icon": "Receipt" },
{ "id": "claim", "slug": "claim", "title": "Claim", "entry": "screens/ClaimDetail.tsx", "hidden": true, "parent": "claims" }
KeyMeaning
idStable id. access, startPage and parent refer to it
slugThe address segment, unique in the app. dev and build are refused
titleThe title in navigation and the browser tab
entryThe file under screens/ whose default export is the screen
hiddenLeft out of the menu but still opened by a link, such as a detail page
parent, groupWhere the screen sits in navigation
iconAn icon @volobox/ui exports, by name, such as LayoutDashboard

A screen's default export receives AppScreenProps:

TSX
import type { AppScreenProps } from "@volobox/app";
import { Button, PageHeader } from "@volobox/ui";

export default function MyClaims({ sdk, params }: AppScreenProps) {
  async function submit(id: string) {
    try {
      await sdk.data.endpoints.submit({ params: { id } });
      sdk.toast.success("Sent for approval.");
    } catch (error) {
      sdk.toast.error((error as Error).message);
    }
  }
  // ...
}

params holds the values the screen was opened with, as strings. sdk offers:

MemberUse
sdk.datalist(entity, { filters, search, sort, fields, include, skip, limit, total }) answers { items, totalCount }; get, create, update(entity, id, values, { version }), delete, aggregate, upload, fileUrls, export, importTemplate, importFile, access()
sdk.data.endpoints.<rule id>({ params, query, body, headers })Calls an endpoint and returns the body the rule answers with
sdk.currentUser{ id, displayName }; both null for a visitor who is not signed in
sdk.navigate(slug, params)Opens another screen of the app
sdk.toastsuccess, error, info, warning, show({ title, description, variant, duration, action }): a notice to this person only
sdk.peopledisplayNames(userIds), search(query, { limit })
sdk.referencessearch(kind, query, options), get(kind, ids), open(item) for the Volobox items the app's fields refer to
sdk.voloboxVolobox's actions on a record (copy reference, agenda, discussion) and sdk.volobox.v1, Volobox's public API as the person on the screen
sdk.realtimesubscribe(channel, onMessage, { onConnected })
sdk.connectionslist(name), connect(name, { returnTo }), disconnect(id)
sdk.locale{ language, direction, timeZone }
sdk.navigationThe app's menu, for a screen that draws its own
sdk.t(key, values)A text from the app's locales/ file in the person's language

Every refused or failed call throws an AppDataError with message (ready to show), code (such as Volobox:AppPlatform:FieldRequired, or null for an endpoint rule's own error), field and status. Volobox checks access on every call; what a screen hides only spares people a button that would fail.

A screen may import react, @volobox/ui, @volobox/forms, the libraries Volobox runs (@volobox/dates, @volobox/icons, @volobox/echarts, @volobox/radix, @volobox/utils, @volobox/dnd, @volobox/virtual, @volobox/query), types from @volobox/app (with import type), other files under screens/, and packages listed under dependencies in package.json. Any other import fails the build.

Warning: Screen code runs as the viewer

A screen runs signed in as whoever opens it and can do what that person can do in Volobox. With a screen open to anyone, the code of every screen can be read by visitors, though none of their data.

The volobox block

JSON
"volobox": { "access": ["projects", "people"], "levels": { "people": "read" }, "required": ["projects"] }
KeyMeaning
accessThe public API groups the screens call through sdk.volobox.v1: agenda, people, projects, conversations, meetings, files, docs, support, calendar, workspace, audit
levelsPer group, read or readWrite. A group with no level reads and writes
requiredGroups the app cannot work without; a publish stops until an Admin allows them

Listing a group asks; it is allowed under Settings > Volobox access, for the draft and the published app separately: a Builder or Admin allows it for the draft, and only an Admin for the published app. The person on the screen gets only what they could already see and do in Volobox.