WebRobot
App Builder · pages

Documentation · App Builder

Data

Where an app keeps its data

spec.data holds three lists:

KeyWhat it is
collectionsThe app's own records: requests, bookings, products, clients… Stored by the runtime, separately for each app.
jobsData jobs on the WebRobot platform whose datasets the app reads. See Data jobs.
credentialsAPI 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.

ownedByWhose recordsTypical use
userEach record belongs to the user who created it.Requests, bookings, a user's projects.
instanceEach record belongs to one instance of a template (an agent a user created for themselves).The weekly results of a user's own agent.
appOne set for the whole app, written by the app's agents and admins, read by everyone.Results an agent publishes for all users.
sharedOne catalogue everyone reads, kept by the admins.Products, services, professionals, rooms.
orgThe 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:

  1. The app's admins read every record.
  2. Everyone reads records of app and shared collections — visitors who are not signed in included.
  3. A user reads their own records of user and instance collections.
  4. Otherwise, a user reads a record when an access rule 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:

  1. Admins change every record.
  2. A user changes their own records of user and instance collections.
  3. Otherwise, only an access rule with can: [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.

FieldMeaning
roleA role key from auth.roles. A user matches if it is their role, or the sign-up role they keep beside a derived role.
whereUp 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 where for the role users get at sign-up: it would give every record to every user;
  • on app and shared collections, a rule without write: 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, or write without 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

TypeIn the formStored as
textOne-line inputText
textareaMulti-line inputText
numberNumber inputA number. Anything else is refused: <label>: not a number.
booleanCheckboxtrue / false. Empty means false.
selectDrop-down, from options or optionsFromThe chosen value. A value not in options is refused: <label>: invalid choice <value>.
multiselectCheckboxesA list of values, each checked against options.
emailEmail inputText. A value that is not an address is refused: <label>: not an email address.
urlURL inputText
urlsOne per lineA list
arrayOne value per lineA list
dateDate pickerText starting with YYYY-MM-DD; anything else is refused: <label>: not a date.
fileUpload buttonFile 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 typedText, one line, at most 512 characters.
country, city, object, relation, jsonOne-line inputText

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

OptionWhat it does
labelThe label shown above the input. Translatable. Defaults to the name.
helpA hint shown inside the empty input. Translatable.
requiredThe form refuses to send without a value: <label> is required. A required file needs at least one file.
defaultThe value a new form starts with, and the value a new record gets when it lacks the field (see Defaults).
maxLengthLongest 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.
optionsThe choices of a select or multiselect: plain strings, or {value, label, gatedBy, parent}.
optionsFromcollection:<name> or collection:<name>.<labelField>: the choices are records of that collection. See below.
dependsOnThe name of another field. Only options whose parent equals that field's value are shown.
visibleWhenShows the field only when a condition on other fields holds. See below.
rolesOnly these roles see the field.
gatedByA 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 of name, full_name, title, label, display_name, company_name, company, subject, item, code that 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.

OptionDefaultMeaning
acceptpdf, docx, xlsx, csv, txt, jpg, jpeg, png, webpAccepted extensions. Also allowed: md, json, html, xml, gif. Up to 12.
maxMb10Largest file, in MB. At most 15.
multiplefalseUp to 10 files.
extracttexttext: 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:

  1. The file is uploaded as soon as it is chosen, before the form is sent.
  2. 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.
  3. Text is extracted (up to 60,000 characters per file). Images have no text.
  4. 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 ownedByWho may create a record
userAny signed-in user who can open the form. The record is theirs.
orgAny 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, sharedAdmins only. Others get only the app's admins add to this collection.
instanceNobody: 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 user or instance collection 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, shared or org collection acts for the whole app, unless the tool sets scope: user or scope: session. It reads every record and may create and change records.
  • An agent visitors use without signing in gets no tool over an org collection, and cannot write to app or shared collections. Validation refuses such tools, and the runtime refuses the call.
  • read without an id returns up to 50 records, newest first. search and show return 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) or total (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.
  • per must be user (the default); other values are not applied to this kind of limit.
  • plans raises the limit per plan or pack (-1 = no limit) for records created by agent tools. Forms always use max.
  • roles is not applied to create: 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

  1. Download the template: an empty CSV whose header names the fields.
  2. 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, x are true; 1.200,5 and 1200,5 are 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

sourceRows
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.
runThe 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

displayWhat it shows
tableA table, one column per field.
cardsOne card per row: the first field as heading, the others below with their labels.
listOne line per row: the first field in bold, the others after it.
kpiKey numbers from kpis (up to 6), computed over the rows the block loaded (after filters and limit). Without kpis: the number of rows.
barHorizontal bars: the first field is the label, the second the value.
chartA 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.

formatShows
text (or none)The value. A "lat,lng" position becomes a map link.
numberA number with up to 2 decimals, in the page's locale.
moneyAn amount in the app's billing.currency (default EUR), no decimals.
percent+12.5%, green when positive, red when negative.
ratioA fraction as a percentage: 0.25 shows +25%.
dateA date, e.g. 05 Mar 2026.
linkA link, for https:// addresses only.
badgeThe value in a badge.
locationA map link for a "lat,lng" position.

On a collection source:

  • a field without label takes the label of the collection's field;
  • the value of a select field 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. contains looks for the text, ignoring case.
  • sort: {field, dir}. Numbers sort as numbers, other values as text. dir is asc or desc; the default is desc.
  • 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.