Docs/Customers & tenants

Organization scope and offices

Screens 1.1, 1.1A and 1.2 — pick the department then agencies from source reference data, handle source outages, and review office mappings.

PEEK Platform Administrator

/peek/customers/tenant-a/1-1

Live walkthrough · Organization scope and offices

Organization scope and offices — /peek/customers/tenant-a/1-1a — /peek/customers/tenant-a/1-1a

Organization scope and offices — /peek/customers/tenant-a/1-2 — /peek/customers/tenant-a/1-2

Customer setup starts with organization scope. Department and agency lists come from USAspending organization reference data; they identify who the customer is, never who may sign in or what data they may read. The draft stores the external reference IDs and a distinct internal tenant identifier.

1
Select the department
On 1.1 choose a department first; agencies load beneath it.
2
Select agencies
Choose one or more agencies under that department. Changing department clears incompatible agency selections.
3
Save organization scope
Saves a customer draft with source IDs and the source refreshed at timestamp.
4
Review offices
On 1.2 compare source agencies with agency-supplied offices, resolve unmapped offices and Confirm reviewed mapping.

When the source is down — If the organization source is unavailable, 1.1A shows the last successful snapshot, outage reason and retry status. You can still save a clearly labeled incomplete draft, but an unresolved official mapping blocks activation.

1.1 · Department & Agency Selection

Select the department before its agencies. Open it at /peek/customers/tenant-a/1-1 (any tenant ID you can access works in place of tenant-a). The primary action is Save organization scope, which requires organization.read or customer.draft.

How 1.1 works

1. Load department reference list
2. Agencies under the selected department
3. Select scope and save a customer draft

Screen 1.1 contract

Fields shown: Department, agency, source IDs, source refreshed at
Primary action: Save organization scope
Required capability: organization.read or customer.draft
Validation: Parent-child source relationship and source timestamp must be available. Changing department clears incompatible agency selections.
Successful outcome: Draft stores external reference IDs and a distinct internal tenant identifier; no identity or record grant is created.
Screen states: Loading; empty; ready; restricted; stale; error; review pending
Audit event: admin.screen.1.1.action (acceptance test AT-UI-1.1)
Requirements: R01, R02, R06, R28, SYS02, SYS04, SYS06, SYS10, SYS11, SYS20, SYS23, UI-1.1

Boundary — USAspending organization metadata never grants identity or data access.

Rejected even if the browser allows it — Select an agency from another department in the request; reject the mismatch even if the browser allowed it.

1.1A · Organization Source Unavailable

Show source outage and stale reference state. Open it at /peek/customers/tenant-a/1-1a (any tenant ID you can access works in place of tenant-a). The primary action is Retry or save draft, which requires organization.read or customer.draft.

How 1.1A works

1. Show last successful organization snapshot, outage reason and retry
2. Allow a labeled incomplete draft

Screen 1.1A contract

Fields shown: Last successful sync, retry status, selected source snapshot
Primary action: Retry or save draft
Required capability: organization.read or customer.draft
Validation: A stale snapshot cannot be represented as a fresh lookup. Unresolved official mapping blocks activation.
Successful outcome: Retry updates only the reference snapshot; saved scope is not silently reassigned.
Screen states: Loading; empty; ready; restricted; stale; error; review pending
Audit event: admin.screen.1.1a.action (acceptance test AT-UI-1.1A)
Requirements: R02, R06, R28, SYS02, SYS04, SYS06, SYS10, SYS11, SYS20, SYS23, UI-1.1A

Boundary — Do not silently replace official IDs or activate an unresolved organization mapping.

Rejected even if the browser allows it — Lose the source service after choosing an organization; preserve the draft and display the last verified timestamp.

1.2 · Organization & Office Review

Verify offices within the selected customer scope. Open it at /peek/customers/tenant-a/1-2 (any tenant ID you can access works in place of tenant-a). The primary action is Confirm reviewed mapping, which requires customer.draft.

How 1.2 works

1. Compare source agencies and agency-supplied offices
2. Resolve unmapped offices and submit the reviewed hierarchy

Screen 1.2 contract

Fields shown: Agency tree, office mappings, provenance, unmapped offices
Primary action: Confirm reviewed mapping
Required capability: customer.draft
Validation: No cycles, duplicate active mapping or unlabeled local office. A local office cannot acquire an official external ID without evidence.
Successful outcome: Versioned organization mapping records reviewer, provenance and explicit tenant scope.
Screen states: Loading; empty; ready; restricted; stale; error; review pending
Audit event: admin.screen.1.2.action (acceptance test AT-UI-1.2)
Requirements: R01, R02, R06, R28, SYS02, SYS04, SYS06, SYS10, SYS11, SYS20, SYS23, UI-1.2

Boundary — Locally defined offices must be labeled as agency supplied and cannot impersonate source records.

Rejected even if the browser allows it — Move an office across agencies without a reviewed mapping and permission impact; block publication.

Related guides

Customer scope and administrators

Screens 1.3 and 1.3A — define the agency customer boundary, designate initial administrators, and configure department-wide purchases.

Organization changes and impact

Screen 1.7 — review renamed, moved or merged offices and stage effective-dated mapping changes without broadening access.

Activation readiness and completion

Screens 1.5 and 1.5A — evaluate readiness blockers for the purchased configuration, activate the tenant and read the activation receipt.