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 when you need to check which tab controls a workspace setting. The examples use the docs-demo 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
• Security
• Activity

ATOM hides tabs you cannot use:

• Profile, Categories, Approvals, Inbox, Integrations, and Team are visible to every signed-in user. Some actions still require admin or owner access. See the per-tab sections and the `Role visibility reference`.
• Billing and Security are visible only to owner and admin users.
• Activity is visible to owner, admin, dispatcher, and staff users. 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 to set the workspace approval policy. The quote form previews these rules before a quote is sent.

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 inbox requests into work orders` 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 that is read-only, archived, or queued for deletion blocks integration changes. The Connect, Reconnect, and Disconnect buttons show a tooltip that explains why the action is unavailable.

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 is read-only, archived, or queued for deletion. The buttons are disabled and show the workspace write-blocked notice.

#Security tab

Use Security to choose whether the workspace enforces two-factor setup for privileged roles.

Security is visible only when the workspace membership role is owner or admin. Other roles do not see the tab. Support staff impersonating a user cannot change this setting.

Open Settings > Security to set MFA policy:

• Require MFA for privileged roles: owner, admin, dispatcher, and staff accounts must set up two-factor authentication before app access, workspace creation, invite acceptance, demo entry, or workspace switching. This is the default for existing and new workspaces.
• Make MFA optional: team members can choose two-factor authentication from My account, but ATOM does not force setup just because their workspace role is privileged. Existing two-factor users still verify at sign-in.

Select Save changes to write the policy. The form shows Security settings have unsaved changes. until the change is saved.

Changing this policy affects future sign-in, onboarding, invite acceptance, demo entry, and workspace-switch checks. It does not remove a user's existing authenticator app or backup codes. Users who want to disable their personal two-factor setup can do that from My account when the active workspace policy is optional.

Security changes are blocked when the workspace is read-only, archived, or queued for deletion. The button is disabled and shows 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 shows the most recent activity first. When older entries are retained but not shown on the page, the footer reads Showing the most recent <limit> entries. Older history is retained for export.. Every viewer sees the action, actor, resource, and timestamps. Owner and admin users also see request metadata such as ip and userAgent; dispatcher and staff users do not.

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 the configured 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. Workspace roles, from least to most access, are contractor, technician, staff, dispatcher, admin, and owner.

• Profile: visible to every role. Edits apply to the signed-in user only.
• Categories: visible to every role. Any signed-in user can create, edit, archive, or restore categories today.
• Approvals: visible to every role. Saving requires admin or owner; other roles can read the current policy.
• Inbox: visible to every role. Editing or removing agency email domains requires admin or owner.
• Integrations: visible to every role. Connecting, reconnecting, or disconnecting Gmail requires admin or owner. Connecting or reconnecting Xero also requires admin or owner. Lower-access roles can still read health, run history, and sync-job badges.
• Billing: visible to owner and admin only. Other roles cannot open the subscription summary or Stripe portal.
• Team: visible to every role. Inviting, resending, or revoking invites requires admin or owner.
• Security: visible to owner and admin only. It controls whether privileged roles must enroll two-factor authentication for this workspace.
• Activity: visible to owner, admin, dispatcher, and staff. Owner and admin users see request metadata. Dispatcher and staff users see the activity details without request metadata.
• 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 read-only, archived, or deletion-pending workspace shows a write-blocked notice on affected actions. Reads still work for visible tabs.

#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.
• Security shows the intended MFA policy, especially before inviting privileged roles into the workspace.
• 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.