Atlas Forms
Tenant Overrides Overview
The tenant override system lets a specific tenant customise shared forms without affecting the base forms that all other tenants see. Overrides are isolated at the database row level, merged at load time, and never modify the global schema.
The Problem Tenant Overrides Solve
In a multi-tenant SaaS deployment, a single form schema is shared across hundreds of tenants. But individual tenants often need small variations:
- Tenant A operates in Australia — they need a "GST Number" field that other tenants don't have
- Tenant B uses their own branding terminology — "Member ID" instead of "User ID"
- Tenant C is a public-sector customer — they need a higher-contrast accessible player
- Tenant D does not use the Purchase Order module — the Purchase Order forms should be hidden
All of these are solved by the tenant override system without creating per-tenant form forks.
What Can Be Overridden
| Override Type | Mechanism |
|---|---|
| Control label / placeholder | JSONPath override on controls[n].label |
| Control default value | JSONPath override on controls[n].defaultValue |
| Select options list | JSONPath override on controls[n].options |
| Visibility rule | JSONPath override on controls[n].visibilityRule |
| Validation rules | JSONPath override on controls[n].validation |
| Player selection | JSONPath override on metadata.playerOverride |
| Tenant-specific fields | Additions: new controls/sections in the tenant override row |
| Form visibility | Set IsActive = 0 on the tenant override row for the form |
What Cannot Be Overridden
| Field | Reason |
|---|---|
FormID | Primary key — immutable per tenant |
FormCategoryID | Group membership is global |
FormTypeID | Form type is set by the group owner |
FormCode | Used by routing and AI pipeline — must be stable |
PrimaryUsage | Tab routing is group-wide |
Pages in This Guide
| Page | Topic |
|---|---|
| Override Schema | The formGroupOverride JSON document structure |
| Control-Level Overrides | Changing labels, defaults, options for a specific tenant |
| Tenant-Specific Forms | Adding new forms in the tenant's private FormID range |
| Disabling Forms | Hiding specific forms for a tenant via IsActive flag |
| Tenant FormID Ranges | The tenantId × 100000 + groupStart convention |
| Deploying Tenant Overrides | Separate deploy scripts and tenant isolation |