Skip to main content

​
Overview

An Organization is the top-level tenant for all data, users, and settings. Each organization owns a hierarchical tree of Sites, membership records (roles), and configuration.

​
Creation & Default Structure

  • Creating an organization also creates:
    • a root Site (id like site-root-*, name root),
    • a default “HQ” child site, and
    • an OrganizationUser membership for the creator with OWNER role, assigned to the root site.
  • The creator’s currentOrganizationId is set to the new organization.

​
Settings

Organization settings influence workflows, AI features, and UI options:
  • defaultFormWorkflow: { type: "DIRECT_APPROVAL" | "REQUIRE_APPROVAL" } (affects submission status behavior)
  • defaultDashboardStatuses: default statuses to display on dashboards
  • requireFormAssignment: roles required to be assigned to forms
  • AI keys (OpenAI/Anthropic): stored encrypted for UI/Calc generation
Admin settings handle branding/terminology (e.g., site label overrides).

​
Membership & Roles (RBAC)

Memberships (OrganizationUser) tie a User to an organization with a role and status:
  • Roles: VIEWER, COLLECTOR, APPROVER, MANAGER, OWNER (hierarchical)
  • Status: INVITED → ACTIVE → INACTIVE (email-based invitations)

​
Site Access (ABAC)

Site access is granted via OrganizationUserSite assignments. Effective access = assigned sites + all descendants. Assigning the root site yields access to the entire organization.

​
Key Operations

  • Get current org: organizations.get
  • Create org: organizations.create
  • Switch org: organizations.switch
  • List orgs (user memberships): organizations.list
  • List users (filtered by caller’s site access): organizations.listUsers
  • Invite user: organizations.inviteUser({ email, role, assignedSiteIds })
  • Update user role: organizations.updateUserRole({ userId, role, assignedSiteIds? })
  • Update user sites: organizations.updateUserSites({ userId, assignedSiteIds })
  • Bulk role/site ops: organizations.bulkUpdateUserRoles, organizations.bulkUpdateUserSites
  • Update settings: organizations.update
All procedures enforce RBAC and ABAC (role + site access) and rely on Row Level Security.

​
Best Practices

  • Assign owners/managers to the root site for full access; assign others to region/site branches.
  • Set defaultFormWorkflow and requireFormAssignment early to align behaviors.
  • Use clear naming and tags for sites; keep the hierarchy shallow when possible.
  • Prefer bulk operations for site/role assignments when updating many users.

​
Gotchas

  • Users without site assignments have no effective site access (they may still appear in admin lists).
  • Root site cannot be deleted; deleting sites is soft-delete and can cascade to descendants.
  • Coordinates on Site are strings in outputs; convert to numbers for calculations.

​
See Also

  • Site (hierarchy, schema, import)
  • Organization User (membership, roles)
  • Organization User Site (site assignments and access)