zia-create-cloud-app-control-rule

name

zia-create-cloud-app-control-rule

description

Create ZIA Cloud App Control rules that enforce granular, action-level decisions on cloud applications (Dropbox, OneDrive, Google Drive, ChatGPT, GitHub, YouTube, Slack, etc.). Cloud App Control is action-level, not block/allow at the connection layer — actions are things like ALLOW_FILE_SHARE_UPLOAD, BLOCK_WEBMAIL_ATTACH, ISOLATE_AI_ML_WEB_USE, DENY_AI_ML_CHAT, BLOCK_SOCIAL_NETWORKING_POST. Each rule belongs to a category (rule_type) such as FILE_SHARE, WEBMAIL, AI_ML, SYSTEM_AND_DEVELOPMENT, SOCIAL_NETWORKING, STREAMING_MEDIA, etc. Action vocabulary is surfaced at the category level, but the API validates per (rule_type, application, action) tuple — combining multiple apps in a single rule frequently fails with INVALID_INPUT_ARGUMENT, so this skill creates one rule per cloud application when the admin names multiple apps. Use when an admin asks to 'allow Dropbox uploads', 'block ChatGPT', 'restrict GitHub edits', 'isolate AI tools', 'block YouTube uploads', 'allow only viewing on OneDrive', 'block file uploads to personal cloud storage (Dropbox, Google Drive, OneDrive)', or 'create a Cloud App Control rule for X'. Chains to `zia-look-up-cloud-app-name` and `zia-manage-time-interval` when needed.

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.
• 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:

{
    "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 upload - GDrive", "Blk upload - OneDrive"). Step 7 has the full abbreviation pattern.

Admin request	Resulting rules
"Block uploads on Dropbox, Google Drive, and OneDrive for Finance"	3 rules — one each for cloud_applications=["DROPBOX"], ["GDRIVE"], ["ONEDRIVE"], every rule scoped to the Finance group.
"Allow viewing on SharePoint but block sharing"	1 rule (single app).
"Block all file-sharing apps"	Enumerate category members via zia_list_cloud_app_policy(app_class="FILE_SHARE", query="[*].app"), then loop one rule per app.

Why not one rule per category instead? Tempting, but every app added to cloud_applications re-runs the per-app validation on the server. The first incompatible (app, action) pair fails the entire create. One rule per app removes the ambiguity entirely and makes each rule individually auditable in the ZIA UI.

After all rules in the loop have been created, activate once at the end (Step 8) — a single activation flushes them all.

Action vocabulary (a few illustrative examples)

The exact enums vary per category — always discover them via zia_list_cloud_app_control_actions(cloud_app=<app>) before creating a rule. For reference, here are typical patterns:

