WebRobot
App Builder · pagine

Documentazione · App Builder

Dati

Dove un'app tiene i suoi dati

spec.data contiene tre liste:

ChiaveCos'è
collectionsI record propri dell'app: richieste, prenotazioni, prodotti, clienti… Memorizzati dal runtime, separatamente per ogni app.
jobsJob di dati sulla piattaforma WebRobot di cui l'app legge i dataset. Vedi Job di dati.
credentialsChiavi API che gli utenti collegano nella pagina del loro account, per gli strumenti HTTP degli agenti. Vedi Agenti e automazione.

Il runtime ha raccolte proprie (utenti, token di accesso, esecuzioni, file, chat…). I loro nomi sono riservati: un manifest non può dichiararle, mostrarle né dare uno strumento su nessuna di esse. I nomi riservati sono 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.

Raccolte

Una raccolta ha un name (una chiave), una description facoltativa, i suoi fields e un proprietario.

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] }

Ogni riferimento a una raccolta altrove nel manifest (collection:<name> in una vista, un blocco di dati, una select, un ruolo, il contesto di un agente, uno strumento, un trigger) deve indicare una raccolta dichiarata. La validazione rifiuta qualsiasi altro valore.

Proprietari: ownedBy

ownedBy decide di chi sono i record. Il valore predefinito è user.

ownedByDi chi sono i recordUso tipico
userOgni record appartiene all'utente che l'ha creato.Richieste, prenotazioni, i progetti di un utente.
instanceOgni record appartiene a un'istanza di un modello (un agente che un utente ha creato per sé).I risultati settimanali dell'agente personale di un utente.
appUn unico insieme per tutta l'app, scritto dagli agenti e dagli amministratori dell'app, letto da tutti.Risultati che un agente pubblica per tutti gli utenti.
sharedUn unico catalogo che tutti leggono, gestito dagli amministratori.Prodotti, servizi, professionisti, sale.
orgIl back office del proprietario dell'app: solo amministratori.Richieste di contatto, ordini, lead.

Chi legge e scrive i record

Una sola regola decide l'accesso ovunque: viste, blocchi di dati, select, strumenti degli agenti e contesto degli agenti.

Leggere un record:

  1. Gli amministratori dell'app leggono ogni record.
  2. Tutti leggono i record delle raccolte app e shared, compresi i visitatori senza accesso.
  3. Un utente legge i propri record delle raccolte user e instance.
  4. Altrimenti, un utente legge un record quando una regola access della raccolta lo concede al suo ruolo.

I record di una raccolta org sono letti solo dagli amministratori e dai ruoli indicati da una regola di accesso.

Modificare un record:

  1. Gli amministratori modificano ogni record.
  2. Un utente modifica i propri record delle raccolte user e instance.
  3. Altrimenti, solo una regola access con can: [write] (o [read, write]) consente a un ruolo di modificare un record.

Creare un record dipende da chi lo crea e dove. Vedi Moduli e Agenti più sotto.

Regole di accesso

access elenca fino a 10 regole. Ognuna dà a un ruolo un accesso alla raccolta oltre ai propri record.

CampoSignificato
roleUna chiave di ruolo da auth.roles. Un utente corrisponde se è il suo ruolo, o il ruolo di registrazione che conserva accanto a un ruolo derivato.
whereFino a 4 campi a cui il record deve corrispondere. Senza where, la regola copre ogni record.
can[read] (predefinito), [write] o [read, write].

In where, "{user.email}" indica l'indirizzo email dell'utente e "{user.id}" il suo id. Quando il valore atteso è un indirizzo email, il campo del record può contenere un indirizzo o un elenco di indirizzi, e il confronto ignora maiuscole e minuscole. Gli altri valori si confrontano come testo.

access:
  # un consulente legge e aggiorna le richieste assegnate a lui
  - { role: consultant, where: { consultant_email: "{user.email}" }, can: [read, write] }
  # un responsabile legge tutte le richieste
  - { role: manager }

