Administer workspace settings

This guide shows you how to administer an ATOM workspace from Settings, plus the SLA tab on the Agencies page.

Use it as the durable reference for workspace administration. The examples use the docs-demo seed tenant, H&R Maintenance Docs Demo. The demo owner is jack.thompson@example.com.

#Open Settings

Open Settings from the sidebar. The URL is /settings?tab=<tab-id>. ATOM shows these tabs in this order:

• Profile
• Categories
• Approvals
• Inbox
• Integrations
• Billing
• Team
• Activity

ATOM hides tabs you cannot use. The visibility rules below match the role gating in _app.settings.component.tsx:

• Profile, Categories, Approvals, Inbox, Integrations, Team are visible to every signed-in user. Tab visibility does not imply write access: most actions on these tabs still require admin or owner. See the per-tab sections and the `Role visibility reference`.
• Billing is visible only when the active workspace membership role is owner or admin.
• Activity is visible only to owner, admin, dispatcher, and staff. Technicians and contractors do not see it.

Legacy URLs still resolve:

• /settings/approvals redirects to /settings?tab=approvals.
• /sla redirects to /agencies?tab=sla.

Use the in-product Help button on Settings to reopen this guide. The help target switches to Approvals settings while the Approvals tab is selected.

#Profile tab

Use Profile to maintain the signed-in user record only. It is not a place to edit other team members.

Open Settings > Profile to update:

• Name, Email, Phone for the signed-in user.
• Notification preferences for the signed-in user.
• Password and session controls when the form exposes them.

Profile edits do not change a user's role or workspace membership. Use the Team tab to invite a teammate; ask an owner or admin to change a role. To maintain other people's profiles, open Team and find their record, not Profile.

#Categories tab

Use Categories to control the work-order categories that flow through quoting, scheduling, and approval rules.

Open Settings > Categories to:

• Create a category with Create category. Fill Name, optional Description, a colour swatch, and the Set as default category toggle.
• Edit a category with the pencil icon on the row.
• Archive a category with the archive icon. Archived categories disappear from new assignments but stay attached to existing records.
• Restore an archived category with Show archived then the restore icon.

Category changes change three downstream behaviours:

• Quote Require approval for these job categories rules in Approvals match the category slug. Archiving a category that an approval rule depends on removes that rule's trigger for new quotes.
• New work orders and bookings can be tagged with the active categories. Existing records keep their previous category even after archiving.
• Technician profiles list categories under Skills / Job Categories for matching.

Slug collisions are blocked. ATOM derives the slug from Name, so renaming a category to match an existing one fails with A category with this name already exists.

#Approvals tab

Use Approvals as the workspace's durable approval policy. The quote form previews this policy; the source of truth lives here.

The tab is visible to every role, but saving the policy requires an admin or owner workspace role. Dispatcher, staff, technician, and contractor users see the current policy and the controls but the Save approval policy button will reject the change with an insufficient-permissions error.

Open Settings > Approvals to set:

• Approval threshold: a dollar amount in 0.00 form. Quotes at or above this total require human approval before auto-mode can continue. Inclusive.
• Always require approval: when ticked, every future quote send needs approval regardless of amount.
• Require approval for these job categories: tick one or more active categories. ATOM requires approval whenever the work order category matches.
• Require approval after hours: requires approval when the request lands outside Monday–Friday, 8am–6pm in the property's state timezone.
• Require customer signature by default: adds a signature step to every future send.

Leave Approval threshold blank to disable the amount threshold. Use 0.00 when every quote must require approval.

Quote senders also see Require customer approval before work can progress and Require customer signature before work can progress on the quote form. Those checkboxes apply to one quote only; the durable defaults live in this tab.

Select Save approval policy to write the change. ATOM stores an immutable policy snapshot on every sent quote, so later policy changes affect only future sends. The save banner reads Approval policy saved. Future quotes will use the updated rules..

The form refuses to save while offline. If the policy fails to read, the tab shows We couldn't read the current approval policy. with a Try again action. Reconnect or refresh before retrying.

See `Build, approve, and send a quote` for how the policy reaches the quote form at send time.

#Inbox tab

Use Inbox to review the agency domains that produce inbound work orders.

The tab is visible to every role. Editing agency domains requires admin or owner; lower-rank roles can view the agency domains list but cannot save domain edits.

Open Settings > Inbox to:

• Review which email domains map to which agencies.
• Add a domain mapping with Add domain.
• Edit or remove an existing agency domain mapping.

The Gmail connection is workspace-wide and now lives on the Integrations tab. Use Settings > Integrations to connect or reconnect Gmail, read the OAuth feedback banner, view run history, check success rate, and disconnect. Quotes sent with Send via Gmail require an inbox thread linked to the work order, so connect Gmail from Integrations before relying on Gmail delivery in the quote guide.

See `Turn an inbox email into a clean work order` for the day-to-day inbox workflow.

#Integrations tab

