Atlas Forms
Action Scope
Action scope refers to what data and services are available to a handler based on where it is triggered from — a single form field, a record, a workflow node, or a global form event. Understanding scope helps you design handlers that are robust and predictable.
Scope Levels
| Scope | Available In Context | Typical Use |
|---|---|---|
| Form | All current field values, formId, tenantId | Submit, validate, reset — general form operations |
| Record | Form values + selected record key (from data-table) | Edit selected row, link to detail form |
| Workflow | Form values + workflow instance context ($context) | Approve/reject, transition workflow state |
| Tenant | Form values + tenantId + tenant-specific config | Tenant-customised submit destinations |
| Global | Application-level singleton services | Send analytics, update global state |
Accessing Workflow Context
When a form is rendered inside a workflow node, the workflow execution context is available through data-bound fields. Access it via formValues:
const workflowHandler: FormActionHandler = async (ctx) => {
// The workflow instance ID is bound from $context.workflowInstanceId
const workflowInstanceId = ctx.formValues['workflow-instance-id'];
const nodeId = ctx.formValues['node-id'];
if (!workflowInstanceId) {
ctx.fail('This action requires workflow context.');
return;
}
await workflowApi.complete({
instanceId: workflowInstanceId,
nodeId,
outcome: ctx.config?.outcome ?? 'approved'
});
ctx.complete('Workflow step completed.');
};Tenant-Aware Handlers
Use ctx.tenantId to make your handler behave differently per tenant:
const submitHandler: FormActionHandler = async (ctx) => {
const { tenantId, formValues, formId } = ctx;
// Tenant-specific endpoint
const endpoint = tenantConfig.getSubmitEndpoint(tenantId, formId);
await fetch(endpoint, {
method: 'POST',
body: JSON.stringify({ tenantId, ...formValues }),
headers: { 'Content-Type': 'application/json' }
});
ctx.complete();
};Scope and Security
Action handlers run in the browser — they are client-side code. Scope is about what data is available, not what is authorised. All sensitive operations must be validated server-side. Never rely on client-side scope checks for security enforcement.
Security Reminder
Never put secret API keys, credentials, or sensitive business logic in action handlers. Handlers run in the browser and are visible to users. Always call a backend API that enforces its own authorization.