Category	Sample apps	Sample actions
FILE_SHARE	DROPBOX, BOX, ONEDRIVE, GOOGLE_DRIVE	ALLOW_FILE_SHARE_VIEW, ALLOW_FILE_SHARE_UPLOAD, ALLOW_FILE_SHARE_CREATE, ALLOW_FILE_SHARE_DELETE, ALLOW_FILE_SHARE_DOWNLOAD, ALLOW_FILE_SHARE_EDIT, ALLOW_FILE_SHARE_FORM_SHARE, ALLOW_FILE_SHARE_RENAME, ALLOW_FILE_SHARE_SHARE, DENY_FILE_SHARE_CREATE, DENY_FILE_SHARE_DELETE, DENY_FILE_SHARE_EDIT, DENY_FILE_SHARE_FORM_SHARE, DENY_FILE_SHARE_RENAME, FILE_SHARE_CONDITIONAL_ACCESS, BLOCK_FILE_SHARE_UPLOAD, BLOCK_FILE_SHARE_DOWNLOAD, BLOCK_FILE_SHARE_SHARE, CAUTION_FILE_SHARE, DENY_FILE_SHARE_UPLOAD, DENY_FILE_SHARE_VIEW, FILE_SHARE_CONDITIONAL_ACCESS
WEBMAIL	GMAIL, GOOGLE_WEBMAIL, OUTLOOK_WEB_ACCESS, YAHOO_WEBMAIL	ALLOW_WEBMAIL_VIEW, ALLOW_WEBMAIL_ATTACHMENT_SEND, ALLOW_WEBMAIL_SEND, BLOCK_WEBMAIL_ATTACH, BLOCK_WEBMAIL_SEND, BLOCK_WEBMAIL_VIEW CAUTION_WEBMAIL, CAUTION_WEBMAIL_VIEW
AI_ML	CHATGPT_AI, GEMINI, ANTHROPIC_CLAUDE, MICROSOFT_COPILOT	ALLOW_AI_ML_WEB_USE, DENY_AI_ML_CHAT, DENY_AI_ML_WEB_USE, ISOLATE_AI_ML_WEB_USE, CAUTION_AI_ML_WEB_USE
SYSTEM_AND_DEVELOPMENT	GITHUB, GITLAB, AZURE_DEVOPS, JIRA	ALLOW_SYSTEM_DEVELOPMENT_CREATE, BLOCK_SYSTEM_DEVELOPMENT_EDIT, BLOCK_SYSTEM_DEVELOPMENT_SHARE, DEV_CONDITIONAL_ACCESS
STREAMING_MEDIA	YOUTUBE, NETFLIX, VIMEO, TWITCH	ALLOW_STREAMING_VIEW, BLOCK_STREAMING_UPLOAD, CAUTION_STREAMING
SOCIAL_NETWORKING	FACEBOOK, TWITTER, LINKEDIN, INSTAGRAM	ALLOW_SOCIAL_NETWORKING_VIEW, BLOCK_SOCIAL_NETWORKING_POST, BLOCK_SOCIAL_NETWORKING_CHAT
INSTANT_MESSAGING	SLACK, MICROSOFT_TEAMS, DISCORD, WHATSAPP	ALLOW_CHAT, BLOCK_FILE_TRANSFER_UPLOAD, BLOCK_FILE_TRANSFER_DOWNLOAD
ENTERPRISE_COLLABORATION	ZOOM, WEBEX, GOOGLE_MEET, MICROSOFT_TEAMS_MEETING	ALLOW_COLLABORATION_VIEW, BLOCK_COLLABORATION_RECORD, BLOCK_COLLABORATION_SHARE_FILE

Action prefixes mean:

• ALLOW_* — permit the operation.
• BLOCK_* / DENY_* — deny the operation outright.
• CAUTION_* — show the user a warning page; they can proceed by acknowledging.
• ISOLATE_* — hand the session to Browser Isolation (requires Isolation entitlement).
• *_CONDITIONAL_ACCESS — apply Conditional Access policy logic.

The treatment of "view-only" mode is typically ALLOW_*_VIEW paired with BLOCK_*_UPLOAD / BLOCK_*_DOWNLOAD / BLOCK_*_SHARE in the same rule.

Workflow

Step 1: Gather requirements from the admin

Required:

• Rule name — hard ZIA limit of 31 characters; longer names are rejected with {"code": "INVALID_INPUT_ARGUMENT", "message": "Name exceeds the max length 31 characters"}. Plan for this before the create call, especially in multi-app loops where each rule needs a unique name (see Step 7 for the abbreviation pattern).
• Target cloud application(s) — the app or apps the admin wants to govern (e.g. "Dropbox", "ChatGPT", "GitHub", "YouTube", "personal cloud storage like Dropbox, Google Drive, and OneDrive"). Friendly names are OK; the resolver in Step 2 will translate them. If the admin names multiple apps, the skill will create one rule per app — see "Multi-app handling" above. When the admin describes a kind of app rather than naming individual ones ("all file-sharing apps", "every AI tool"), enumerate the apps in that category with zia_list_cloud_app_policy(app_class=<category>, query="[*].app") and confirm the list with the admin before continuing.
• What operations to allow / block / isolate — the admin's intent in plain language. Examples: "allow viewing but block uploads", "block any file sharing", "isolate the session", "let users chat but block file transfers".
• order — 1-based position in the evaluation sequence (order=1 is the top, evaluated first; ZIA evaluates rules top-to-bottom and stops at the first match). The tool defaults to 1 when omitted, but always pass order explicitly when the tenant already has Cloud App Control rules of the same rule_type — derive the value from the safety checks in Step 6: Rule placement and safety checks (mandatory) instead of guessing.
• rank — admin rank, integer in the inclusive range 0..7. The tool defaults to 7 (highest) when omitted; this matches ZIA's documented default. See admin rank documentation.

At least one matching criterion (otherwise the rule is too broad to be useful):

• The cloud application(s) themselves (cloud_applications=[...])
• Users / groups / departments
• Locations / location groups
• Device trust levels / devices / device groups
• User-agent types (e.g. browser-only enforcement)
• A time-of-day window (Time Interval)
• A validity window (enforce_time_validity + validity_start_time / validity_end_time / validity_time_zone_id) for temporary rules

