Authoring workflow

A canvas goes from idea to live in three steps, all inside your tenant configuration repository. The same workflow applies whether a person or an AI agent does the writing.

1. Write

Create or edit canvases/{tenant}/{id}.canvas.yaml on a branch. Start from an existing canvas in your tenant or from the shared platform library rather than a blank file — the structure (queries → transform → template → actions) is the same everywhere.

Design guideline: put all logic in the transform, so the Handlebars template is presentation-only loops and conditionals. Grouping, sorting, date arithmetic, flags, and derived strings belong in JavaScript, where they can be reasoned about and reviewed; templates that contain business logic are where parity bugs hide.

2. Verify with live data

Two endpoints make canvases debuggable without touching Salesforce:

Endpoint	Returns
/api/v1/canvas/{tenant}/{id}/render?recordId=...&sfEnvironment=...	The rendered HTML, exactly as the Lightning component will show it
/api/v1/canvas/{tenant}/{id}/json?recordId=...&sfEnvironment=...	The raw query results and the transformed view model — what your template actually receives

Use the JSON endpoint first when a canvas misbehaves: it answers "is this a query problem, a transform problem, or a template problem?" in one look. Add refresh=true to bypass the five-minute configuration cache while iterating.

For local development, the canvas service supports rendering from a local checkout of your configuration repository, so you can iterate on a branch against real sandbox data before anything merges.

3. Ship

Merge. Configuration is live within five minutes — the platform reads canvases from your repository with a short cache. Rollback is git revert.

When a new canvas needs to appear on a Salesforce page, there is a one-time App Builder step to place the edgeCanvasRunner component (see Salesforce embedding). Every subsequent change to that canvas is repository-only.

Authoring with AI agents

Because a canvas is declarative configuration with a strict schema, AI agents author them reliably — and this is how much of the platform's canvas library is built and maintained:

• The schema is validated on load, so a malformed canvas fails fast with a precise error rather than rendering wrongly.
• The JSON debug endpoint gives an agent the same inspect-verify loop a person uses: query, check the view model, adjust the transform, re-render.
• Golden-reference verification — diffing rendered output against known-good historical output — is the standard bar when a canvas replaces an existing report. When one of our tenants' legacy operational reports (departure rooming lists and equipment reports built on a pre-Canvas framework) were migrated to Canvas, agents ported the queries, transforms, and templates, then verified renders against previously sent documents down to the email subject lines before the swap went live.

Practically, this means a change request like "add a dietary column to the rooming list" is a same-day, one-file configuration change: an agent (or a team member) edits the transform and template, verifies against live data, and merges.

Conventions worth keeping

• No tenant conditionals — a canvas belongs to a tenant; shared library canvases vary behavior through canvas_config blueprint overrides, never by checking tenant names.
• Honest empty states — skip mockData on operational canvases so an empty departure renders as empty, not as sample data.
• Version and describe — bump canvas.version and keep description current; these are your operational breadcrumbs.
• Separate report and email canvases — on-screen widgets use style: slds; email bodies are their own canvases with style: standalone (see Actions).