Formats
ReferenceApp 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
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 handAny 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.
| Key | Type | Meaning |
|---|---|---|
$schema | string | Optional path or URL of the schema, for editors. Volobox ignores it |
version | integer | Format version. Always 1 |
name | string | The app's name. People see the Name on the app's Settings; Volobox writes that name here when it saves the files |
description | string | One or two sentences on what the app is for |
roles | array | The app's own roles (see Roles and audiences) |
enums | array | Named value lists that enum fields use |
entities | array | The record types the app stores. Each becomes a table |
rules | array | Server-side JavaScript: operations, endpoints, event handlers and schedules |
access | object | Who may do what, per entity, endpoint and screen |
screens | array | The app's pages, each a React component |
startPage | string | Id of the screen the app opens on. Defaults to the first screen that is not hidden |
navigation | string | Who draws the navigation: shell (Volobox, the default) or screens (the app, with AppNav) |
menu | object | The menu's layout: items in order (screens, sections, folders, separators, links to other Volobox pages) and footer |
languages | object | { "default": "en", "supported": ["en", "tr"] }; each supported language has locales/<language>.json |
events | array | The events this app announces outside itself, so workflows can start from them |
shares | array | What this app offers other apps: records to read, events to handle, endpoints to call |
uses | array | Other apps' shares this app reads, each under an alias |
secrets | array | Credentials the rules send to other systems, read as env.<NAME> |
connections | array | Kinds of accounts at other services that people connect, for rules to act as |
listens | array | The Volobox events the app's rules react to |
volobox | object | The 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:
memberuses the published app,builderalso builds the draft and publishes (and reads and changes every record, whateveraccesssays),adminalso 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
rolesand assigned under Settings > Roles. They only add to what a member may do.
"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:
| Audience | Who |
|---|---|
A role id, such as approver | The people and groups who hold that app role |
everyone | Every member of the app, whatever app roles they hold (everyone in the workspace when the app is public) |
anyone | Also 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
{
"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
| Key | Meaning |
|---|---|
id | Stable id, lowercase with dashes. Keep it when the entity is renamed |
name | PascalCase singular name, such as Claim. Fields, rules and access refer to it |
label, pluralLabel, description | How people see it |
displayField | The field that names a record in lists, pickers and references |
ownerField | A reference-to-user field that says whose record it is. scope: "own" compares it with the signed-in person |
fields | The entity's fields |
validations | Checks that compare two fields of the same record |
volobox | How 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
type | Holds |
|---|---|
text | Text, optionally with maxLength, minLength, pattern or format (email, phone, url) |
integer, decimal | Numbers, with min, max and, for decimal, scale |
money | An amount with currency (an ISO 4217 code such as EUR) and scale |
boolean | Yes or no |
date, dateTime, time | A day (YYYY-MM-DD), a moment (ISO 8601 in UTC), a time of day (HH:MM) |
enum | One value of the enum named in enum |
reference | A 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, image | A stored file, optionally limited by allowedContentTypes (and image dimensions) |
list | A list of itemType values (text, integer, decimal, boolean, date or enum), with maxCount and uniqueItems |
formula | A computed value: a Power Fx expression over the record's fields, with a resultType |
rollup | A summary of another entity's records: source, via (its reference field), operation (count, sum, average, min, max) and value |
secret | A credential each record holds, stored encrypted and never read back |
Field options
| Option | Meaning |
|---|---|
id, name | Stable id (lowercase with dashes) and camelCase name |
label, description | How people and agents see the field |
required | A record cannot be saved without a value |
unique | No two records hold the same value |
default | The value a new record starts with |
readOnly | Only rules write it |
serverOnly | Never leaves the server: rules read and write it, screens never see it |
onDelete | For a reference to the app's own entity: restrict (default), cascade or setNull |
scopedBy | For a Volobox item with a parent, such as volobox.milestone: the field holding the parent, so the picker offers only its items |
{
"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
| Key | Meaning |
|---|---|
screen | Id of the screen a record opens on in Volobox. It receives the record's id in the query parameter param |
param | The camelCase query parameter name. Defaults to id |
copyReference | People may copy a record's reference into chats, tasks and documents |
agenda | People may add a record to their Volobox agenda |
discussion | Each 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
"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"] }
}| Key | Meaning |
|---|---|
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 |
openToAnyone | One 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/.
| Key | Applies to | Meaning |
|---|---|---|
id, kind, file, description | all (required) | Stable id; the kind; the file under rules/; one sentence people read on review |
entity, operation | operation | The entity, and which write it takes over: create, update or delete |
method, route | endpoint | get, post, put, patch or delete, and a path such as /claims/{id}/submit |
calledByOtherSystems | endpoint | true for an endpoint open to anyone that another system calls, such as a webhook |
visitorLimits, uploads | endpoint | How often one visitor may call it; files sent with the call, by body key |
event, from | event | The 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, everyMinutes | schedule | A five-field cron expression in UTC, such as 0 9 * * 1-5, or a run every so many minutes |
kind | Runs |
|---|---|
operation | In 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 |
endpoint | When a screen, an Inbox card button, an agent or another system calls it, such as Submit or Approve |
event | In the background, after a rule announces an event, another app's shared event happens, or a Volobox event the app listens to happens |
schedule | On a timetable in UTC. Only the published app's schedules run |
background | Long work another rule hands off, in batches |
{ "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:
export default async function ({ params, db, inbox, currentUser, badRequest, conflict, notFound }) {
// ...
}What it gets depends on its kind:
| Kind | Gets | currentUser is |
|---|---|---|
operation, create | values: the checked values, with field defaults and the owner filled in | The person creating |
operation, update | id; values: only the fields sent; previous: the record as stored | The person updating |
operation, delete | id; previous | The person deleting |
endpoint | params (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), visitor | The caller; null for a visitor and for another app's call |
event | event (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 |
schedule | Nothing more | Always 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
| Member | Use |
|---|---|
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) |
clock | now(), today(), addMinutes, addHours, addDays; moments are ISO 8601 in UTC |
auth | isBuilder, hasRole(roleId) for the person running the rule |
currentUser, agent | Who is acting (above) |
app | key, environment (dev or published), peopleWithRole(roleId), endpointUrl(route, query), screenUrl(slug, params) |
people | holders({ platformRoles, roles }) and rolesOf(userId) |
events | publish(name, payload) |
apps.<alias> | call an endpoint another app shares with this one |
volobox | Reads Volobox items: get(kind, id) answers the item's fields, or null |
utils | formatDate, formatCurrency, daysBetween, toCsv, escapeHtml, sanitizeHtml and more; each takes one object |
files, realtime, background | Stored files, messages to screens listening on a channel, and long work in batches |
env | Placeholders for the declared secrets, never their values |
http | Requests to other systems' REST APIs (see Call other systems from an app) |
connections | Accounts connected to the app, for http to act as |
crypto | verifyHmac, verifySecret, signing and hashing with secrets, randomId() |
inbox, notifications, alerts | Inbox cards, bell notifications and alerts |
log | log(...), log.info, log.warn, log.error, log.debug: lines in the rule's run log |
userError, ok, created, noContent, badRequest, forbidden, notFound, conflict, redirect, response | Refusals 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) orresponse(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:
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:
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:
"events": [
{ "name": "request.submitted", "label": "Request submitted", "description": "A requester submitted a draft.", "entity": "Request" }
]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
| Call | Use 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":
"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." }
]// 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 field | Meaning |
|---|---|
id | Names the event; the same on a second delivery |
event, occurredAt | What happened and when |
actor | { userId, agentId } |
subject | { kind, id, label, number }: the item it is about |
scope | { projectId, repositoryId, supportDeskId, appId } |
data | The event's own fields: ids, states and labels, never a message body or description |
causation | { workflowRunId, agentRunId, batchId, batchSize } |
listenssays 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": truestops 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
{ "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" }| Key | Meaning |
|---|---|
id | Stable id. access, startPage and parent refer to it |
slug | The address segment, unique in the app. dev and build are refused |
title | The title in navigation and the browser tab |
entry | The file under screens/ whose default export is the screen |
hidden | Left out of the menu but still opened by a link, such as a detail page |
parent, group | Where the screen sits in navigation |
icon | An icon @volobox/ui exports, by name, such as LayoutDashboard |
A screen's default export receives AppScreenProps:
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:
| Member | Use |
|---|---|
sdk.data | list(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.toast | success, error, info, warning, show({ title, description, variant, duration, action }): a notice to this person only |
sdk.people | displayNames(userIds), search(query, { limit }) |
sdk.references | search(kind, query, options), get(kind, ids), open(item) for the Volobox items the app's fields refer to |
sdk.volobox | Volobox's actions on a record (copy reference, agenda, discussion) and sdk.volobox.v1, Volobox's public API as the person on the screen |
sdk.realtime | subscribe(channel, onMessage, { onConnected }) |
sdk.connections | list(name), connect(name, { returnTo }), disconnect(id) |
sdk.locale | { language, direction, timeZone } |
sdk.navigation | The 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
"volobox": { "access": ["projects", "people"], "levels": { "people": "read" }, "required": ["projects"] }| Key | Meaning |
|---|---|
access | The public API groups the screens call through sdk.volobox.v1: agenda, people, projects, conversations, meetings, files, docs, support, calendar, workspace, audit |
levels | Per group, read or readWrite. A group with no level reads and writes |
required | Groups 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.