Optional:

• Description, rank (1-7), order (defaults to top), labels, size/time quotas

Step 2: Resolve each cloud application to a canonical enum

The admin will usually name app(s) in plain English ("Dropbox", "ChatGPT", "Microsoft OneDrive", "Google Drive"). Cloud App Control needs the canonical ZIA enum for each one (DROPBOX, CHATGPT_AI, ONEDRIVE, GDRIVE).

Resolve every app the admin named individually. When the admin names N apps in one request, treat this as N independent resolutions (and, downstream, N independent rule creates — see "Multi-app handling" above).

For each named app:

1. Call zia_list_cloud_app_policy(search="<app name>", query="[*].{app: app, name: appName, parent: parent}").
2. The policy catalog returns each entry as {"app": "<canonical enum>", "appName": "<display name>", "parent": "<category>", "parentName": "<category display name>"}. Always use the app field (the canonical enum, e.g. GDRIVE) as the value for the rule's cloud_applications. Never pass the display name (appName, e.g. "Google Drive") — the create API rejects it.
3. Note the parent field — this is the category the app belongs to, and it becomes the rule's rule_type in Step 3.

If a search returns nothing, the app is not in the policy-engine catalog — stop and tell the admin. Do not fall back to Shadow IT analytics (zia_list_shadow_it_apps) — that's a different catalog and its IDs are not valid Cloud App Control inputs.

If a search returns multiple plausible matches (e.g. "sharepoint" → SHAREPOINT_ONLINE and SHAREPOINT_FOR_BUSINESS), ask the admin which one they want before moving on. Do not silently pick one.

The create/update tools also auto-resolve friendly names via the policy-engine catalog — but doing the resolution explicitly in this step keeps the audit trail clean, lets you confirm ambiguous matches, and gives you the parent value you need for Step 3.

For deeper canonical-name lookup help, chain to zia-look-up-cloud-app-name.

Step 3: Discover the rule_type and the available actions for each app

