|
| 1 | +--- |
| 2 | +title: Administrator Guide |
| 3 | +description: The task-first operations manual for customer system administrators — onboard a tenant in four steps (build the org tree, add people, assign positions, verify), with the 90% rule — daily administration is assigning positions; the capability plumbing ships built-in. |
| 4 | +--- |
| 5 | + |
| 6 | +# Administrator Guide |
| 7 | + |
| 8 | +You are the **system administrator** of an ObjectStack tenant. You opened |
| 9 | +Setup for the first time and found dozens of positions and permission sets you |
| 10 | +never created. This page is the *"I'm the admin — what do I actually do?"* |
| 11 | +manual: one real task — onboarding your organization — walked start to finish, |
| 12 | +with the platform concepts introduced only where you need them. |
| 13 | + |
| 14 | +The one thing to internalize before anything else: |
| 15 | + |
| 16 | +> **90% of daily administration is assigning people to positions.** The |
| 17 | +> positions, the permission sets behind them, and the security baseline all |
| 18 | +> ship with the platform and the apps you install. You almost never build |
| 19 | +> capability from scratch — and you shouldn't. |
| 20 | +
|
| 21 | +## Four concepts — only one is a daily tool |
| 22 | + |
| 23 | +| Concept | What it is | Who authors it | You touch it | |
| 24 | +|:--|:--|:--|:--| |
| 25 | +| **Permission set** | The only capability container — object CRUD, field security, access depth, system capabilities | Platform & app developers (in Studio) | Rarely — [Step 5](#step-5--configure-permissions-only-when-the-shipped-positions-dont-fit) | |
| 26 | +| **Position** (岗位) | A flat, named job function that binds permission sets; users hold positions | Ships with apps; you assign it | **Daily** | |
| 27 | +| **Business unit** | The *one* hierarchy — org tree that decides visibility depth and delegation boundaries | You, at onboarding and reorgs | Occasionally | |
| 28 | +| **User** | The person signing in | You | Daily | |
| 29 | + |
| 30 | +A user's effective access is the **union** of every permission set reached |
| 31 | +through their positions, plus direct grants, plus the built-in additive |
| 32 | +baseline (`member_default`) every authenticated user gets. Restriction is done |
| 33 | +by *not granting* — there are no subtraction rules to maintain. Details: |
| 34 | +[Permission Sets](/docs/permissions/permission-sets) · |
| 35 | +[Positions](/docs/permissions/positions). |
| 36 | + |
| 37 | +## The whole flow at a glance |
| 38 | + |
| 39 | +Onboarding a tenant is four ordered steps — each depends on the previous one: |
| 40 | + |
| 41 | +1. **Build the organization** — create the business-unit tree. |
| 42 | +2. **Add people** — invite, create, or import users; place them in units. |
| 43 | +3. **Assign positions** — give each person their job function (the daily 90%). |
| 44 | +4. **Verify** — impersonate a user and ask the explain engine why access |
| 45 | + resolves the way it does. |
| 46 | + |
| 47 | +A fifth step exists only for the minority case where a shipped position |
| 48 | +doesn't fit. |
| 49 | + |
| 50 | +## Step 1 — Build the organization (Business Units) |
| 51 | + |
| 52 | +**Setup → People & Organization → Business Units** (`/apps/setup`). |
| 53 | + |
| 54 | +The default **Org Chart** tab renders the tree as an indented |
| 55 | +expand-and-collapse tree grid. Create the root first (kind `company`), then |
| 56 | +add children with **New**, picking the **Parent Business Unit** in the form — |
| 57 | +`division` / `department` / `office` / `cost_center` are display hints; the |
| 58 | +tree works the same regardless. Reorganizing works the same way: **Edit** a |
| 59 | +unit and change its parent. *(Rough edge today: the tree view is a read-only |
| 60 | +presentation — re-parenting happens through the record form, not drag-and-drop.)* |
| 61 | + |
| 62 | +Three similarly-named things, three different jobs — don't mix them up: |
| 63 | + |
| 64 | +| Object | Job | |
| 65 | +|:--|:--| |
| 66 | +| **Business unit** (`sys_business_unit`) | The hierarchy. Drives visibility depth (`unit`, `unit_and_below`) and delegated-admin boundaries | |
| 67 | +| **Team** (`sys_team`) | Flat collaboration group. Teams *receive* sharing; they never carry capability | |
| 68 | +| **Organization** (`sys_organization`) | The tenant itself — your company's account, not a node inside it | |
| 69 | + |
| 70 | +Keep the tree shallow and honest to your real structure; you'll revisit it |
| 71 | +only on reorgs. Why the tree matters: |
| 72 | +[access depth](/docs/permissions/permission-sets#access-depth--readscope--writescope-adr-0057-d1). |
| 73 | + |
| 74 | +## Step 2 — Add people (Users) |
| 75 | + |
| 76 | +**Setup → People & Organization → Users.** Three ways in, all first-class: |
| 77 | + |
| 78 | +| Path | When to use | What happens | |
| 79 | +|:--|:--|:--| |
| 80 | +| **Invite User** (toolbar) | The person has a reachable email | Sends a better-auth invitation; they set their own password on accept | |
| 81 | +| **Create User** (toolbar) | No email flow wanted — or phone-only staff | Creates a sign-in-ready account (email and/or phone); a generated temporary password is shown **once**, with password-change forced on first login | |
| 82 | +| **Import** (toolbar) | Bulk onboarding from CSV/Excel | Wizard with column mapping and dry-run preview; up to 500 rows per batch. Pick the sign-in policy: no password (first sign-in via OTP/magic/reset link), send invitations, or one-time temporary passwords | |
| 83 | + |
| 84 | +Day-to-day lifecycle actions live on each user's row menu and record header: |
| 85 | +**Ban / Unban** (blocks sign-in), **Unlock Account** (clears a brute-force |
| 86 | +lockout early), **Set Password** (also mints one-time temporary passwords), |
| 87 | +and **Impersonate User** (see [Step 4](#step-4--verify)). *(Rough edge today: |
| 88 | +users' own self-service password recovery depends on a configured email or |
| 89 | +SMS delivery service — wiring tracked in cloud#580. Until then, admin **Set |
| 90 | +Password** is the reliable fallback.)* |
| 91 | + |
| 92 | +Placing a person in the org tree is a separate record: a **Business Unit |
| 93 | +Member** row (`sys_business_unit_member` — user + business unit, one marked |
| 94 | +*primary*). Depth-based visibility and `unit_and_subordinates` sharing resolve |
| 95 | +through this membership, so don't skip it. |
| 96 | + |
| 97 | +Endpoint-level detail (payloads, password policies, phone-only accounts): |
| 98 | +[Authentication → Admin User Management](/docs/permissions/authentication#admin-user-management). |
| 99 | + |
| 100 | +## Step 3 — Assign positions |
| 101 | + |
| 102 | +This is the daily 90%. An assignment is one row: **User Position** |
| 103 | +(`sys_user_position`) = *user* + *position* + optionally the **business unit** |
| 104 | +they hold it in. The anchor decides *where* the position's depth grants apply |
| 105 | +— "sales manager **of East**" sees East's records, not the whole company's. |
| 106 | + |
| 107 | +From **Setup → Access Control → Positions**, open a position and add |
| 108 | +assignments from its related list (or create User Position rows directly). |
| 109 | +These writes are governed: tenant-level admins pass; a |
| 110 | +[delegated admin](/docs/permissions/delegated-administration) can only assign |
| 111 | +allowlisted sets inside their own subtree — self-escalation is structurally |
| 112 | +refused. |
| 113 | + |
| 114 | +Two adjacent surfaces complete the picture: |
| 115 | + |
| 116 | +- **Direct grants** — on a permission set's record page |
| 117 | + (**Setup → Access Control → Permission Sets**), the **Assigned Users** panel |
| 118 | + adds per-user grants without a position. Rows held *via a position* are |
| 119 | + shown but removed on the position, not here. |
| 120 | +- **Business-unit membership** — from Step 2; independent of the assignment |
| 121 | + anchor. |
| 122 | + |
| 123 | +*(Rough edge today: position assignments, BU membership, and direct grants |
| 124 | +are three separate entry points — they aren't consolidated into a single |
| 125 | +panel on the user page yet.)* |
| 126 | + |
| 127 | +## Step 4 — Verify |
| 128 | + |
| 129 | +Never announce "you're all set" untested. Two built-in verification tools: |
| 130 | + |
| 131 | +- **Impersonate.** Users list → row menu → **Impersonate User**. You get that |
| 132 | + user's session — open the apps they'd open, confirm they see what they |
| 133 | + should (and *don't* see what they shouldn't). Impersonation is for |
| 134 | + legitimate support and verification; sessions are logged. |
| 135 | +- **Explain.** Studio's **Access** pillar → **Explain access**: pick the user, |
| 136 | + an object, and an operation, and the engine returns the verdict plus every |
| 137 | + evaluation layer — which permission set granted, held via which position, |
| 138 | + which sharing rule widened, which policy narrowed. The same report is |
| 139 | + available over REST at `/api/v1/security/explain`. See |
| 140 | + [Explain Engine](/docs/permissions/explain). |
| 141 | + |
| 142 | +When something resolves wrong, explain-first beats guess-and-toggle: the |
| 143 | +report names the exact permission set and layer to fix. |
| 144 | + |
| 145 | +## Step 5 — Configure permissions (only when the shipped positions don't fit) |
| 146 | + |
| 147 | +One rule of thumb: **permissions are *designed* in Studio, *assigned* in |
| 148 | +Setup.** If you are in this section, you've confirmed no shipped position |
| 149 | +covers the need. |
| 150 | + |
| 151 | +The permission-set **matrix editor** (Studio → Access) is a structured |
| 152 | +spreadsheet — you never hand-write JSON: |
| 153 | + |
| 154 | +- **Object grid** — per object: Create / Read / Update / Delete, lifecycle |
| 155 | + bits (Transfer / Restore / Purge), and View All / Modify All, with per-row |
| 156 | + bulk buttons (Read / CRUD / All / None) and the object's sharing baseline |
| 157 | + (OWD) shown alongside. |
| 158 | +- **Field-level security** — expand an object for per-field Read / Edit. |
| 159 | +- **Capabilities** — named grants like `manage_users` or `studio.access`. |
| 160 | + |
| 161 | +Prefer the smallest change that works, in this order: **bind an existing set |
| 162 | +to a position** → **clone and adjust** → **author a new set**. Editing a set |
| 163 | +that shipped with an app creates an *environment overlay* — your change wins, |
| 164 | +survives upgrades, and can be reset back to the vendor baseline; the API name |
| 165 | +is immutable after creation. And keep the additive model in mind: author |
| 166 | +coherent capability bundles, never "subtraction sets". |
| 167 | +Full model: [Permission Sets](/docs/permissions/permission-sets). |
| 168 | + |
| 169 | +## Quick paths |
| 170 | + |
| 171 | +| I need to… | Do this | |
| 172 | +|:--|:--| |
| 173 | +| Onboard a new employee | Invite/Create the user → Business Unit Member row → assign their position ([2](#step-2--add-people-users)→[3](#step-3--assign-positions)) | |
| 174 | +| Offboard someone | **Ban User** (blocks sign-in immediately) — then remove assignments at leisure | |
| 175 | +| "I can't sign in" | User record → is it banned? locked? **Unlock Account** or **Set Password** (temporary, must-change) | |
| 176 | +| "Why can't I see X?" | Studio → Access → **Explain access** for that user + object | |
| 177 | +| Someone changed departments | Update their Business Unit Member row; re-anchor their User Position rows | |
| 178 | +| Let a subsidiary manage its own staff | Grant a set carrying a [delegated admin scope](/docs/permissions/delegated-administration) | |
| 179 | +| Give one user one extra capability | Permission set record → **Assigned Users** → add (direct grant) | |
| 180 | + |
| 181 | +## FAQ |
| 182 | + |
| 183 | +**Do I need Studio?** Rarely. Setup is the administrator's home; Studio is |
| 184 | +where permission sets are *designed* — you enter it for Step 5 and for the |
| 185 | +Explain panel. |
| 186 | + |
| 187 | +**A new user sees almost nothing — broken?** No: that's the baseline working. |
| 188 | +Access arrives when you assign a position (Step 3). |
| 189 | + |
| 190 | +**Department vs. team?** Department = business unit (hierarchy, visibility). |
| 191 | +Team = flat sharing group. If it should affect *what records people see* by |
| 192 | +org structure, it's a business unit. |
| 193 | + |
| 194 | +**Can I delete the built-in permission sets?** No — sets like |
| 195 | +`member_default` and `organization_admin` are the platform baseline. Shipped |
| 196 | +sets can be overlaid (Step 5) or simply left unassigned. |
| 197 | + |
| 198 | +## Where is everything |
| 199 | + |
| 200 | +| Thing | Location | |
| 201 | +|:--|:--| |
| 202 | +| Users, invitations | Setup → People & Organization → Users / Invitations | |
| 203 | +| Business-unit tree | Setup → People & Organization → Business Units | |
| 204 | +| Teams | Setup → People & Organization → Teams | |
| 205 | +| Positions, permission sets, capabilities | Setup → Access Control | |
| 206 | +| Sharing rules, record shares | Setup → Access Control | |
| 207 | +| Password policy, MFA, lockout, SSO | Setup → Configuration → Authentication | |
| 208 | +| Company info, localization, branding | Setup → Configuration | |
| 209 | +| Sessions, notification events, audit logs | Setup → Diagnostics | |
| 210 | +| Permission matrix editor, Explain access | Studio → Access | |
| 211 | + |
| 212 | +--- |
| 213 | + |
| 214 | +## See also |
| 215 | + |
| 216 | +- [Permissions & Identity overview](/docs/permissions) — the full model |
| 217 | +- [Positions](/docs/permissions/positions) · [Permission Sets](/docs/permissions/permission-sets) |
| 218 | +- [Delegated Administration](/docs/permissions/delegated-administration) — scale yourself out |
| 219 | +- [Authentication](/docs/permissions/authentication) — hardening and sign-in flows |
0 commit comments