# Using extensions

> Install, connect, run, pause, update and remove an extension in a Prosaic workspace — who can do each, and where runs show up.

Source: https://developer.prosaic.works/docs/extensions/using-extensions

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](/docs/extensions/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](mailto:support@prosaic.works) |

## Install it on an entity

An extension is installed on an entity when it's deployed with that entity's ID:

```bash
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](#approve-a-wider-extension).

## Connect outside services

An extension that calls another system's API declares a [connection](/docs/extensions/manifest#connections) 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/callback` as 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](/docs/extensions/triggers#events) 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](/docs/extensions/sandbox-api#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:

```bash
prosaic extension logs --dir . --follow
```

Each 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](/docs/extensions/testing-and-deploy#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](mailto:support@prosaic.works). Its runs are kept for audit.

## Next

- [Triggers](/docs/extensions/triggers) — every event, the cron format and each action placement, with handlers.
- [Testing and deploy](/docs/extensions/testing-and-deploy) — the `validate`, `dev`, `deploy` and `logs` loop.
- [Examples](/docs/extensions/examples) — complete extensions to copy.
