Automatic Tagging Rules

A tagging rule tags agents for you. Each rule tests one field — a scan result or a plain inventory field — with a comparison, and asserts a single tag on every device that matches. Instead of hand-tagging machines, you describe the group once (“every agent with less than 20 GB free disk”) and Athena keeps the membership current as inventory changes. Because the tag lands in the same pool as manual tags, you can immediately target it with Commands, Deployment Packages, Scheduled Jobs and Monitors.

Which field a rule tests#

Every rule lives in one of two field universes. Which one it uses depends on whether you attach a scan definition:

Comparison operators#

A condition is field → operator → value. Any of the ten operators can be used with any field:

Create a rule in the console#

Open Settings → Monitoring → Tagging Rules. The section lists every rule with its Name, Condition, Tag, Matches (how many agents currently carry the tag from this rule), Last Evaluated and an Enabled toggle. Choose New Rule to open the editor and fill in:

Saving a rule queues a background fleet sweep and returns immediately; the tag appears on matching devices once the sweep lands. The row’s Matches count and Last Evaluated time refresh when it finishes — there is no live progress bar, so re-open the section to see the result.

Re-evaluate, enable, disable, delete#

Rules re-evaluate automatically as inventory and scans update, but each row also has a Re-evaluate action, and the section header has Re-evaluate All (which sweeps every enabled rule). Both queue a whole-fleet sweep and never block.

Manage rules via the REST API#

The same rule lifecycle is available under /api/tagging-rules. Reading rules requires a Helpdesk (or higher) token; the preview and field catalogue require Operator or Admin; creating, editing, enabling/disabling, deleting and forcing a re-evaluation require Admin.

A scan-field rule attaches a scanDefinitionId; an agent/inventory-field rule omits it, so fieldName is the field path. The operator value is the numeric operator code (for example 0 for equals, 7 for is-less-than):

// Tag every device with less than 20 GB free (scan-field rule)
POST /api/tagging-rules
{
  "name": "Low Disk Space",
  "scanDefinitionId": "550e8400-e29b-41d4-a716-446655440000",
  "fieldName": "FreeGB",
  "operator": 7,
  "value": "20",
  "tag": "LowDisk",
  "isEnabled": true
}

// Tag every domain-joined device (agent-field rule — no scanDefinitionId)
POST /api/tagging-rules
{
  "name": "Domained",
  "fieldName": "DomainName",
  "operator": 0,
  "value": "corp.local",
  "tag": "Domained"
}

Updates use patch semantics: send only the fields you want to change, and a null field is left as-is. Editing the threshold on a rule therefore never renames its tag. A rule cannot be switched between the scan and agent/inventory universes by an update — that’s a delete-and-recreate.

Manage rules via PowerShell#

The Athena PowerShell module wraps the same endpoints. Operators use readable operator names such as LessThan and Equals.

# Scan-field rule: the disk scan runs on the agent, the threshold is checked on the server
New-AthenaTaggingRule -Name "Low Disk Space" -ScanDefinitionId $scanDefId `
    -FieldName "FreeGB" -Operator LessThan -Value "20" -Tag "LowDisk"

# Agent-field rule: no -ScanDefinitionId, so -FieldName IS the agent field path
New-AthenaTaggingRule -Name "Domain joined" -FieldName "DomainName" `
    -Operator Equals -Value "corp.local" -Tag "Domained"

# Park a rule disabled — it asserts nothing until enabled
New-AthenaTaggingRule -Name "Servers" -FieldName "OsVersion" -Operator Contains `
    -Value "Server" -Tag "Server" -Disabled

List rules, and read back their evaluation stats (there is no live progress stream — poll the rule to see a sweep land):

# All rules, or just the enabled ones that assign a given tag
Get-AthenaTaggingRule
Get-AthenaTaggingRule -EnabledOnly -Tag "LowDisk"

# Raise a threshold; -Value never renames the tag
Set-AthenaTaggingRule -Id $ruleId -Value "50"

# Disable a rule — retracts its auto-assigned tags; manual tags are untouched
Set-AthenaTaggingRule -Id $ruleId -Enabled $false

# Force a re-evaluation, then read the result back
Invoke-AthenaTaggingRuleEvaluation -Id $ruleId
Start-Sleep 5
Get-AthenaTaggingRule -Id $ruleId | Select-Object Name, MatchingAgentCount, LastEvaluatedAt

# Delete a rule (retracts its tags). -Force skips the confirmation prompt
Remove-AthenaTaggingRule -Id $ruleId -Force

Where auto tags flow#

An auto tag is indistinguishable from a manual one everywhere a tag is consumed — matching is case-insensitive, and a device needs only one matching tag. That means a single tagging rule can keep a whole workflow current: