Documentation · App Builder
Data
Where an app keeps its data
spec.data holds three lists:
| Key | What it is |
|---|---|
collections | The app's own records: requests, bookings, products, clients… Stored by the runtime, separately for each app. |
jobs | Data jobs on the WebRobot platform whose datasets the app reads. See Data jobs. |
credentials | API keys users connect on their account page, for the agents' HTTP tools. See Agents and automation. |
The runtime has its own collections (users, sign-in tokens, runs, files, chats…). Their names are reserved: a
manifest cannot declare, show or give a tool over any of them. The reserved names are users, login_tokens,
mcp_sessions, credit_ledger, runs, approvals, chats, event_log, instances, scheduled_runs,
scheduler, memory, meta, sessions, outbox, files, file_blobs, credentials, push_devices,
push_log.
Collections
A collection has a name (a key), an optional description, its fields and an owner.
data:
collections:
- name: requests
description: Service requests from clients
ownedBy: user
retentionDays: 365
fields:
- { name: subject, type: text, required: true, maxLength: 120, label: { en: Subject, it: Oggetto } }
- { name: details, type: textarea, label: { en: Details, it: Dettagli } }
- name: status
type: select
default: new
label: { en: Status, it: Stato }
options:
- { value: new, label: { en: New, it: Nuova } }
- { value: done, label: { en: Done, it: Chiusa } }
- { name: consultant_email, type: email, label: { en: Consultant, it: Consulente } }
access:
- { role: consultant, where: { consultant_email: "{user.email}" }, can: [read, write] }
Every reference to a collection elsewhere in the manifest (collection:<name> in a view, a data block, a select, a
role, an agent's context, a tool, a trigger) must name a declared collection. Validation refuses anything else.
Owners: ownedBy
ownedBy decides whose records they are. The default is user.
ownedBy | Whose records | Typical use |
|---|---|---|
user | Each record belongs to the user who created it. | Requests, bookings, a user's projects. |
instance | Each record belongs to one instance of a template (an agent a user created for themselves). | The weekly results of a user's own agent. |
app | One set for the whole app, written by the app's agents and admins, read by everyone. | Results an agent publishes for all users. |
shared | One catalogue everyone reads, kept by the admins. | Products, services, professionals, rooms. |
org | The app owner's back office: admins only. | Contact requests, orders, leads. |
Who reads and writes records
One rule decides access everywhere: views, data blocks, selects, agent tools and agent context.
Reading a record:
- The app's admins read every record.
- Everyone reads records of
appandsharedcollections — visitors who are not signed in included. - A user reads their own records of
userandinstancecollections. - Otherwise, a user reads a record when an
accessrule of the collection gives it to their role.
Records of an org collection are read only by admins and by roles that an access rule names.
Changing a record:
- Admins change every record.
- A user changes their own records of
userandinstancecollections. - Otherwise, only an
accessrule withcan: [write](or[read, write]) lets a role change a record.
Creating a record depends on who creates it and where. See Forms and Agents below.
Access rules
access lists up to 10 rules. Each gives one role a way into the collection beyond its own records.
| Field | Meaning |
|---|---|
role | A role key from auth.roles. A user matches if it is their role, or the sign-up role they keep beside a derived role. |
where | Up to 4 fields the record must match. Without where, the rule covers every record. |
can | [read] (default), [write], or [read, write]. |
In where, "{user.email}" stands for the user's email address and "{user.id}" for their id. When the expected
value is an email address, the record's field may hold one address or a list of them, and the comparison ignores case.
Other values are compared as text.
access:
# a consultant reads and updates the requests assigned to them
- { role: consultant, where: { consultant_email: "{user.email}" }, can: [read, write] }
# a manager reads all requests
- { role: manager }
Validation refuses:
- a rule for a role that does not exist;
- a rule without
wherefor the role users get at sign-up: it would give every record to every user; - on
appandsharedcollections, a rule withoutwrite: everyone reads them already.
Combine access rules with a derived role to give a role to the people a record names.
Record fields the runtime adds
Every record has an id, createdAt and updatedAt. Records a user creates carry their userId. Records saved by a
form also carry submittedBy (the email of the signed-in user who sent it). Agents never see userId in the records
their tools return.
Defaults on new records
A field's default fills a new record that does not carry that field (missing, empty or null). The runtime applies
defaults when a record is created by:
- a form view, including fields the form does not show;
- an admin on the Data page, by hand;
- an agent's tool (
append, orwritewithout an id); - the result of a scheduled or triggered agent saved with
writesTo.
Defaults are not applied to records loaded from a CSV, to bookings, or to records a trigger writes.
A trigger on status: new therefore fires for a record a form created without showing status.
retentionDays
retentionDays (1 to 3650) deletes records older than that many days, counted from createdAt. The runtime purges
once a day, up to 5000 records per collection per day. Files attached to the deleted records are not deleted with
them.
Not used yet
The schema accepts parent, sharing and searchable on a collection. The runtime does not act on them yet.
Fields
A field has a name (^[a-z][a-z0-9_]*$), a type and options. The same field definition is used in collections,
in inputForm (the run form) and in template parameters.
Field types
| Type | In the form | Stored as |
|---|---|---|
text | One-line input | Text |
textarea | Multi-line input | Text |
number | Number input | A number. Anything else is refused: <label>: not a number. |
boolean | Checkbox | true / false. Empty means false. |
select | Drop-down, from options or optionsFrom | The chosen value. A value not in options is refused: <label>: invalid choice <value>. |
multiselect | Checkboxes | A list of values, each checked against options. |
email | Email input | Text. A value that is not an address is refused: <label>: not an email address. |
url | URL input | Text |
urls | One per line | A list |
array | One value per line | A list |
date | Date picker | Text starting with YYYY-MM-DD; anything else is refused: <label>: not a date. |
file | Upload button | File ids. See Files. |
location | "Use my position" button (the phone's GPS in the phone app, the browser elsewhere), or typed | "lat,lng" with 6 decimals, e.g. 45.464200,9.190000. |
barcode | "Scan" button (the camera in the phone app; a photo on the web where the browser can read codes), or typed | Text, one line, at most 512 characters. |
country, city, object, relation, json | One-line input | Text |
The checks of email and date apply to record forms and to the admins' Data page. The run form (inputForm)
stores those values as typed. The other checks apply to both.
Field options
| Option | What it does |
|---|---|
label | The label shown above the input. Translatable. Defaults to the name. |
help | A hint shown inside the empty input. Translatable. |
required | The form refuses to send without a value: <label> is required. A required file needs at least one file. |
default | The value a new form starts with, and the value a new record gets when it lacks the field (see Defaults). |
maxLength | Longest text. The run form refuses longer text (<label>: at most N characters); a record form cuts it at that length. Without maxLength, a record form keeps at most 10,000 characters. |
options | The choices of a select or multiselect: plain strings, or {value, label, gatedBy, parent}. |
optionsFrom | collection:<name> or collection:<name>.<labelField>: the choices are records of that collection. See below. |
dependsOn | The name of another field. Only options whose parent equals that field's value are shown. |
visibleWhen | Shows the field only when a condition on other fields holds. See below. |
roles | Only these roles see the field. |
gatedBy | A plan or pack key that unlocks the field (or, on an option, that option). See Billing. |
roles, gatedBy, dependsOn and visibleWhen are checked again by the server for the run form (inputForm).
In a record form (a form view) they only change what the browser shows.
Conditions in visibleWhen
A condition is one or more comparisons joined by && (and) and || (or):
field == 'value'/field != 'value'— the value in single quotes;field— the field has a value;!field— it has none.
Anything else counts as false. Example: mode == 'market' && budget.
Choices from a collection: optionsFrom
- name: client
type: select
required: true
label: { en: Client, it: Cliente }
optionsFrom: collection:clients.company_name
- The choices are the records of the collection that this user may read, newest first, up to 200.
- The stored value is the record's
id. The label is the field after the dot; without it, the first ofname,full_name,title,label,display_name,company_name,company,subject,item,codethat has text, else the first text field of the record. - When there is nothing to choose, the form says "Nothing to choose yet." with a link to the first form view this user can open that adds to that collection, or says an administrator has to add one first.
- The server checks the value: an id of a record the user may not read is refused (
<field>: not one of your <collection>).
optionsFrom: job:<key> is accepted by the schema but not filled by the runtime yet.
Not used yet
The schema accepts fields (sub-fields of an object or array) and relation (a target collection). The runtime
does not use them yet: such fields are entered as plain text.
Files
A field of type file lets a signed-in user upload files. Visitors who are not signed in cannot upload.
| Option | Default | Meaning |
|---|---|---|
accept | pdf, docx, xlsx, csv, txt, jpg, jpeg, png, webp | Accepted extensions. Also allowed: md, json, html, xml, gif. Up to 12. |
maxMb | 10 | Largest file, in MB. At most 15. |
multiple | false | Up to 10 files. |
extract | text | text: the text of PDF, Word, Excel, CSV and text files is extracted for the agent. none: no extraction. |
capture | — | A photo taken with the camera: images only, made smaller before upload. In the phone app, the native camera. |
What happens on upload:
- The file is uploaded as soon as it is chosen, before the form is sent.
- The server checks the extension, the size, and that the content really is that kind of file (a renamed program is
not a PDF). Errors:
this field accepts …,the file is larger than N MB,the file is not a valid <ext>,empty file. - Text is extracted (up to 60,000 characters per file). Images have no text.
- The file is stored in the app's own store. The form keeps its id.
Who can download a file: the user who uploaded it, and the app's admins. Nobody else — not even a role an access rule gives the record to. Files download as attachments.
For agents: a run's goal gets {<field>} (the file names) and {<field>_text} (the extracted text, 30,000
characters at most across all files). An agent reads a file — and sees an image — with an app tool
{action: read_file}. See Agents and automation.
Who may create records with a form
A view of type form saves records into its collection. See Views for the view itself.
Collection ownedBy | Who may create a record |
|---|---|
user | Any signed-in user who can open the form. The record is theirs. |
org | Any signed-in user who can open the form, and visitors if the form is open to them. Only admins (and access rules) read the records: an inbox. |
app, shared | Admins only. Others get only the app's admins add to this collection. |
instance | Nobody: an instance's records are written by its agent. |
Visitors may send at most 5 submissions per hour from one network address to one form.
With edit: true, opening the form as /v/<key>?id=<record id> changes that record, if the user may change it (see
Who reads and writes records).
Every saved record is an app event: triggers on that collection fire. See Agents and automation.
What agents may read and write
Agents reach collections through app tools (read, search, show, write, append). The full description of
tools is in Agents and automation; the data rules are:
- A tool over a
userorinstancecollection is tied to the user the agent works for: the agent must pass the app session it gets in its task. It reads and changes that user's records, plus those the collection's access rules give the user's role. New records are stamped with that user. - A tool over an
app,sharedororgcollection acts for the whole app, unless the tool setsscope: userorscope: session. It reads every record and may create and change records. - An agent visitors use without signing in gets no tool over an
orgcollection, and cannot write toapporsharedcollections. Validation refuses such tools, and the runtime refuses the call. readwithout an id returns up to 50 records, newest first.searchandshowreturn up to 100 (default 20).- Agent context (
context: [{key, from: collection:<name>}]) gives the agent the records the user may read, up to 30 records and 8,000 characters.
Limits on new records
A limit with action: create:<collection> caps how many records one user creates in a collection:
limits:
- { action: create:listings, max: 3, window: total, plans: { pro: 50, agency: -1 } }
window:minute,hour,day,month(30 days) ortotal(ever: a quota).- The count is the user's own records in the collection created in that window.
- It applies to records created through forms and through agent tools. Admins are exempt.
permust beuser(the default); other values are not applied to this kind of limit.plansraises the limit per plan or pack (-1= no limit) for records created by agent tools. Forms always usemax.rolesis not applied tocreate:limits.
When the limit is reached the user sees limit reached: ….
The admins' data page
Admins have a Data link in the header (/admin/data) when the app has at least one collection owned by
shared, app or org. Records of users (user, instance) are not on this page: they belong to the users.
The page has one tab per collection, and for the chosen one:
- Add a record / Edit the record: a form with all the collection's fields except file fields. The same checks as a form apply. Saving fires triggers like any form.
- Import from CSV: see below.
- Records: up to 200 records, newest first, with the first 6 fields as columns, each with Edit and Delete (after a confirmation).
The page also lists the last agents that could not start, with the reason.
Importing a CSV
- Download the template: an empty CSV whose header names the fields.
- Fill it in a spreadsheet and choose the file.
The import rules:
- The header names the fields, by name or by label, ignoring case. Columns that match no field are ignored.
- Comma or semicolon, whichever the header uses. Quotes as in standard CSV.
- At most 2000 rows and 5 MB per import.
- Values are read as people write them:
yes,sì,true,1,xare true;1.200,5and1200,5are numbers; a select takes its value or its label; a multiselect takes values separated by|or,. - Each row is checked like a form. Invalid rows are skipped; the page reports how many were imported and skipped, with the first 20 errors.
- Importing does not fire triggers: a thousand rows do not start a thousand agents or emails. Field defaults are not applied either.
Export to CSV
A view of type table, list or cards with export: true shows a Download CSV link under its rows, when there
are rows. The file
holds the rows that view shows to this user, with the view's fields as columns (all fields when the view names none,
without userId).
- UTF-8 with a byte-order mark, so spreadsheets read accents.
- Cells that a spreadsheet would run as a formula (starting with
=,+,-,@) start with an apostrophe. - At most 200 rows.
- Rows reserved to a plan are not exported: a user without the plan gets
this data needs a plan.
Data blocks
A data block shows rows on a page. It is a section of type data in a page view, and the same mechanism powers the
table, cards, list and chart views (see Views).
- type: data
title: { en: Open requests, it: Richieste aperte }
source: collection:requests
display: table
fields:
- { key: subject }
- { key: status, format: badge }
- { key: createdAt, label: { en: Sent, it: Inviata }, format: date }
filters:
- { field: status, op: "!=", value: done }
sort: { field: createdAt, dir: desc }
limit: 20
empty: { en: No open requests., it: Nessuna richiesta aperta. }
Sources
source | Rows |
|---|---|
collection:<name> | The records of the collection this user may read (see Who reads and writes records). |
job:<key> | The latest dataset of a data job. |
run | The signed-in user's own runs: title, status, createdAt, finishedAt, agent, chargedCredits, and the form values. Visitors get no rows. |
catalog or catalog:<category> | The platform's public catalog of sources. |
Rows from jobs and from the catalog are cached for one minute.
path turns a list inside each row into rows, e.g. path: assets shows each item of each row's assets list.
Display
display | What it shows |
|---|---|
table | A table, one column per field. |
cards | One card per row: the first field as heading, the others below with their labels. |
list | One line per row: the first field in bold, the others after it. |
kpi | Key numbers from kpis (up to 6), computed over the rows the block loaded (after filters and limit). Without kpis: the number of rows. |
bar | Horizontal bars: the first field is the label, the second the value. |
chart | A chart of type chart: bar, line, pie or stacked. The first field gives the labels, the others the series. |
Fields and formats
fields (up to 12) are the columns, each {key, label, format}. key may be a dot path (price.amount). Without
fields, the block shows the first 6 field names found in the rows — usually not what you want: list the fields.
format | Shows |
|---|---|
text (or none) | The value. A "lat,lng" position becomes a map link. |
number | A number with up to 2 decimals, in the page's locale. |
money | An amount in the app's billing.currency (default EUR), no decimals. |
percent | +12.5%, green when positive, red when negative. |
ratio | A fraction as a percentage: 0.25 shows +25%. |
date | A date, e.g. 05 Mar 2026. |
link | A link, for https:// addresses only. |
badge | The value in a badge. |
location | A map link for a "lat,lng" position. |
On a collection source:
- a field without
labeltakes the label of the collection's field; - the value of a
selectfield shows its option's label in the reader's language ("new" → "Nuova").
In a table, a long text (over 220 characters, such as an agent's Markdown report) shows as a plain-text excerpt; the
whole text appears on hover. This applies to fields with no format or format text.
Filters, sort and limit
filters(up to 8):{field, op, value}.=and!=compare as text.>,>=,<,<=compare numbers; rows whose value is not a number are left out.containslooks for the text, ignoring case.sort:{field, dir}. Numbers sort as numbers, other values as text.dirisascordesc; the default isdesc.limit: 1 to 200 rows. Default 50.
Key numbers: kpis
Each KPI is {label, agg, field, format}. agg is count, sum, avg, min, max or last (the first
non-empty value in the rows, after sorting: with the default desc sort on a date, the latest).
- type: data
source: collection:requests
display: kpi
kpis:
- { label: { en: Requests, it: Richieste }, agg: count }
- { label: { en: Average budget, it: Budget medio }, agg: avg, field: budget, format: money }
Grouping: groupBy
groupBy makes one row per value of a field, with aggregates as columns:
groupBy:
field: createdAt
bucket: week # day, week (from Monday) or month, for dates
aggs:
- { key: total, agg: sum, field: amount }
minCount: 5 # groups with fewer rows are hidden
Every group row also has count. Use the field and the agg keys in fields.
With acrossUsers: true on a collection ownedBy: user, the block aggregates the records of every user, not only
the reader's. Only the aggregates are shown, never a record. It needs minCount of at least 5, so no group can single
out one user. Validation refuses it otherwise.
Teasers: preview
preview: {rows, unlessPlan} shows users without the plan unlessPlan only the first rows rows (default 3), then
"N more rows with the plan.". Record buttons are hidden in a teaser. Admins see everything.
Record buttons: actions
actions (up to 4) adds buttons to each row: call, directions, share, add to calendar. See
Views.
When there are no rows
A block with no rows shows empty, or "No data yet.". A source that cannot be read shows "Data not available right
now." A job: source whose job is not linked shows "Job not linked.".
Data jobs
spec.data.jobs lists data jobs of the WebRobot platform that the app uses. A job is linked by its projectId and
jobId.
data:
jobs:
- key: prices
description: Daily prices from the partner shops
projectId: 812
jobId: 4410
What the runtime does with a linked job:
- a data block or view with
source: job:<key>reads the latest dataset the job produced. The runtime builds the query from the block's fields, filters, sort and limit; numbers stored as text are compared as numbers; - a schedule or a trigger can start the job. See Agents and automation.
A job without projectId and jobId is not linked: blocks show "Job not linked." and schedules skip it.
The schema also accepts pipeline, params, perRecord, schedule and ingestTo on a job. The runtime does not
act on them yet.