zia-look-up-rule-targets

What this skill does

# ZIA: Look Up Rule Targets

## Why this skill exists

Every ZIA rule resource (Cloud Firewall, DNS, IPS, URL Filtering, SSL Inspection, Web DLP, File Type Control, Sandbox, Cloud App Control) scopes by the same set of "who/where/when/what-device" target fields:

- `users`, `groups`, `departments` — who the rule applies to
- `locations`, `location_groups` — where the user is connecting from
- `url_categories` — which URL category the request hits
- `devices`, `device_groups` — which managed device the user is on
- `workload_groups` — which workload (cloud-asset) the connection is to/from
- `labels` — admin-assigned tags for organisation/reporting
- `time_windows` — which time-of-day schedule the rule honours

Every one of those fields takes **IDs** (or, for `url_categories`, **canonical UPPER_SNAKE strings**), not display names. The admin will almost always name them by display name. This skill is the single source of truth for "given a name, find the ID."

Centralising it here means every rule skill (`zia-create-firewall-filtering-rule`, `zia-create-cloud-app-control-rule`, etc.) can chain to this one instead of repeating — and re-decaying — the same lookup table.

## Hard rules (apply to every lookup)

These rules are non-negotiable and override anything a rule skill might say in passing:

1. **Read-before-write.** For every rule target the admin names, run **one** lookup with the appropriate `zia_list_*` tool before assembling the rule payload.
2. **Empty list is authoritative.** If the list call returns no match for an exact-name lookup, the named target **does not exist**. Stop the rule create. Tell the admin plainly. Do not retry with split keywords, broader filters, larger `page_size`, unfiltered listings, or "let me also try without the filter to double-check." One call, one answer.
3. **Never invent IDs.** If a lookup returns nothing, never substitute a similar-looking ID, never skip the field that the admin named, never silently drop it from the payload. The rule payload must reflect the admin's intent verbatim or the workflow stops.
4. **Never narrate the lookup.** Don't tell the admin "I'm searching for the user group `Engineering`…" — just resolve, build the payload, and report what was applied. If you have to retry quietly (e.g. one retry with a different known-good knob, see the `name=` vs `search=` notes), retry quietly and report only the final outcome.
5. **Don't pre-list targets the admin didn't name.** If the admin says "create a rule for users in `Engineering`," resolve only `Engineering`. Don't dump the full user-group list as context, don't enumerate departments, don't list time intervals "in case they want one."
6. **One target kind per call.** Don't try to bundle a user lookup and a location lookup into one tool call.

## Rule-target catalogue

The table below is **the** authoritative mapping for ZIA rule-target fields. Each row gives:

- the canonical field name on the rule payload
- the type the rule expects (list of `int` IDs, or list of `str` UPPER_SNAKE)
- the lookup tool to use, with the **correct** tool name (the project has a few legacy multiplexed tools — those are called out)
- which rule resources accept the field
- known quirks worth remembering at lookup time

| Rule-target field | Payload type | Lookup tool (with knob) | Accepted by which rule types | Notes |
|---|---|---|---|---|
| `users` | `list[int]` IDs | `zia_users_manager(action="read", search="<name>")` | every rule type | Multiplexed legacy tool — `action="read"` is the only supported action via this entrypoint; pagination via `page` + `page_size`. |
| `groups` (= user groups) | `list[int]` IDs | `zia_user_group_manager(action="read", name="<literal>")` | every rule type | Multiplexed legacy tool. **Use `name=`, not `search=`** — server-side `search` is unreliable on this endpoint (sometimes matches user login IDs); the tool's `name=` is a case-insensitive substring match resolved client-side after pulling a wide page. So `name="A000"` reliably finds `A000`, `a000`, `Group_A000`. |
| `departments` (= user departments) | `list[int]` IDs | `zia_user_department_manager(action="read", search="<name>")` | every rule type **except IPS** | Multiplexed legacy tool. Cloud Firewall IPS rules do not expose `departments` on the create payload. |
| `locations` | `list[int]` IDs | `zia_list_locations(query_params={"search": "<name>"})` | every rule type | The `query_params` knob forwards to the SDK; pass `{"search": "<name>"}` for substring match against location name. |
| `location_groups` | `list[int]` IDs | `zia_list_location_groups(name="<exact>", search="<substring>", group_type="Static" \| "Dynamic")` | every rule type | Read-only — the public ZIA API does **not** expose location group create/update/delete. If the admin's named group doesn't exist, the only options are: pick an existing group, or have the admin create one in the ZIA UI first. Group types: `Static` (manually-curated) or `Dynamic` (driven by location attributes). |
| `url_categories` | **`list[str]`** UPPER_SNAKE on most rule types; **`list[int]`** IDs on Web DLP only | `zia_list_url_categories(search="<name>")` for discovery; `zia_get_url_category_predefined(name=...)` for built-in lookups by ID or display name | URL Filtering, SSL Inspection, Web DLP, File Type Control, Sandbox; **not** on Cloud Firewall / DNS / IPS / Cloud App Control | **Two distinct shapes** — Web DLP accepts numeric IDs, every other rule accepts the canonical UPPER_SNAKE category string (e.g. `OTHER_ADULT_MATERIAL`). The list tool returns both fields on every entry; pick the right one for the rule type. **Predefined vs custom matters.** ZIA ships hundreds of curated categories (`FINANCE`, `NEWS_AND_MEDIA`, `OTHER_ADULT_MATERIAL`, etc.) plus any custom categories the admin has created — they share the same API surface but have different lifecycle rules. See "Creating URL categories on the fly" below for the full decision tree, including when to chain to the predefined-only mutation tools. |
| `devices` | `list[int]` IDs | `zia_list_devices(name="<name>")` (or `zia_list_devices_lite` for ID-only payloads) | Cloud Firewall, DNS, IPS, URL Filtering, SSL Inspection, File Type Control, Cloud App Control; **not** Sandbox / Web DLP | These are the same devices ZCC manages. Disabling the `zcc` service does NOT remove the ZIA device tools — they're an intentional cross-service overlap. Use `_lite` when you only need IDs (faster on large tenants). |
| `device_groups` | `list[int]` IDs | `zia_list_device_groups(search="<name>")` | same as `devices` | Same cross-service-overlap caveat as `devices`. |
| `workload_groups` | `list[int]` IDs | `zia_list_workload_groups(query="[?name=='<exact>']")` | **only Cloud Firewall, URL Filtering, SSL Inspection, Web DLP** | Read-only via this server. The ZIA list endpoint does **not** support a server-side `name` filter — use a JMESPath `query` to filter client-side (e.g. `query="[?name=='WG-AWS-Prod']"`). Workload group authoring (with its expression DSL) is intentionally left to the ZIA UI. |
| `labels` | `list[int]` IDs | `zia_list_rule_labels(search="<name>")` | every rule type | Labels are the project's own organisational tagging — separate from URL categories or any other classification. Has full CRUD if the admin asks to create one. |
| `time_windows` (= time intervals) | `list[int]` IDs | **chain to `zia-manage-time-interval`** (sub-skill) | every rule type **except SSL Inspection** | SSL Inspection has no `time_windows` field on the API — time-of-day enforcement on encrypted traffic must be done on a different rule type. The sub-skill handles find-or-create; never create the time interval inline. |

## Lookup pattern (apply to every row)

For every rule target the admin names:

1. Pick the row from the table above.
2. Make exactly one call to the listed tool, with the listed knob, using the admin's literal name.
3. Examine the response:
   - **One match** → take its `id` (or, for `url_cat