Call once per canonical enum from Step 2 (even when multiple apps share a category — the per-app call confirms the category mapping and the action vocabulary for that specific app's branch):

zia_list_cloud_app_control_actions(cloud_app="<canonical enum>")

The response is a structured dict. The fields that matter for rule creation:

• category — pass this as rule_type on the create call (it should match the parent you noted in Step 2).
• actions — the category's action enum vocabulary. Pick the subset that matches the admin's stated intent for this app.
• resolved_app — confirms how the input was resolved.
• actions_surfaced_via — diagnostic; the app the API actually returned actions for (may differ from resolved_app because not every app in a category is a "representative" the API surfaces actions for — the tool walks the category until it finds one that does).

Important caveat about the returned actions list. It is the category's full vocabulary, not a per-app validity list. The ZIA API validates each (action, app) pair at create time, and an action returned here may still be rejected when paired with a specific app in the same category. There is no read-only call that enumerates per-app action validity — the create call is the only authoritative validator. If a create fails with INVALID_INPUT_ARGUMENT: "Invalid action provided for selected applications", pare the actions list down to the subset the admin actually asked for and retry; see Step 7.

Why you cannot skip this step: action enum vocabulary varies per category. Hand-typing BLOCK_DROPBOX_UPLOAD will be silently rejected by ZIA — the real enum is BLOCK_FILE_SHARE_UPLOAD (and only valid because Dropbox is in FILE_SHARE).

If the admin's intent maps to multiple actions, pass them all (e.g. actions=["ALLOW_FILE_SHARE_VIEW", "BLOCK_FILE_SHARE_UPLOAD", "BLOCK_FILE_SHARE_SHARE"] for "view-only on Dropbox"). If the admin's intent doesn't map to any actions in the returned set, stop and ask — don't substitute.

Step 4: Resolve shared operands (read-before-write)

For every user, group, department, location, location group, device, device group, label, or time interval the admin named, delegate to zia-look-up-rule-targets to get the IDs. That skill is the single source of truth for these lookups and enforces the project's hard rules (one call per rule target, empty list = does not exist, never invent IDs, never narrate). Cloud App Control accepts every shared rule-target field listed there except url_categories and workload_groups (CAC is operation-level inside an app — its scoping uses cloud applications, not URL categories or workload groups).

Stop and report if any lookup is empty — never invent IDs, never substitute.

Step 5: Resolve the schedule (only if the admin asked for time-of-day scoping)

If the admin's request includes any time-of-day language ("during business hours", "after hours", "weekends only", "between 8am-5pm Mon-Fri", "block YouTube at lunch"), chain to zia-manage-time-interval to find or create the Time Interval and obtain its interval_id. That ID becomes the time_windows=[<id>] value on the rule.

If the admin did not mention a schedule, leave time_windows unset. Don't invent a default.

For a temporary rule (e.g. "block this during a 30-day audit window") use enforce_time_validity=True + validity_start_time + validity_end_time + validity_time_zone_id instead — that's an absolute date range, distinct from the recurring weekly window of time_windows.

Do not call zia_activate_configuration() from within zia-manage-time-interval when chaining — defer activation to the end of this skill so a single activation flushes both the new Time Interval and the new Cloud App Control rule.

Step 6: Rule placement and safety checks (mandatory)

Before building the create call, run a short policy review. Cloud App Control rules sit in a single top-to-bottom evaluation table per rule_type — first match wins. Creating a rule blindly is the most common way to silently disable existing rules or duplicate work that's already in place.

Evaluation model in one paragraph. The policy table is evaluated top to bottom (order=1 is the top, evaluated first); the first rule whose criteria match the traffic wins and no further rules are consulted for that connection. A more general rule placed above a more specific rule will shadow the specific one. Deny / Block actions must sit above any Allow rule that could match the same traffic — otherwise the Allow wins and the Deny never fires.

Pull the current policy table once. Use a single discovery call and reuse its result for all four checks below:

zia_list_cloud_app_control_rules(
    rule_type=<category from Step 3>,
    query="[?enabled].{id: id, name: name, order: order, actions: actions, cloud_applications: cloud_applications}",
)

Required checks — every create must pass all four:

a. Specificity. The new rule must target a specific cloud application (or a small set of related apps in the same category) and at least one additional scoping dimension (users / groups / departments / locations / devices / time window / device trust / user-agent type). A rule with only cloud_applications and no other scoping is acceptable only when the admin explicitly asked for a tenant-wide policy ("everyone, everywhere"); confirm that intent before continuing.

b. Shadowing. For every existing enabled rule whose order is above the proposed position, ask: would it match the same traffic this new rule is meant to govern? If yes, the new rule will be shadowed (never reached). Either move the new rule above the conflicting rule(s), or ask the admin whether the conflicting rules should be narrowed. Never proceed silently with a shadowed rule.

c. Duplicate purpose. Scan the same result for any existing enabled rule whose actions + cloud_applications + key scoping (users / locations / device trust) effectively performs what the admin is asking for. If one is found, stop and report the matching rule (name + ID) to the admin — ask whether they want to modify the existing rule (zia_update_cloud_app_control_rule) rather than creating a parallel one. Creating a duplicate is almost always a configuration error.

d. Deny supersedes Allow. If the new rule uses a BLOCK_* or DENY_* action, scan the result for any enabled rule with an ALLOW_* action whose cloud_applications covers the same app(s) (or a superset). The new Deny rule must sit above every such Allow rule — compute the lowest order value among those Allow rules and set the new rule's order to a value strictly less than that. The Deny itself must also be specific (per check a) — it should not be broader than the operation the admin actually wants to block.

Choosing the final order value.

• If checks b–d produced a constraint (e.g. "must be above order 5"), pick a value that satisfies it. ZIA renumbers the table around the insertion.
• If no constraint was produced, default to order=1 (top) for restrictive new rules and a higher number (near the bottom) for permissive baseline rules that should only catch traffic nothing else governed.
• Always pass order explicitly when the tenant already has Cloud App Control rules of the same rule_type — never rely on the tool default.

Surface the chosen order and the reason for it in the echo-back at the end (Step 9), so the admin can see the placement decision was deliberate.

Step 7: Build and create the rule(s)

Loop once per app from Step 2 — one create call per canonical enum. Reuse the same scoping (users / groups / locations / schedule / device trust), same rule_type, same admin intent; only name, cloud_applications, and actions change per iteration:

zia_create_cloud_app_control_rule(
    rule_type=<category from step 3, e.g. "FILE_SHARE">,
    name=<rule name (max 31 chars); make per-app names distinct — see below>,
    actions=[<one or more action enums from step 3>],
    cloud_applications=[<exactly one canonical enum from step 2>],
    description=<optional>,
    enabled=True,
    rank=<0-7, default 7>,                     # always send; tool defaults to 7
    order=<1-based position, default 1>,       # always send; tool defaults to 1 (top)
    device_trust_levels=[...],                 # ANY, LOW_TRUST, MEDIUM_TRUST, HIGH_TRUST, UNKNOWN_DEVICETRUSTLEVEL
    user_agent_types=[...],
    locations=[...],
    location_groups=[...],
    groups=[...],
    departments=[...],
    users=[...],
    time_windows=[<interval_id>],              # only if schedule was requested
    labels=[...],
    devices=[...],
    device_groups=[...],
    enforce_time_validity=<bool>,
    validity_start_time=<...>,
    validity_end_time=<...>,
    validity_time_zone_id=<...>,
    size_quota=<KB>,
    time_quota=<minutes>,
)

Notes on the call:

• rule_type is required and must match the category returned by zia_list_cloud_app_control_actions for the app — passing the wrong category for the chosen actions is the #1 way to get a 400 from this API.

• actions is required and must be a subset of the action list returned in step 3 for the same category.

• cloud_applications should contain exactly one canonical enum — see "Multi-app handling" at the top of this skill. The field maps internally to the SDK's applications kwarg; we surface it as cloud_applications to stay consistent with other ZIA rule tools (SSL Inspection, Web DLP, File Type Control). Friendly names are auto-resolved; if any name is auto-resolved, the response includes a _cloud_applications_resolution audit field — surface it when echoing back to the admin so they see exactly which canonical enum each input became.

• name must be unique per app AND fit inside ZIA's 31-character hard limit. ZIA rejects duplicate rule names; when looping for N apps, suffix the name with the app's friendly name. Exceeding 31 characters returns {"code": "INVALID_INPUT_ARGUMENT", "message": "Name exceeds the max length 31 characters"} — count the characters before submitting. Examples (all ≤ 31):

  Intent	Bad (32+ chars)	Good (≤ 31 chars, plain ASCII)
  Block uploads, multi-app loop	"Block uploads — Microsoft OneDrive" (35)	"Blk upload - OneDrive" (21), "Blk upload - GDrive" (19), "Blk upload - Dropbox" (20)
  View-only, single app	"Dropbox view-only for Finance team" (34)	"DBX view-only - Finance" (23)
  Isolate AI tools	"Isolate ChatGPT for engineering" (32)	"Iso ChatGPT - Eng" (17)

  Abbreviation pattern when you're tight: shorten the verb first ("Block" → "Blk", "Allow" → "Allw", "Isolate" → "Iso", "Deny" → "Dny"), then drop articles and prepositions, then trim the app name to its common short form ("OneDrive", "GDrive", "DBX", "ChatGPT"). Keep the app suffix readable so the admin can still identify which rule is which in the ZIA UI. When you're at the edge of the limit, prefer plain ASCII separators (-) over typographic ones (—) — multi-byte characters can be counted differently by different parts of the ZIA stack, so plain ASCII is the safe default.

• Capture the returned id from each call.

Error handling — INVALID_INPUT_ARGUMENT: "Invalid action provided for selected applications". ZIA validates each (action, app) pair at create time, and a category-level action may not be valid for a specific app in that category. If you hit this error:

1. Pare the actions list down to the minimal subset the admin actually asked for (drop any "while I'm here" extras).
2. Retry the create for that specific app.
3. If a single action still fails, the action genuinely doesn't apply to that app — confirm with the admin and either substitute a different action they're happy with, or skip that app from the loop and tell the admin which apps were skipped and why.

Do not silently change cloud_applications to a different app to make the action accept. Do not silently combine apps into a single rule to "save a call" — that's the exact pattern this error exists to prevent.

Step 8: Activate the configuration

ZIA changes are staged until activation. After all the rules in your loop (Step 7) have been created — not after each individual create — run one activation:

zia_activate_configuration()

A single activation flushes every staged change at once; activating per-rule is unnecessary and slower. Tell the admin: " Cloud App Control rule(s) created (IDs <id1>, <id2>, …) and activated." If activation fails, surface the error — the rules exist but are not live.

Step 9: Echo back what was applied

Confirm in plain language. For a single rule, one block. For a multi-app loop, one block per rule:

• The rule name.
• The cloud application it applies to (use the friendly display name, not the enum, when speaking to the admin).
• Each granular action that was applied, in human terms ("uploads blocked, viewing allowed, sharing blocked").
• Each scoping dimension that was applied (one bullet per — users, locations, schedule, device trust, etc.).
• The rule_type (category), so the admin knows where to find the rule in the ZIA UI.
• The chosen order and a one-line reason ("placed above the existing 'Allow Dropbox' rule so the new block fires first", or "placed at top — no existing rules in this category"), so the admin can see the placement was deliberate.
• The activation status (one line at the end, covers the whole batch).

For a multi-app loop, also list any apps that were skipped and why (e.g. "Box was skipped — the requested BLOCK_FILE_SHARE_UPLOAD action is not valid for BOX and no equivalent action exists in this tenant"). Never hide a partial outcome.

Don't restate operand IDs or internal field names that the admin doesn't need to see. Don't restate the _cloud_applications_resolution audit verbatim — paraphrase ("'Dropbox' → DROPBOX, 'OneDrive' → ONEDRIVE").

Quick Reference

Tools used:

• Discovery: zia_list_cloud_app_policy(search=...) — find the canonical app enum and its parent category.
• Discovery: zia_list_cloud_app_control_actions(cloud_app=...) — find the category (rule_type) and valid actions for the target app. Always call this before create.
• Read: zia_list_cloud_app_control_rules(rule_type=..., search=...) — required before every create to run the Step 6 safety checks (specificity, shadowing, duplicate purpose, Deny-above-Allow). rule_type is required by the SDK.
• Read: zia_get_cloud_app_control_rule(rule_type=..., rule_id=...) — fetch a specific rule (also used as the implicit pre-step inside update for silent backfill of name).
• Write: zia_create_cloud_app_control_rule(rule_type, name, actions, cloud_applications, ...).
• Write: zia_update_cloud_app_control_rule(rule_type, rule_id, ...) — partial updates work; the tool silently backfills name from the existing rule when omitted.
• Write: zia_delete_cloud_app_control_rule(rule_type, rule_id) — destructive, returns an HMAC confirmation token first; pass it back to confirm.
• Activation: zia_activate_configuration().

Schedule sub-skill:

• zia-manage-time-interval — chain whenever the admin's request mentions time-of-day or day-of-week.

Cloud-app enum sub-skill:

• zia-look-up-cloud-app-name — chain when the admin's app name is ambiguous, mistyped, or when you need to confirm the canonical name before discovery.

Related ID-resolution tools:

• Shared rule targets (users, groups, departments, locations, location groups, devices, device groups, labels, time windows): handled by zia-look-up-rule-targets. CAC does not use url_categories or workload_groups.
• CAC-specific discovery: zia_list_cloud_app_policy, zia_list_cloud_app_control_actions.

Related skills

• zia-look-up-rule-targets — shared name-to-ID lookups for users, groups, departments, locations, location groups, devices, device groups, labels, and time windows. Chain to it from Step 4.
• zia-look-up-cloud-app-name — friendly-name → canonical-name lookups (see Step 2).
• zia-manage-time-interval — find-or-create helper for schedule scoping (see Step 5).

Different ZIA rule types — do not chain through this skill:

• zia-create-ssl-inspection-rule — SSL Inspection is a separate resource type. If the admin wants Cloud App Control to enforce action-level decisions on encrypted traffic, the matching connections must already be DECRYPT'd by an SSL Inspection rule — that's a separate prerequisite, not part of this skill.
• zia-create-firewall-filtering-rule — for connection-level allow/block of an entire application, that's a Cloud Firewall rule, not Cloud App Control.
• zia-create-url-filtering-rule — for URL- or category-level allow/block, that's URL Filtering. Cloud App Control is operation-level inside an app, not URL-level.
• File Type Control / Web DLP / Sandbox / Cloud Firewall DNS / Cloud Firewall IPS rules — also separate resource types.

Typical chain when a schedule is requested:

for each app the admin named:
    zia_list_cloud_app_policy(search="<app>")       (find canonical enum + parent category)
            ↓
    zia_list_cloud_app_control_actions(cloud_app=…) (find rule_type + valid actions)

zia-manage-time-interval                            (find or create the Time Interval, return its ID)
        ↓
zia_list_cloud_app_control_rules(rule_type=…)       (Step 6 safety checks: specificity, shadowing,
                                                     duplicate purpose, Deny-above-Allow)
        ↓
for each resolved app:
    zia_create_cloud_app_control_rule(…)            (one rule per app — see "Multi-app handling")
        ↓
zia_activate_configuration()                        (one activation flushes the whole batch)

Pre-list the existing rules once, but stay scoped. The Step 6 safety checks require one zia_list_cloud_app_control_rules(rule_type=<category>) call so the agent can reason about placement, shadowing, duplicate purpose, and Deny-above-Allow ordering. Reuse that single result for all four checks across every iteration of the create loop — don't fan out additional list calls per app, and don't list rules outside the target rule_type.