This page is about an extension once it's deployed: how it gets onto a client's entity, how people in the workspace run it, and where to look when it does something unexpected. To build one, start with the quickstart.
Where extensions live
An extension belongs to the workspace it was deployed to. There's no marketplace or shared catalogue: to run the same extension in a second workspace, deploy it there too, signed in as an admin of that workspace.
Inside the workspace it runs only for the entities it's installed on. Each installation is one entity — one client or business — and is switched on and off on its own. An extension installed on three entities runs three times on a schedule, and an event on an entity it isn't installed on doesn't run it at all.
In the Prosaic app, extensions are under Settings → Extensions, at https://app.prosaic.works/settings/extensions. The link in the settings menu is still rolling out to workspaces, so if you don't see it, open that address directly.
Who can do what
| Task | Who |
|---|---|
| Deploy or update an extension, and install it on an entity | Workspace admin or owner |
| Enter, replace, authorise or disconnect a connection's credential | Workspace admin or owner |
| Open Settings → Extensions, turn an installation off or on, approve it | Advisor, admin or owner, for the entities they can see |
| Click an extension's action in the app | Anyone in the workspace who can see the entity |
Read run logs with prosaic extension logs | Anyone signed in to the CLI for the workspace |
| Delete an extension from the workspace | Prosaic support — email support@prosaic.works |
Install it on an entity
An extension is installed on an entity when it's deployed with that entity's ID:
prosaic extension deploy --dir . --entity-id <entity-id>Run it once for each entity. Every run finds the extension by the name in its manifest, updates it, and then installs it on the entity you named, or refreshes the installation if it's already there. The entity ID is the part of the app's address after /entities/ when you have that entity open, or run prosaic entities list.
Settings → Extensions has no button for installing on another entity yet, so new installations come from the CLI.
What installing grants
There's no separate consent screen. Installing is the consent: Prosaic records what the extension asked for at that moment — its scopes, and every host its connections can reach — together with who installed it and when. Every run is checked against that record as well as against the manifest, so a later deploy can't quietly give an installed extension more access. See Approve a wider extension.
Connect outside services
An extension that calls another system's API declares a connection for it. Each connection shows in the extension's panel under Settings → Extensions with its label, base URL, the hosts it can reach and a status: Not connected, Awaiting authorisation, Connected, Expired or Needs attention.
A workspace admin connects it there:
- API key, bearer token, username and password, or a custom header — type the values into the fields the connection asks for and choose Save. Prosaic never shows a stored value again, so to change one, type the new value and choose Replace.
- OAuth — enter the client ID and client secret from your app at the third party, choose Save client details, then Authorise and sign in to the third party. Register
https://app.prosaic.works/api/extensions/oauth/callbackas the redirect URI in their developer console first. Prosaic refreshes the access token from then on; Reauthorise starts the sign-in again.
Disconnect deletes the stored credential. If calls through a connection start failing, the panel shows the last failure's error code.
Prosaic encrypts the credential, attaches it to each request on the server, and never passes it into the sandbox. The extension's code can't read it, log it or send it anywhere else.
Connections declared with scope = "entity", which keep a separate credential for each client, can't be connected from Settings → Extensions yet. Use the default workspace scope, which shares one credential across the workspace.
Run it
How an extension runs depends on the triggers in its manifest. One extension can have all three.
Events
An event trigger runs the extension when something happens on an entity it's installed on: a journal is created, posted or voided, a bank transaction is reconciled, a file is uploaded, a GST period starts or a GST return changes status. Nobody has to do anything beyond their normal work — post the journal, reconcile the transaction, file the return. The Triggers page lists every event.
Schedules
A cron trigger runs the extension on its schedule, once for each entity it's installed on. Schedules are in UTC, so a 9am New Zealand run is 0 21 * * * in winter. A new or changed schedule takes effect within a minute of deploying.
Actions
An action trigger adds an item to the Prosaic app. Where it appears depends on its placement:
| Placement | Where it appears |
|---|---|
transaction.single | The actions menu on the Transactions page (⌘K or Ctrl+K), under Extensions, with one transaction selected |
transaction.bulk | The same menu with two or more transactions selected |
report | A button above the Profit and loss report |
The item shows the action's label. It appears only on entities where the extension is installed and switched on.
Clicking it runs the extension for that entity, with the selected transactions, or the report's dates, as its input. The person who clicked is the run's triggering user, so the extension can send email in the firm's name with replies going to them. The app shows Running… and then finished, or failed with the error the run ended on. If a run takes longer than three minutes, the app stops waiting and says it's still running; the result is under Settings → Extensions.
Email replies
An extension that sends a conversational email runs again when the recipient replies, with the reply as its input. Replies need no setup on the workspace's side. See Replies.
See what it did
Settings → Extensions lists every extension in the workspace with its status, version, and how many installations and runs it has. Open one to see:
- Execution Flow — its triggers and the scopes it holds.
- Connections — the credentials it needs, as above.
- Installations — each entity it's installed on, when, and a switch to turn it off and on.
- Recent Executions — the last five runs, with trigger, status and how long each took.
- Bundle Code — the code that actually runs. Deployed from the CLI, this is the built bundle; the source stays with the developer.
The log lines an extension writes with prosaic.log aren't shown in the app. Read them with the CLI:
prosaic extension logs --dir . --followEach run shows its status, ID, trigger and start time, every log line, and the error if it failed. A run that went over its time limit has the status timeout. See Logs for the flags.
Pause it
Turn an installation off with its switch under Settings → Extensions → Installations. While it's off, events and schedules skip that entity and its actions disappear from the app. Turn it back on the same way. Other entities' installations carry on.
Deploying with --entity-id turns that entity's installation back on, so a developer redeploying to a test entity doesn't need the app.
Update it
A developer updates an extension by deploying again. The new code takes effect on every installation at once — there's no per-entity version and no history to roll back to, so rolling back means deploying the earlier code again. The manifest's version is shown in Settings → Extensions but is otherwise a label.
Approve a wider extension
When a deploy adds a scope, or a connection host, every installation made before it stops running for that entity. Events and schedules are skipped, and clicking one of its actions fails with GRANT_REQUIRED. Removing a scope never pauses anything.
The installation is marked Paused until you approve what it now asks for, listing the new scopes and hosts. Approve and resume records the wider grant and starts it again. Deploying with --entity-id does the same for that one entity.
Remove it
There's no uninstall in the app or the CLI yet. To stop an extension running for an entity, turn its installation off. To delete it from the workspace entirely, email support@prosaic.works. Its runs are kept for audit.
Next
- Triggers — every event, the cron format and each action placement, with handlers.
- Testing and deploy — the
validate,dev,deployandlogsloop. - Examples — complete extensions to copy.
