Docs / Renly Apps / Write rules and approvals

Write rules and approvals

A write rule says which changes need a person before they happen, or must not happen at all. The server evaluates the rules on every write, whoever asks: a person on a page, an agent, an API key, an import or an automation.

What a rule is

Match: A record type (or a live source's entity) and an action: create, update, delete, change owner or bulk. For updates, optionally only when one of the listed fields changes. Optionally when conditions on the record after the change, in the same grammar as queries: amount > 50000, stage = closed_won.
Require: Approval (one approver), two-person (two different approvers, neither the requester) or deny (the write is refused).
Approvers: A role or named people. If none is set, the app's makers. Organisation owners and admins can always decide, and the requester never can.
Message: Shown to the person whose change is held or refused.

An app has up to 50 rules. Rules live in the app's definition, so they are versioned, previewed and published with everything else, and the approval card for a publish shows rule changes.

{
  "id": "big-discount",
  "label": "Discounts over 20% need the sales lead",
  "match": { "type": "opportunity", "action": "update", "fields": ["discount"],
             "when": [{ "field": "discount", "op": "gt", "value": 20 }] },
  "require": "approval",
  "approvers": { "role": "sales_lead" },
  "message": "Discounts above 20% are approved by the sales lead."
}

How a write is evaluated

The write arrives through the Records service: from a page's action, a Records tool an agent calls, the REST API, an import or an automation step. Role, row scope, field access, the expected version and the idempotency key are checked first.
The app's rules are evaluated against the record as it would be after the change. Bulk writes meet the rules record by record.
If no rule matches, the write is applied in one transaction with its Records event and outbox entry. The response is applied.
If a rule requires approval, the write is not applied. A write request stores the exact change and a digest of it. The person sees Sent for approval; the API gets HTTP 202 with the request id.
If a rule denies, the write is refused with the rule's message (HTTP 422 for the API).
If the app is paused by an administrator, every write is refused with This app is paused by an administrator (HTTP 423). Reads continue.

Agents keep their own approval cards and autonomy level. A matching rule holds even an autonomous agent's write as a request. If agents are paused organisation-wide, an agent's or automation's held request stays open until they resume.

Where requests appear

Place	What you can do
In the app	The Approvals tab (`/apps/<name>/requests`) lists requests you raised, may decide, or make for. A held record shows a Waiting for approval badge.
Approvals inbox	Every write request appears beside workflow and agent approvals, with the field changes, the rule, your rights and the decision buttons. Two-person requests show their dual-control state.
Notifications	Approvers are notified when a request is held; the requester when it is decided.
Email	Each approver is emailed signed Approve and Reject links that open a confirm page. Rejecting, and approving a request that needs one approver, work from the link alone. Either approval of a two-person request needs you signed in.
Microsoft Teams	Approvers with a linked Teams identity get an Adaptive Card with Approve and Reject in their chat with Renly. Apps in Teams. Pro Plus and Enterprise.

Deciding

Approve runs the stored change exactly as requested, attributed to the requester, with the approver recorded. The record's version is checked: if the record changed in between, the request fails as stale and the requester resubmits.
Two-person rules need two different approvers, neither of them the requester. The first approval is recorded and the request waits for the second.
Reject takes a reason, which the requester sees.
The requester can withdraw a pending request.
Requests expire after 7 days.
A request from an API key runs with the key's own access when approved, and only while the key is live and may still write that type.

What the evidence records

Every applied write produces a Records event that names who acted (a person, an agent for a person, an API key or a workflow), the app version and the interface it came from, the fields before and after, and the rule and request when there was one, with each approver. The event is linked into the organisation's evidence trail; an agent's write is also linked to its tool effect. Decisions made from Teams, and actions run from a custom block or by an API key, are marked with how they came in. Audit entries cover the request lifecycle, pauses, owner changes and exports.

How evidence is sealed and verified is described in Approvals and governance and on the Governed Runtime page.

← Data, access and sources Next: Agents in apps →