Use Integrations to manage external service connections. The current integrations are Gmail and Xero.

The tab is visible to every role. Connecting, reconnecting, and disconnecting Gmail require admin or owner; lower-rank roles see the Gmail health, run history, and recent runs but the Connect, Reconnect, and Disconnect buttons will reject the request. Connecting or reconnecting Xero also requires admin or owner. The Integrations tab does not expose a Xero disconnect action, so removing the Xero connection has to happen in Xero itself; the buttons available here for Xero are Connect Xero and Reconnect Xero only.

Open Settings > Integrations for Gmail:

• Connect Gmail opens the OAuth flow when no inbox is connected.
• Reconnect, Inbox, and Disconnect appear on a connected workspace.
• After Google returns, ATOM redirects to /settings?tab=integrations and shows a connection feedback banner.
• The status card derives a health badge from Successful runs and Failed runs. The displayed status switches to critical when the success rate falls below 50%, degraded below 90%, and healthy at or above 90%.
• Latest run and Recent runs show recent processed counts, error counts, and any errorSummary text.

Open Settings > Integrations for Xero:

• Connect Xero opens the Xero OAuth flow when no integration exists.
• Reconnect Xero is shown when an integration exists.
• Recent sync jobs lists the last 10 sync jobs with pending, processing, succeeded, or failed status badges.
• Account mapping shows the configured Xero account codes for revenue, labor, material, and fee lines.

Xero sync is queued: ATOM enqueues quote and invoice changes, syncs every few minutes, maps line items to the configured account codes, syncs status updates bidirectionally, and retries failed syncs with exponential backoff.

A workspace in read_only, archived, or hard_delete lifecycle blocks integration writes. The Connect, Reconnect, and Disconnect buttons fall back to a tooltip explaining the lifecycle gate.

See `Build, approve, and send a quote` for the Gmail and Xero send paths from a quote.

#Billing tab

Use Billing to read the workspace subscription summary and to manage payment, plan changes, and cancellations in Stripe.

Billing is visible only when the workspace membership role is owner or admin. Other roles do not see the tab.

Open Settings > Billing to read:

• Current plan: the active Stripe price label, or Unknown plan if Stripe has not returned one.
• Status: badges such as Active, Trialing, Past due, Paused, Canceled. ATOM overrides an Active badge to Active — canceling when Stripe has flagged the subscription to cancel at period end.
• Renewal: a short copy line for the current billing period, such as Renews on <date>, Trial ends on <date>, Cancels on <date>, Payment due — period ends <date>, or Ended on <date> after cancellation completes.

Select Manage billing in Stripe to start a Stripe Customer Portal session and open it in the same tab. Use the portal for card updates, invoice history, cancellations, and plan changes. Stripe handles failed-payment dunning with Stripe defaults.

Error states:

• Billing details are temporarily unavailable. with a Try again action: retry from the same tab.
• A billing/portal_unauthorized error shows a Sign in again link to /login.
• A billing/portal_forbidden or billing/portal_no_account error shows a Contact support link to support@atomworks.app.
• This workspace isn't linked to Stripe billing yet. appears when the workspace has no Stripe account. Contact support to link a Stripe customer.

When the browser restores the tab from the back-forward cache after a Stripe portal change, ATOM reloads the subscription summary so it does not show stale data.

See `Track invoices, payments, and Xero status` for billable invoice flows that sit downstream of subscription billing.

#Team tab

Use Team to invite teammates, track invite status, and resend or revoke invites.

The tab is visible to every role. Inviting, resending, and revoking require admin or owner; lower-rank roles can read the pending invites list but the action buttons will reject the request.

Open Settings > Team to:

• Select Invite team member to open the invite dialog.
• Enter Email address, an optional Name, choose Role from owner, admin, dispatcher, staff, technician, or contractor, and add an optional personal message.
• Select Send invite. ATOM stores the invite and shows it in the pending list. The list only returns invites that are still outstanding, so the visible statuses are pending or sent. Accepted, revoked, and expired invites drop off the pending list; check the workspace Activity log to confirm the change.

Use the per-row actions to:

• Resend: re-email an outstanding invite.
• Revoke: invalidate the invite. ATOM asks Revoke this invitation? before continuing.

The invite list does not edit existing team-member roles. Use the existing workspace admin tooling outside Settings to change a current member's role.

Invites are blocked when the workspace lifecycle is read_only, archived, or hard_delete. The buttons are disabled and show the workspace write-blocked notice.

#Activity tab

Use Activity to read the workspace audit log. It is gated to owner, admin, dispatcher, and staff. Technicians and contractors do not see the tab.

Open Settings > Activity to:

• See the latest workspace activity, newest first.
• Filter rows by action with the search field (for example booking.update, workspaceApprovalPolicy.upsert).
• Page through results 25 rows at a time.

Each row shows the action, the actor (or acting as label when a support staff impersonator was active), the resource type and id, an absolute timestamp, and a relative timestamp. Impersonator rows show a Support impersonation badge.

