Sanctris Tools and purposes
Infrastructure checks and result delivery
Design administrators can call definitions with kind: "flow", defId, version and simulation: {formData, decisions?}. The read-only simulator uses the real engine and current organization. Approval nodes default to approve; decisions maps node IDs to approve/reject. It stops at services, waits or 100 actions and never creates instances, sends notifications, runs timers or performs HTTP. The browser exposes this under Fields & validation. This is a published-version scenario, not exhaustive path analysis or future-outcome assurance.
Explicitly subscribe signed Webhooks to operation.succeeded, operation.failed, operation.unknown, operation.rejected, or operation.expired, without a flowFilter. Empty event lists retain their existing instance-only behavior. Verify x-sanctris-signature and deduplicate by payload.eventId. payload.operation contains state and business references, not form data, confirmation arguments or tokens. State markers and outbox deliveries commit together. Delivery is at least once with bounded retries, not automatic push support in AI clients; an integration service must receive it. Unknown outcomes require reconciliation, never automatic replay.
Design sessions now retain multiple touched form/workflow references. Old sessions can migrate only the previously saved last reference. Connected AI apps show role/scope-filtered tool diagnostics; this does not verify client connectivity or bypass object-level authorization.
Sanctris exposes tools according to the connection's purpose, read/write scope and the user's business roles. Purpose is not a privilege escalation.
Purpose selection
| Purpose | Typical work |
|---|---|
| Daily work (default) | Tasks, intake forms, requests and progress |
| Forms and workflow design | Definitions, drafts, validation and proposals |
| Data analytics | Dictionaries, queries, audit queries and exports |
| Administration | Organization, positions, agents and workflow administration |
Daily work currently has up to 15 tools, including the approved-operation executor. Tool visibility can be smaller for read-only connections. Use tools/list as the authority. Removed compatibility aliases are not supported.
A typical intake flow
Read-only preparation
startable_flows({flowRef, formData?}) and get_collection({collectionId, formData?}) accept partial input and return prepared: versioned fields/rules, authoritative preview data/context, editable keys, valid and issues. Omit formData for initial values. Closed collections retain their submitted snapshot.
Preparation neither submits data nor creates an approval. Validation currently reports the first issue, not every error. Submission always revalidates. Authenticated web clients can use POST /api/forms/prepare with {formRef, data}.
Operation contract
Confirmation and outcome responses retain existing fields and add operation: contractVersion, operationId, state, terminal, nextAction, and safeToReplay. Next actions are review, poll, reconcile (unknown outcome), or none. Never interpret failure as permission to replay or automatically create a replacement.
The built-in studio and external MCP share a policy catalog, with intentionally narrower studio capabilities. Tool schemas remain authoritative in tools/list.
fillable_collections: discover forms available to the authenticated user.get_collection: read schema, current response and browser link.fill_collection: submit complete formData with schema-correct types.- Review the returned approvalUrl in the browser.
- Approval automatically executes the stored parameters. Use
execute_approved_operationwith the original operation_id to retrieve the outcome; do not create a replacement. - Query the result, never infer success solely from approval.
Required fields, types, audience, collection status and deadline are checked before requesting approval and again when submitting.
A typical workflow
Discover with startable_flows, initiate with initiate, read my_todo, act using act_on_task, track with instance_progress, and revise/withdraw using act_on_instance. Writes use the same confirmation mechanism.
Field values
Keep text as text, including phone numbers with leading zeros. Send numbers for numeric fields, arrays for multi-select fields and schema-shaped objects for ranges or tables. Do not add literal quote characters to a phone to “force” a string.
Design and administration
Draft simulation and connection access
For kind: "flow", get_draft accepts simulation: {rev, formData, formRev?, decisions?}. The workflow revision must match; omit formRev for the published bound form, or supply an exact form draft revision. Simulation does not submit, notify or call external services. AI Design also has a Simulate draft action.
Connection access settings can narrow tools and exact resources immediately, without expanding roles or OAuth scopes. Use unversioned flow:flow.xxx, form:form.xxx, collection:UUID or instance:UUID references. Workflow grants cover associated instances and the bound form when read through the workflow; direct form draft access needs its own grant. Resource restrictions deny global discovery and organization management. An empty restricted list denies all. Approved operations recheck access to reviewed parameters before execution.
Form preflight returns up to 100 validation issues, including table row paths, so AI can repair multiple fields at once. Preflight is not submission.
In AI Design, Simulate draft provides visual field/table input, published-versus-draft bound form selection, and per-node simulated approval decisions. Results show status and event trace with expandable technical details. This checks one scenario, not exhaustive path coverage.
Keep and name up to 10 temporary scenarios, then run them as a batch. Closing the dialog or changing form source clears them. Coverage reports observed nodes and directed transitions, including uncovered portions—not proof of every condition, input combination or path. Each scenario is bounded to 1000 transitions and 100 approval actions; external services and waits still stop simulation.
MCP get_draft accepts simulationBatch: {rev, formRev?, scenarios: [{name, formData, decisions?}]} instead of simulation. Invalid inputs are reported per scenario. Revision conflicts or authorization failures abort the whole batch rather than mixing revisions.
Draft changes go through validation and proposals. Administration remains role-restricted even when the connection requests the admin toolset. Reauthorize with the desired purpose if a tool is not available; do not use old aliases or an unrelated identity.