La validazione rifiuta:

  • una regola per un ruolo che non esiste;
  • una regola senza where per il ruolo che gli utenti ricevono alla registrazione: darebbe ogni record a ogni utente;
  • sulle raccolte app e shared, una regola senza write: tutti le leggono già.

Combina le regole di accesso con un ruolo derivato per dare un ruolo alle persone indicate in un record.

Campi aggiunti dal runtime

Ogni record ha un id, createdAt e updatedAt. I record creati da un utente portano il suo userId. I record salvati da un modulo portano anche submittedBy (l'email dell'utente con accesso che l'ha inviato). Gli agenti non vedono mai userId nei record restituiti dai loro strumenti.

Valori predefiniti dei nuovi record

Il default di un campo riempie un nuovo record che non porta quel campo (mancante, vuoto o nullo). Il runtime applica i valori predefiniti quando un record viene creato da:

  • una vista modulo, compresi i campi che il modulo non mostra;
  • un amministratore nella pagina Data, a mano;
  • uno strumento di un agente (append, o write senza id);
  • il risultato di un agente pianificato o avviato da un trigger, salvato con writesTo.

I valori predefiniti non si applicano ai record caricati da un CSV, alle prenotazioni o ai record scritti da un trigger.

Un trigger su status: new scatta quindi anche per un record che un modulo ha creato senza mostrare status.

retentionDays

retentionDays (da 1 a 3650) elimina i record più vecchi di quel numero di giorni, contati da createdAt. Il runtime fa pulizia una volta al giorno, fino a 5000 record per raccolta al giorno. I file allegati ai record eliminati non vengono eliminati con loro.

Non ancora usati

Lo schema accetta parent, sharing e searchable su una raccolta. Il runtime non li usa ancora.

Campi

Un campo ha un name (^[a-z][a-z0-9_]*$), un type e delle opzioni. La stessa definizione di campo si usa nelle raccolte, in inputForm (il modulo di esecuzione) e nei parametri dei modelli.

Tipi di campo

TipoNel moduloMemorizzato come
textInput su una rigaTesto
textareaInput su più righeTesto
numberInput numericoUn numero. Qualsiasi altro valore è rifiutato: <label>: not a number.
booleanCasella di spuntatrue / false. Vuoto significa false.
selectMenu a tendina, da options o optionsFromIl valore scelto. Un valore che non è in options è rifiutato: <label>: invalid choice <value>.
multiselectCaselle di spuntaUn elenco di valori, ognuno verificato rispetto a options.
emailInput emailTesto. Un valore che non è un indirizzo è rifiutato: <label>: not an email address.
urlInput URLTesto
urlsUno per rigaUn elenco
arrayUn valore per rigaUn elenco
dateSelettore di dataTesto che inizia con YYYY-MM-DD; qualsiasi altro valore è rifiutato: <label>: not a date.
filePulsante di caricamentoId di file. Vedi File.
locationPulsante "Use my position" (il GPS del telefono nell'app per telefono, il browser altrove), o scritto a mano"lat,lng" con 6 decimali, es. 45.464200,9.190000.
barcodePulsante "Scan" (la fotocamera nell'app per telefono; una foto sul web dove il browser sa leggere i codici), o scritto a manoTesto, una riga, al massimo 512 caratteri.
country, city, object, relation, jsonInput su una rigaTesto

I controlli di email e date si applicano ai moduli dei record e alla pagina Data degli amministratori. Il modulo di esecuzione (inputForm) memorizza quei valori così come sono scritti. Gli altri controlli si applicano a entrambi.

Opzioni dei campi

OpzioneCosa fa
labelL'etichetta mostrata sopra l'input. Traducibile. Il valore predefinito è il nome.
helpUn suggerimento mostrato dentro l'input vuoto. Traducibile.
requiredIl modulo rifiuta l'invio senza un valore: <label> is required. Un file obbligatorio richiede almeno un file.
defaultIl valore con cui parte un nuovo modulo, e il valore che riceve un nuovo record a cui manca il campo (vedi Valori predefiniti).
maxLengthLunghezza massima del testo. Il modulo di esecuzione rifiuta un testo più lungo (<label>: at most N characters); un modulo di record lo tronca a quella lunghezza. Senza maxLength, un modulo di record conserva al massimo 10.000 caratteri.
optionsLe scelte di una select o multiselect: stringhe semplici, o {value, label, gatedBy, parent}.
optionsFromcollection:<name> o collection:<name>.<labelField>: le scelte sono i record di quella raccolta. Vedi sotto.
dependsOnIl nome di un altro campo. Sono mostrate solo le opzioni il cui parent è uguale al valore di quel campo.
visibleWhenMostra il campo solo quando vale una condizione su altri campi. Vedi sotto.
rolesSolo questi ruoli vedono il campo.
gatedByLa chiave di un piano o di un pacchetto che sblocca il campo (o, su un'opzione, quell'opzione). Vedi Pagamenti e crediti.

roles, gatedBy, dependsOn e visibleWhen vengono verificati di nuovo dal server per il modulo di esecuzione (inputForm). In un modulo di record (una vista form) cambiano solo ciò che mostra il browser.

Condizioni in visibleWhen

Una condizione è uno o più confronti uniti da && (e) e || (o):

  • field == 'value' / field != 'value': il valore tra apici singoli;
  • field: il campo ha un valore; !field: non ne ha.

Qualsiasi altra cosa vale come falsa. Esempio: mode == 'market' && budget.

Scelte da una raccolta: optionsFrom

- name: client
  type: select
  required: true
  label: { en: Client, it: Cliente }
  optionsFrom: collection:clients.company_name
  • Le scelte sono i record della raccolta che questo utente può leggere, dai più recenti, fino a 200.
  • Il valore memorizzato è l'id del record. L'etichetta è il campo dopo il punto; senza di esso, il primo tra name, full_name, title, label, display_name, company_name, company, subject, item, code che contiene testo, altrimenti il primo campo di testo del record.
  • Quando non c'è niente da scegliere, il modulo dice "Nothing to choose yet." con un link alla prima vista modulo che questo utente può aprire e che aggiunge record a quella raccolta, oppure dice che prima un amministratore deve aggiungerne uno.
  • Il server verifica il valore: l'id di un record che l'utente non può leggere è rifiutato (<field>: not one of your <collection>).

optionsFrom: job:<key> è accettato dallo schema ma il runtime non lo riempie ancora.

Non ancora usati

Lo schema accetta fields (sottocampi di un object o array) e relation (una raccolta di destinazione). Il runtime non li usa ancora: questi campi si inseriscono come testo semplice.

File

Un campo di tipo file consente a un utente con accesso di caricare file. I visitatori senza accesso non possono caricare.

OpzionePredefinitoSignificato
acceptpdf, docx, xlsx, csv, txt, jpg, jpeg, png, webpEstensioni accettate. Ammesse anche: md, json, html, xml, gif. Fino a 12.
maxMb10File più grande, in MB. Al massimo 15.
multiplefalseFino a 10 file.
extracttexttext: il testo di file PDF, Word, Excel, CSV e di testo viene estratto per l'agente. none: nessuna estrazione.
capture—Una foto scattata con la fotocamera: solo immagini, rimpicciolite prima del caricamento. Nell'app per telefono, la fotocamera nativa.

Cosa succede al caricamento:

  1. Il file viene caricato appena scelto, prima dell'invio del modulo.
  2. Il server controlla l'estensione, la dimensione e che il contenuto sia davvero quel tipo di file (un programma rinominato non è un PDF). Errori: this field accepts …, the file is larger than N MB, the file is not a valid <ext>, empty file.
  3. Il testo viene estratto (fino a 60.000 caratteri per file). Le immagini non hanno testo.
  4. Il file viene memorizzato nell'archivio proprio dell'app. Il modulo ne conserva l'id.

Chi può scaricare un file: l'utente che l'ha caricato e gli amministratori dell'app. Nessun altro, nemmeno un ruolo a cui una regola di accesso dà il record. I file si scaricano come allegati.

Per gli agenti: l'obiettivo di un'esecuzione riceve {<field>} (i nomi dei file) e {<field>_text} (il testo estratto, al massimo 30.000 caratteri in tutto tra tutti i file). Un agente legge un file, e vede un'immagine, con uno strumento dell'app {action: read_file}. Vedi Agenti e automazione.

Chi può creare record con un modulo

Una vista di tipo form salva i record nella sua collection. Vedi Viste per la vista stessa.

ownedBy della raccoltaChi può creare un record
userOgni utente con accesso che può aprire il modulo. Il record è suo.
orgOgni utente con accesso che può aprire il modulo, e i visitatori se il modulo è aperto a loro. Solo gli amministratori (e le regole di accesso) leggono i record: una casella di posta in arrivo.
app, sharedSolo gli amministratori. Gli altri ricevono only the app's admins add to this collection.
instanceNessuno: i record di un'istanza sono scritti dal suo agente.

I visitatori possono inviare al massimo 5 invii all'ora da un indirizzo di rete a un modulo.

Con edit: true, aprire il modulo come /v/<key>?id=<record id> modifica quel record, se l'utente può modificarlo (vedi Chi legge e scrive i record).

Ogni record salvato è un evento dell'app: i trigger su quella raccolta scattano. Vedi Agenti e automazione.

Cosa possono leggere e scrivere gli agenti

Gli agenti raggiungono le raccolte attraverso gli strumenti dell'app (read, search, show, write, append). La descrizione completa degli strumenti è in Agenti e automazione; le regole sui dati sono:

  • Uno strumento su una raccolta user o instance è legato all'utente per cui l'agente lavora: l'agente deve passare la sessione dell'app che riceve nel suo compito. Legge e modifica i record di quell'utente, più quelli che le regole di accesso della raccolta danno al ruolo dell'utente. I nuovi record vengono marcati con quell'utente.
  • Uno strumento su una raccolta app, shared o org agisce per tutta l'app, a meno che lo strumento imposti scope: user o scope: session. Legge ogni record e può creare e modificare record.
  • Un agente che i visitatori usano senza accesso non riceve strumenti su una raccolta org, e non può scrivere su raccolte app o shared. La validazione rifiuta questi strumenti, e il runtime rifiuta la chiamata.
  • read senza id restituisce fino a 50 record, dai più recenti. search e show ne restituiscono fino a 100 (predefinito 20).
  • Il contesto dell'agente (context: [{key, from: collection:<name>}]) dà all'agente i record che l'utente può leggere, fino a 30 record e 8.000 caratteri.

Limiti sui nuovi record

Un limite con action: create:<collection> fissa quanti record un utente può creare in una raccolta:

limits:
  - { action: create:listings, max: 3, window: total, plans: { pro: 50, agency: -1 } }
  • window: minute, hour, day, month (30 giorni) o total (da sempre: una quota).
  • Il conteggio riguarda i record propri dell'utente nella raccolta creati in quella finestra.
  • Si applica ai record creati tramite moduli e tramite strumenti degli agenti. Gli amministratori ne sono esenti.
  • per deve essere user (il predefinito); altri valori non si applicano a questo tipo di limite.
  • plans alza il limite per piano o pacchetto (-1 = nessun limite) per i record creati dagli strumenti degli agenti. I moduli usano sempre max.
  • roles non si applica ai limiti create:.

Quando il limite è raggiunto l'utente vede limit reached: ….

La pagina Data degli amministratori

Gli amministratori hanno un link Data nell'intestazione (/admin/data) quando l'app ha almeno una raccolta con proprietario shared, app o org. I record degli utenti (user, instance) non sono in questa pagina: appartengono agli utenti.

La pagina ha una scheda per raccolta e, per quella scelta:

  • Add a record / Edit the record: un modulo con tutti i campi della raccolta tranne i campi file. Si applicano gli stessi controlli di un modulo. Il salvataggio fa scattare i trigger come qualsiasi modulo.
  • Import from CSV: vedi sotto.
  • Records: fino a 200 record, dai più recenti, con i primi 6 campi come colonne, ognuno con Edit e Delete (dopo una conferma).

La pagina elenca anche gli ultimi agenti che non sono riusciti a partire, con il motivo.

Importare un CSV

  1. Download the template: un CSV vuoto la cui intestazione riporta i campi.
  2. Compilalo in un foglio di calcolo e scegli il file.

Le regole dell'importazione:

  • L'intestazione indica i campi, per nome o per etichetta, ignorando maiuscole e minuscole. Le colonne che non corrispondono a nessun campo vengono ignorate.
  • Virgola o punto e virgola, quello usato dall'intestazione. Virgolette come nel CSV standard.
  • Al massimo 2000 righe e 5 MB per importazione.
  • I valori si leggono come li scrivono le persone: yes, sì, true, 1, x sono veri; 1.200,5 e 1200,5 sono numeri; una select accetta il suo valore o la sua etichetta; una multiselect accetta valori separati da | o ,.
  • Ogni riga viene controllata come un modulo. Le righe non valide vengono saltate; la pagina riporta quante sono state importate e saltate, con i primi 20 errori.
  • L'importazione non fa scattare i trigger: mille righe non avviano mille agenti o email. Nemmeno i valori predefiniti dei campi vengono applicati.

Esportazione in CSV

Una vista di tipo table, list o cards con export: true mostra un link Download CSV sotto le sue righe, quando ci sono righe. Il file contiene le righe che quella vista mostra a questo utente, con i campi della vista come colonne (tutti i campi quando la vista non ne indica nessuno, senza userId).

  • UTF-8 con byte-order mark, così i fogli di calcolo leggono gli accenti.
  • Le celle che un foglio di calcolo eseguirebbe come formula (che iniziano con =, +, -, @) iniziano con un apostrofo.
  • Al massimo 200 righe.
  • Le righe riservate a un piano non vengono esportate: un utente senza il piano riceve this data needs a plan.

Blocchi di dati

Un blocco di dati mostra righe in una pagina. È un blocco di tipo data in una vista page, e lo stesso meccanismo alimenta le viste table, cards, list e chart (vedi Viste).

- 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. }

Sorgenti

sourceRighe
collection:<name>I record della raccolta che questo utente può leggere (vedi Chi legge e scrive i record).
job:<key>L'ultimo dataset di un job di dati.
runLe esecuzioni proprie dell'utente con accesso: title, status, createdAt, finishedAt, agent, chargedCredits e i valori del modulo. I visitatori non ricevono righe.
catalog o catalog:<category>Il catalogo pubblico delle fonti della piattaforma.

Le righe dai job e dal catalogo restano in cache per un minuto.

path trasforma una lista dentro ogni riga in righe, es. path: assets mostra ogni elemento della lista assets di ogni riga.

Visualizzazione

displayCosa mostra
tableUna tabella, una colonna per campo.
cardsUna scheda per riga: il primo campo come titolo, gli altri sotto con le loro etichette.
listUna riga di testo per riga: il primo campo in grassetto, gli altri dopo.
kpiNumeri chiave da kpis (fino a 6), calcolati sulle righe caricate dal blocco (dopo i filtri e limit). Senza kpis: il numero di righe.
barBarre orizzontali: il primo campo è l'etichetta, il secondo il valore.
chartUn grafico di tipo chart: bar, line, pie o stacked. Il primo campo dà le etichette, gli altri le serie.

Campi e formati

fields (fino a 12) sono le colonne, ognuna {key, label, format}. key può essere un percorso con punti (price.amount). Senza fields, il blocco mostra i primi 6 nomi di campo trovati nelle righe, di solito non ciò che vuoi: elenca i campi.

formatMostra
text (o nessuno)Il valore. Una posizione "lat,lng" diventa un link alla mappa.
numberUn numero con fino a 2 decimali, nel formato locale della pagina.
moneyUn importo nella billing.currency dell'app (predefinita EUR), senza decimali.
percent+12.5%, verde se positivo, rosso se negativo.
ratioUna frazione come percentuale: 0.25 mostra +25%.
dateUna data, es. 05 Mar 2026.
linkUn link, solo per indirizzi https://.
badgeIl valore in un badge.
locationUn link alla mappa per una posizione "lat,lng".

Con una sorgente di tipo raccolta:

  • un campo senza label prende l'etichetta del campo della raccolta;
  • il valore di un campo select mostra l'etichetta della sua opzione nella lingua di chi legge ("new" → "Nuova").

In una tabella, un testo lungo (oltre 220 caratteri, come il report Markdown di un agente) appare come estratto in testo semplice; il testo completo compare al passaggio del mouse. Vale per i campi senza formato o con formato text.

Filtri, ordinamento e limite

  • filters (fino a 8): {field, op, value}. = e != confrontano come testo. >, >=, <, <= confrontano numeri; le righe il cui valore non è un numero vengono escluse. contains cerca il testo, ignorando maiuscole e minuscole.
  • sort: {field, dir}. I numeri si ordinano come numeri, gli altri valori come testo. dir è asc o desc; il predefinito è desc.
  • limit: da 1 a 200 righe. Predefinito 50.

Numeri chiave: kpis

Ogni KPI è {label, agg, field, format}. agg è count, sum, avg, min, max o last (il primo valore non vuoto nelle righe, dopo l'ordinamento: con l'ordinamento predefinito desc su una data, il più recente).

- 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 }

Raggruppamento: groupBy

groupBy crea una riga per ogni valore di un campo, con gli aggregati come colonne:

groupBy:
  field: createdAt
  bucket: week          # day, week (dal lunedì) o month, per le date
  aggs:
    - { key: total, agg: sum, field: amount }
  minCount: 5           # i gruppi con meno righe sono nascosti

Ogni riga di gruppo ha anche count. Usa il campo e le chiavi degli aggregati in fields.

Con acrossUsers: true su una raccolta ownedBy: user, il blocco aggrega i record di tutti gli utenti, non solo quelli di chi legge. Sono mostrati solo gli aggregati, mai un record. Richiede un minCount di almeno 5, così nessun gruppo può isolare un singolo utente. Altrimenti la validazione lo rifiuta.

Anteprime ridotte: preview

preview: {rows, unlessPlan} mostra agli utenti senza il piano unlessPlan solo le prime rows righe (predefinito 3), poi "N more rows with the plan.". In un'anteprima ridotta i pulsanti dei record sono nascosti. Gli amministratori vedono tutto.

Pulsanti dei record: actions

actions (fino a 4) aggiunge pulsanti a ogni riga: chiama, indicazioni stradali, condividi, aggiungi al calendario. Vedi Viste.

Quando non ci sono righe

Un blocco senza righe mostra empty, oppure "No data yet.". Una sorgente che non si può leggere mostra "Data not available right now." Una sorgente job: il cui job non è collegato mostra "Job not linked.".

Job di dati

spec.data.jobs elenca i job di dati della piattaforma WebRobot che l'app usa. Un job si collega con il suo projectId e jobId.

data:
  jobs:
    - key: prices
      description: Daily prices from the partner shops
      projectId: 812
      jobId: 4410

Cosa fa il runtime con un job collegato:

  • un blocco di dati o una vista con source: job:<key> legge l'ultimo dataset prodotto dal job. Il runtime costruisce la query dai campi, dai filtri, dall'ordinamento e dal limite del blocco; i numeri memorizzati come testo si confrontano come numeri;
  • una pianificazione o un trigger può avviare il job. Vedi Agenti e automazione.

Un job senza projectId e jobId non è collegato: i blocchi mostrano "Job not linked." e le pianificazioni lo saltano.

Lo schema accetta anche pipeline, params, perRecord, schedule e ingestTo su un job. Il runtime non li usa ancora.