ATOM fetches the most recent entries (the WORKSPACE_ACTIVITY_FETCH_LIMIT window). When the list hits the fetch limit, the footer reads Showing the most recent <limit> entries. Older history is retained for export.. Every viewer of this tab sees the action, actor (including impersonator), resource type and id, and timestamps. Owner and admin also receive request metadata fields (ip and userAgent) from the underlying audit log; dispatcher and staff have those request metadata fields masked by maskWorkspaceActivityLogRequestMetadata but still see the action, actor, and resource columns.

Use Activity to confirm that policy and configuration changes from this Settings page were recorded. Changes made by support staff while impersonating a user are clearly labelled.

#SLA administration

SLA settings live on the Agencies page, not on Settings. Open Agencies and select the SLA tab; the URL is /agencies?tab=sla. The legacy /sla route redirects to the same tab.

Use Agencies > SLA to:

• Review agency-by-agency SLA scorecards for response, completion, and other tracked metrics.
• Set or edit per-agency SLA targets.
• See breach badges and trending warnings against TRENDING_THRESHOLD.

The Agencies page help target is agencies on the directory tab and sla on the SLA tab. The screen-level help button on Settings does not change to the SLA target; use the help button on the Agencies page instead.

See `Find and maintain records` for the agency directory edits that sit alongside the SLA tab.

#Role visibility reference

Use this list when planning role assignments. The roles are the values in VALID_ROLES: owner, admin, dispatcher, staff, technician, contractor. Role rank goes contractor < technician < staff < dispatcher < admin < owner. Tab visibility is enforced in the client; the action gates below are enforced by requireRoleAtLeast in the mutators and by API route checks.

• Profile: visible to every role. Edits apply to the signed-in user only.
• Categories: visible to every role. Server-side write actions (workOrderCategory.create, .update, .archive) require an authenticated session. There is no role-rank gate on category writes today, so any signed-in user can save. The tab does not currently apply the workspace-lifecycle write guard, so in a read_only or archived workspace the buttons stay enabled and the mutation only fails when submitted; the create/edit/archive buttons are disabled only when the browser is offline.
• Approvals: visible to every role. Saving requires admin or owner — workspaceApprovalPolicy.upsert calls requireRoleAtLeast(auth, "admin"). Other roles can read the policy but the Save approval policy button will fail with an insufficient-permissions error.
• Inbox: visible to every role. Editing or removing agency email domains is gated to admin or owner by the agencyEmailDomain.upsert and .delete mutators. Dispatcher, staff, technician, and contractor users can see the agency domains list but cannot complete domain edits.
• Integrations: visible to every role. Connecting, reconnecting, and disconnecting Gmail are gated to owner and admin by /api/gmail/oauth/authorize and the Gmail disconnect handler. Gmail OAuth feedback, connection health, run history, and disconnect controls live here. Connecting and reconnecting Xero are gated to owner and admin by /api/xero/oauth/authorize; the Integrations tab does not expose a Xero disconnect action today, so removing the connection has to happen in Xero. Read-only health, run history, and sync-job badges remain visible to lower-rank roles.
• Billing: tab is hidden for dispatcher, staff, technician, and contractor; visible to owner and admin. Both the subscription summary and the Stripe portal session check isBillingManagerRole server-side, so non-managers cannot reach the data even by URL.
• Team: visible to every role. The Invite team member flow (/api/team/invites) and the teamInvite.resend / teamInvite.revoke mutators require admin or owner. Lower-rank roles see the pending invites list but the action buttons will reject the request.
• Activity: tab is hidden for technician and contractor; visible to owner, admin, dispatcher, and staff. All visible roles see the action, actor (with Support impersonation badge where applicable), resource, and timestamps. Request metadata fields (ip, userAgent) are masked by maskWorkspaceActivityLogRequestMetadata for everyone except owner and admin, per canViewActivityLogRequestMetadata.
• SLA on the Agencies page follows the standard agencies access rules; use the in-product SLA button to confirm what each role can change.

Workspace lifecycle also gates writes across every tab. A workspace in read_only, archived, or hard_delete shows the workspace write-blocked notice on the affected actions; reads still work for the visible tabs even when the role gate above would otherwise allow the write.

#Handoff checklist

Before you leave a Settings change, confirm these points:

• The change is on the right tab and the tab is visible to the operators who need it.
• Approval changes match the rules you intend to fire from the quote form, including category-level rules.
• Inbox shows the expected agency domain mappings, and Integrations shows the expected connected state with no lastError banner.
• Billing reflects the right Current plan, Status, and Renewal copy; the Stripe portal opens for owner or admin.
• Team invites show the expected status; revoked invites are gone from active workflows.
• The change appears in Activity with the expected action name and resource id; an impersonation badge marks any action support staff took on the team's behalf.
• SLA targets and breaches are reviewed in Agencies > SLA, not in Settings.