Operate
Environments
An add-in owns an ordered set of environments — Development, QA, Staging, UAT, Production — and each one runs its own agent, independently live. This page covers renaming, the per-environment result cache, and how configuration moves between environments.
6 min read
What an environment is
An add-in owns an ordered set of named environments — up to five, in a fixed promotion order (Development, QA, Staging, UAT, Production by default; you don't have to fill every slot, and names are yours to edit). A new add-in starts with a single Development environment.
- Each environment runs its own agent — its own
connxl-agentprocess (or several replicas), authenticated by a certificate scoped to that one environment. There is no "active environment" and no pin: Development and Production are served in parallel by different agents, and nothing you do in one affects whether the other is live. - Development (position 1) is the source. It's the only environment where you create or edit structure — functions, connection definitions, ribbon buttons, the taskpane. The backend enforces this, not just the dashboard.
- Every other environment is a promote target. There you edit only environment-specific values — credentials, hosts, cache settings. A structural edit (adding a function, changing a connection's shape) is rejected outside the source environment; you bring structure in with Promote instead.
Renaming and deleting
Open an environment's Settings to rename it. The slug — matched case-insensitively against the agent's CONNXL_ENV_ID at connect time — is fixed at creation and can't change, so renaming the display name never breaks a running agent's identity.
Deleting cascades
Deleting an environment removes its connections, functions, ribbon buttons, taskpane, and version history with it. The source environment and the environment an add-in currently depends on for its last remaining agent are protected from deletion.
The result cache
Each environment carries its own cache configuration — the agent's snapshot cache block, edited from the environment's Configuration tab on the Agent page. It controls whether (and how) function results are cached before a call reaches your data source again.
- Backend —
disabled(the default; nothing is cached),memory(in the agent process — cleared on restart, per-replica), orvalkey(shared across every replica in the environment, backed by a Valkey connection you register like any other data source). - Defaults — the catch-all TTL and size limits applied to any function no segment below covers.
- Segments — an ordered list of glob rules over function ids (
MODULE.NAME, e.g.SALES.*). The first matching segment wins, so put narrower patterns above broader ones. Each segment can set its own TTL and size limits, overriding the defaults for just the functions it matches.
| Field | Type | Description |
|---|---|---|
backendRequired | disabled | memory | valkey | Where cached results live. valkey needs a registered kv connection in this environment — without one, the option is unavailable. |
connectionIdOptional | id | The kv (Valkey) connection backing a valkey cache. The connection's URL is a secret, so the cache config references it by id rather than storing the URL directly. |
defaults.ttlSecondsOptional | int | Default time-to-live for a cached result, in seconds. Blank/0 means no default limit is set. |
defaults.maxEntriesOptional | int | Default cap on the number of cached entries. |
defaults.maxBytesOptional | int | Default cap on cached size, in bytes. |
resources[].nameOptional | string | A label for the segment. default is reserved, and names must be unique within the environment. |
resources[].matchRequired | glob | A glob over function ids (e.g. SALES.*). Ordered top-to-bottom; the first match wins. |
resources[].ttlSeconds / maxEntries / maxBytesOptional | int | Overrides the defaults for functions this segment matches. |
A pattern that matches nothing is only a warning
The dashboard checks each segment's glob against your environment's current function ids and flags one that matches none of them — useful for catching a typo'd module name. It's advisory only: a pattern can legitimately target a function you haven't built yet, so it never blocks saving.
Caching applies only when a backend other than disabled is selected; picking disabled keeps the backend selector live (so you can turn caching back on) but makes every other field inert.
How configuration moves between environments
Structure never edits itself into a downstream environment — it's brought in deliberately with Promote, from that environment's page. Promote:
- Copies the source environment's structure (functions, connections' shape, ribbon buttons, taskpane) into the target environment.
- Preserves the target's own values — its credentials, agent host, and cache configuration are untouched, so promoting a new function to Production doesn't overwrite Production's database password.
- Publishes automatically — a promote both updates the target's working configuration and makes it live in the same step, recorded as a
promoteentry in that environment's version history.
See Versions for the full save/publish/compare/restore workflow, and how a promote shows up in an environment's history.
Dashboard
The dashboard is where you configure add-ins and watch the agents that serve them. Everything is scoped by the URL — organization, then add-in, then environment — so the breadcrumb tells you exactly what you're editing.
Versions
Every environment keeps a restorable history of published configurations. This page covers the draft-vs-live model, saving and publishing a version, comparing two snapshots (including your unpublished draft), restoring, and promoting a version across environments.