zia-create-cloud-app-control-rule

What this skill does

# ZIA: Create Cloud App Control Rule

## How to talk to the admin

- Don't narrate tool calls, search filters, JMESPath expressions, or internal lookup logic. Just confirm what was created and which scoping was applied.
- Empty list responses are authoritative. If a `zia_list_*` lookup returns no match for an exact-name search, treat the resource as "does not exist." Do not retry with split keywords or unfiltered listings.
- Don't claim a tool doesn't exist without checking. If `zia_create_*` and `zia_get_*` are visible for a resource, the matching `zia_list_*` exists too.
- Don't narrate strategy pivots. If you have to retry quietly, retry quietly and report only the final outcome.
- After every successful create, **mention the activation step explicitly** — ZIA changes are staged until activated. The agent must call `zia_activate_configuration()` and tell the admin the change is now live.

## Scope of this skill

This skill creates **one or more** Cloud App Control rules per invocation. When the admin names multiple cloud apps in one request, the skill creates **one rule per app** (see "Multi-app handling" below) — that is intentional, not a violation of scope. Anything outside that scope is a hard stop:

- **It does not create** the auxiliary objects the rule references (location IDs, label IDs, group/department/user IDs, device groups, time intervals). If those don't exist, this skill stops and points the admin at the right place to create them — it does not improvise.
- **It does not modify SSL Inspection, Cloud Firewall, URL Filtering, DLP, File Type Control, or any other ZIA rule type.** Those are separate resource types and have their own skills (`zia-create-ssl-inspection-rule`, `zia-create-firewall-filtering-rule`, `zia-create-url-filtering-rule`). Cloud App Control is **not** the same as URL Filtering — URL Filtering blocks at the URL/category level; Cloud App Control allows or blocks specific *operations* (upload, share, edit, comment, attach) inside an application.
- **It does not bypass SSL inspection.** Cloud App Control needs the traffic to be decrypted to enforce action-level decisions. If the traffic is in a `DO_NOT_DECRYPT` SSL Inspection rule, the action enforcement will not happen — surface this as a known limitation if the admin asks why a rule isn't taking effect.

## Hard stop conditions

Stop and report plainly when:

- **The admin's stated cloud app cannot be resolved** to a canonical ZIA name after one targeted lookup. Do not invent canonical names, do not silently substitute a similar app. Hand off to `zia-look-up-cloud-app-name` if the admin needs help finding the right canonical name.
- **The admin asked for an action that doesn't exist on this app's category.** Cloud App Control actions are category-scoped. `BLOCK_FILE_SHARE_UPLOAD` works for `DROPBOX` (category `FILE_SHARE`) but not for `GMAIL` (category `WEBMAIL`, where the equivalent is `BLOCK_WEBMAIL_ATTACH`). Always discover the valid actions for the target app's category first — do not guess action enums.
- **The admin asked for plain "BLOCK" or "ALLOW".** Cloud App Control does not have a connection-level block/allow. Pick the right granular action (e.g. `BLOCK_FILE_SHARE_UPLOAD`, `ALLOW_FILE_SHARE_VIEW`). If the admin really wants a connection-level block of an entire application, that's a Cloud Firewall rule (`zia-create-firewall-filtering-rule`) or URL Filtering rule, not Cloud App Control.
- **The admin's stated location names, user/group/department IDs, label names, or time-interval names cannot be resolved.** Resolve once via the appropriate `zia_list_*` tool; if empty, say so and stop. Do not skip the field, do not invent IDs.
- **`rank` is outside the inclusive range `0..7`.** ZIA's admin rank is a 0-7 integer; the tool will reject any other value before the API call. See [admin rank documentation](https://help.zscaler.com/zia/about-admin-rank).
- **The rule name is longer than 31 characters.** ZIA enforces a hard 31-character maximum on the Cloud App Control rule `name`. The API rejects longer names with `{"code": "INVALID_INPUT_ARGUMENT", "message": "Name exceeds the max length 31 characters"}`. Abbreviate the verb (`"Blk"` for Block, `"Allw"` for Allow, `"Iso"` for Isolate) before truncating the app name — see Step 7 for the worked pattern. This counts **bytes**, not Unicode grapheme clusters; emoji and most accented characters in the name will consume more than one slot.
- **A recurring schedule was requested but no schedule details were provided.** Don't guess. Ask once for `start_time`, `end_time`, and `days_of_week`, then chain to `zia-manage-time-interval`.

Never improvise around a missing dependency — hand off or stop.

## How Cloud App Control differs from other rule types

| Question | Answer for Cloud App Control |
|---|---|
| What does the rule act on? | A specific cloud application (or set of apps in the same category). |
| Is the action applied to the connection or the operation? | The **operation**. The connection still flows, but specific operations (upload, share, edit, comment, post, attach) are allowed, blocked, or isolated. |
| Is the action set the same for every app in a category? | **Mostly, but not strictly.** Action vocabulary is *surfaced* at the category level (every `FILE_SHARE` app's discovery call returns the same enum list; every `AI_ML` app's discovery returns its own list; etc.), and the same action enum is rejected if used with the wrong category. **However**, the create endpoint validates per `(rule_type, app, action)` tuple — a category-level action may still be rejected when paired with one specific app in that category. This is why this skill creates one rule per app rather than combining apps in a single `cloud_applications` list (see "Multi-app handling"). |
| Can a rule cover multiple categories? | **No.** A single rule has exactly one `rule_type` (category). To cover two categories, create two rules. |
| Can a rule cover multiple apps? | **In theory yes** — `cloud_applications` accepts a list — but in practice ZIA frequently rejects multi-app rules with `INVALID_INPUT_ARGUMENT: "Invalid action provided for selected applications"` because per-app action validity varies. **Default to one rule per app.** See "Multi-app handling" below. |
| Does the rule require SSL decryption to take effect? | **Yes** for most actions. If the matching traffic is in a `DO_NOT_DECRYPT` SSL Inspection rule, action enforcement does not happen. |
| Does the rule require an `order`? | **Yes.** ZIA rejects create payloads without `order`. Default is 1 (top of policy table) when omitted. |

## Multi-app handling (one rule per cloud application)

**Pattern: when the admin's request names more than one cloud application — even apps in the same category — create one rule per app, not a single rule with all apps in `cloud_applications`.**

**Why.** Cloud App Control's action enums are surfaced at the *category* level, but the API validates **per `(rule_type, application, action)` tuple**. Two apps in the same category can each accept a slightly different subset of the category's action enums. A rule combining multiple apps with a shared action list frequently fails the create call with:

```json
{
    "code": "INVALID_INPUT_ARGUMENT",
    "message": "Invalid action provided for selected applications"
}
```

The error is total — the create fails for **all** apps in the call, not just the rejected one. There is no API surface that enumerates per-app action validity up front, so the only safe pattern is to split.

**Loop the workflow once per app.** Each iteration reuses the same scoping (users / groups / locations / schedule / device trust), the same `rule_type`, and the same admin intent — only `name`, `cloud_applications`, and `actions` change per iteration. Rule names must be unique **and ≤ 31 characters** (ZIA hard limit), so suffix each with the app's friendly name and abbreviate the verb if needed (e.g. `"Blk upload - Dropbox"`, `"Blk u