Collection Control Domain

The Collection Control domain provides a three-tier control system (client-level, device-level, user-level) for managing what data the AMM agent collects across deployed devices and users.

Controls follow a strict precedence model: Client > Device > User. Client-level controls always take precedence over device-level and user-level controls.

For embedding and endpoint design decisions, see the Design Guidelines.

Tier Overview

Tier	Field	Location	Values	Default
Client	`collection_mode`	Client DTO	`discovery`, `saas_usage`, `disabled`, `deleted`	`saas_usage`
Device	`collection_state`	Device DTO	`enabled`, `disabled`, `deleted`	`enabled`
User	`status`	UserRef / User DTO	`active`, `archived`, `deleted`	`active`

Collection Mode Behavior

Mode	Agent Behavior
`discovery`	Collects device info and installed software only -- no app usage or browsing telemetry
`saas_usage`	Full data collection (default)
`disabled`	All collection stopped; agent sends lightweight heartbeats (device_id + user_id only) to poll for config changes
`deleted`	Agent self-uninstalls. Irreversible.

Precedence Model

The effective collection mode for a device is computed by applying the three tiers in order:

If client.collection_mode is disabled or deleted → effective mode = client mode (overrides everything)
If device.collection_state is disabled or deleted → effective mode = device state
If user.status is archived or deleted → agent stops collecting for that user session, sends lightweight heartbeats
Otherwise → effective mode = client.collection_mode

This is exposed as effective_mode on the full Device DTO.

A single device with multiple OS users can have different user statuses -- only affected user sessions stop collecting.

Irreversibility

Entity	Irreversible State	Behavior
Client	`deleted`	Cannot transition to any other mode. Agent self-uninstalls.
Device	`deleted`	Cannot transition to any other state. Agent self-uninstalls.
User	`deleted`	Cannot transition to any other status. Row retained, no new data. Re-detected users create a new record.

User archived is reversible -- can be reactivated to active at any time.

Endpoints

Control endpoints are distributed across the affected domains:

Client-level

Endpoint	Method	Description
Update Client	PATCH	Change the client's `collection_mode`

Device-level

Endpoint	Method	Description
Update Device Controls	PATCH	Update a single device's `collection_state` and `log_shipping_enabled`
Bulk Enable Devices	POST	Enable collection on multiple devices
Bulk Disable Devices	POST	Disable collection on multiple devices
Bulk Delete Devices	POST	Mark multiple devices as deleted

User-level

Endpoint	Method	Description
Update User	PATCH	Change a single user's `status` (alongside department updates)
Bulk Archive Users	POST	Archive collection for multiple users
Bulk Activate Users	POST	Reactivate collection for multiple users
Bulk Delete Users	POST	Soft-delete multiple users

Audit

Endpoint	Method	Description
Audit Log	GET	Paginated audit trail of all collection control changes

Config Delivery

Agents receive their effective configuration via the heartbeat response. No new polling endpoint is required. The heartbeat response includes:

{
  "ok": true,
  "received_at_utc": "...",
  "config": {
    "collection_mode": "saas_usage",
    "device_state": "enabled",
    "log_shipping_enabled": false,
    "user_status": "active"
  }
}

When disabled/deleted (at any tier), the agent sends lightweight heartbeats containing only device_id, user_id, and generated_at_utc to continue polling for config changes.

Tier Overview​

Collection Mode Behavior​

Precedence Model​

Irreversibility​

Endpoints​

Client-level​

Device-level​

User-level​

Audit​

Config Delivery​