Tabs Reference
The manifest
Your app's manifest is a JSON file on your site, at an address you choose (/tands.json, say). Workspace admins install your app from that address.
{
"manifestVersion": 1,
"id": "acme-crm",
"name": "Acme CRM",
"description": "Your customers, in a tab.",
"developer": { "name": "Acme", "url": "https://acme.example" },
"icon": "/icon.png",
"tabs": [
{ "id": "contacts", "name": "Contacts", "url": "/tab/contacts" },
{ "id": "deals", "name": "Deals", "description": "Your pipeline.", "url": "/tab/deals" }
]
}Fields
| Field | Required | Rules |
|---|---|---|
manifestVersion | Yes | 1 |
id | Yes | 3–64 characters: lowercase letters, digits, and single dots or dashes between them, like acme-crm or com.acme.crm. Never change it: it's how workspaces know your app. |
name | Yes | 1–40 characters |
description | No | Up to 300 characters |
developer.name | With developer | 1–80 characters |
developer.url | No | An http(s) address |
icon | No | A path to a square PNG, JPEG, WebP or GIF, up to 100 KB. SVG isn't accepted. |
tabs | Yes | 1–10 tabs (below) |
data | No | The data your app keeps in the workspace: see Collections |
actions | No | What your app does when agents ask: see Actions |
events | No | What happens in your app, for triggers: see Events |
data is optional: the collections your app keeps. See Collections.
Fields this version doesn't know are ignored, so later fields won't break older workspaces.
Tabs
| Field | Required | Rules |
|---|---|---|
id | Yes | Lowercase letters, digits and dashes, starting with a letter or digit; up to 40 characters; unique in your manifest. Keep it stable: tabs in spaces refer to it. |
name | Yes | 1–40 characters. A new tab is named after it, and people can rename theirs. |
description | No | Up to 200 characters, shown when people choose a tab to add |
url | Yes | The page: a path, or a full address on your origin |
Collections
data.collections maps each collection's name to its declaration. Names, of collections and of fields, are lowercase letters, digits and underscores, starting with a letter, up to 40 characters.
| Field | Required | Rules |
|---|---|---|
scope | Yes | workspace, space, tab or user: who shares and sees it. See Scopes. |
fields | Yes | 1–50 fields, each with a type (string, text, number, boolean, date, datetime), an optional description (up to 200 characters), required (default false) and, for strings, enum |
description | No | Up to 300 characters |
agents | No | read (the default) or none |
An app has up to 20 collections. See Keeping data.
Actions
actions maps each action's name (lowercase letters, digits and underscores) to its declaration. An app has up to 20.
| Field | Required | Rules |
|---|---|---|
description | Yes | Up to 300 characters: what it does, for agents and admins |
url | Yes | Its endpoint: a path, or a full address on your origin |
changes | No | true (the default): agents ask the person first. false: it only reads, and runs at once. |
input | No | Up to 20 fields, as in collections |
See Actions.
Events
events maps each event's name (lowercase letters, digits and underscores) to its declaration. An app has up to 20.
| Field | Required | Rules |
|---|---|---|
description | Yes | Up to 300 characters: what happened, for people in triggers |
fields | No | Up to 20 fields, as in collections |
See Events.
One origin
An app lives on one origin: the manifest's. icon and every tab's url are resolved against the manifest's address and must stay on its origin. /tab/contacts in a manifest at https://crm.example.com/tands.json is https://crm.example.com/tab/contacts. A tab on https://other.example.com is refused.
Tokens are addressed to that origin, and the workspace only talks to frames on it. If your pages need several hosts, serve them behind one.
Changing it
You can change anything but id and your origin; that includes adding actions. Workspaces pick up changes when an admin chooses Check for updates. Removing a tab from your manifest leaves the tabs people added saying your app's tab isn't installed. See Installing and updating.