activator-consumption-cli

name

activator-consumption-cli

description

Inspect existing alerts, notifications, and automated actions in Fabric via read-only REST API calls using `az rest` CLI. Use when the user wants to: (1) list existing alerts in a workspace, (2) inspect how an alert or notification is configured, (3) read and decode an Activator/Reflex definition (ReflexEntities.json), (4) list rules, sources, and actions behind an alert, (5) understand why an alert fires or what action it takes. Triggers: "show my alerts", "what alerts do I have", "inspect this alert", "show me the rule", "show me the action", "show me the source", "get reflex definition", "list activators", "activator details"

Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the check-updates skill (e.g., /fabric-skills:check-updates).
• Claude Code / Cowork / Cursor / Windsurf / Codex: read the local package.json version, then compare it against the remote version via git fetch origin main --quiet && git show origin/main:package.json (or the GitHub API). If the remote version is newer, show the changelog and update instructions.
• Skip if the check was already performed earlier in this session.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

activator-consumption-cli — Read-Only Activator Exploration via CLI

Table of Contents

Task	Reference	Notes
Finding Workspaces and Items in Fabric	COMMON-CLI.md § Finding Workspaces and Items in Fabric	Mandatory — READ link first [needed for workspace/item ID resolution]
Fabric Topology & Key Concepts	COMMON-CORE.md § Fabric Topology & Key Concepts
Authentication & Token Acquisition	COMMON-CORE.md § Authentication & Token Acquisition	Wrong audience = 401
Core Control-Plane REST APIs	COMMON-CORE.md § Core Control-Plane REST APIs
Long-Running Operations (LRO)	COMMON-CORE.md § Long-Running Operations (LRO)	getDefinition may return 202
Rate Limiting & Throttling	COMMON-CORE.md § Rate Limiting & Throttling
Fabric Item Definitions	ITEM-DEFINITIONS-CORE.md § Definition Envelope	Base64 payload structure
Authentication Recipes	COMMON-CLI.md § Authentication Recipes	az login flows
Fabric Control-Plane API via az rest	COMMON-CLI.md § Fabric Control-Plane API via az rest	Always pass --resource https://api.fabric.microsoft.com
LRO Pattern	COMMON-CLI.md § Long-Running Operations (LRO) Pattern
Pagination Pattern	COMMON-CLI.md § Pagination Pattern
Tool Stack	SKILL.md § Tool Stack
Connection

---

Tool Stack

Tool	Purpose	Install
az cli	Fabric REST API calls for reading Activator items and definitions	winget install Microsoft.AzureCLI
jq	JSON processing, Base64 decoding, definition inspection	winget install jqlang.jq

---

Connection

Use the shared authentication guidance in COMMON-CLI.md § Authentication Recipes. Resolve workspace and item IDs per COMMON-CLI.md § Finding Workspaces and Items in Fabric. Examples below assume WS_ID and REFLEX_ID are already resolved.

---

Listing Activator Items

List All Activators in a Workspace

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName, description}'

Required scopes: Workspace.Read.All or Workspace.ReadWrite.All

Paginated Listing

For workspaces with many items, follow the continuationUri returned in each response:

NEXT_URL="https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes"
while [ -n "$NEXT_URL" ]; do
  RESPONSE=$(az rest --method GET \
    --url "$NEXT_URL" \
    --resource "https://api.fabric.microsoft.com")
  echo "$RESPONSE" | jq '.value[] | {id, displayName, description}'
  NEXT_URL=$(echo "$RESPONSE" | jq -r '.continuationUri // empty')
done

Filter by Folder

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes?recursive=true&rootFolderId=${FOLDER_ID}" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName}'

---

Inspecting a Single Activator

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '{id, displayName, description, type, workspaceId}'

---

Reading the Definition

getDefinition is a POST (not GET), requires ReadWrite scopes (Reflex.ReadWrite.All or Item.ReadWrite.All) even for read-only inspection, and may return 202 LRO. Use the fabric_lro helper from COMMON-CLI.md § Long-Running Operations (LRO) Pattern so 202 responses can be polled via the Location header before decoding.

Decode the Full Definition

DEFINITION=$(fabric_lro POST \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  '{}')

echo "$DEFINITION" \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d | jq .

Save Definition to File

DEFINITION=$(fabric_lro POST \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  '{}')

echo "$DEFINITION" \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d | jq . > reflex-entities.json

---

Exploring Rules, Sources, and Actions

Once you have the decoded ReflexEntities.json, use jq to extract specific components.

List All Entity Types

cat reflex-entities.json | jq '[.[] | .type] | sort | group_by(.) | map({type: .[0], count: length})'

List Data Sources

cat reflex-entities.json | jq '.[] | select(.type | endswith("Source-v1")) | {name: .payload.name, type: .type, id: .uniqueIdentifier}'

List Rules

cat reflex-entities.json | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, id: .uniqueIdentifier, shouldRun: .payload.definition.settings.shouldRun}'

List Objects and Their Attributes

# Objects
cat reflex-entities.json | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Object") | {name: .payload.name, id: .uniqueIdentifier}'

# Attributes for a specific object
OBJECT_ID="<object-guid>"
cat reflex-entities.json | jq --arg oid "$OBJECT_ID" '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Attribute" and .payload.parentObject.targetUniqueIdentifier == $oid) | {name: .payload.name, id: .uniqueIdentifier}'

Inspect a Rule's Condition

RULE_ID="<rule-guid>"
cat reflex-entities.json \
  | jq --arg rid "$RULE_ID" '.[] | select(.uniqueIdentifier == $rid) | .payload.definition.instance' -r \
  | jq '.steps[] | {step: .name, rows: [.rows[] | .kind]}'

List Actions (Fabric Item Actions)

cat reflex-entities.json | jq '.[] | select(.type == "fabricItemAction-v1") | {name: .payload.name, itemType: .payload.fabricItem.itemType, itemId: .payload.fabricItem.itemId}'

Summary View

Get a high-level overview of an Activator's configuration:

cat reflex-entities.json | jq '{
  containers: [.[] | select(.type == "container-v1") | .payload.name],
  sources: [.[] | select(.type | endswith("Source-v1")) | {name: .payload.name, type: .type}],
  objects: [.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Object") | .payload.name],
  rules: [.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, active: .payload.definition.settings.shouldRun}],
  actions: [.[] | select(.type == "fabricItemAction-v1") | {name: .payload.name, type: .payload.fabricItem.itemType}]
}'

---

Must / Prefer / Avoid

MUST DO

• Always use --resource https://api.fabric.microsoft.com with az rest
• Always send --body '{}' for getDefinition — it is a POST and omitting the body can cause 411 errors
• Handle LRO responses — getDefinition may return 202; poll the Location header
• Base64-decode the ReflexEntities.json payload before inspection — it is Base64-encoded in the API response
• JSON-parse the definition.instance field in rule entities — it is a JSON-encoded string, not a nested object

PREFER

• Summary view first — give users a high-level overview before diving into individual entities
• Save to file when the definition is large — decode once and explore with jq locally
• Discover IDs dynamically via workspace and item listing + JMESPath filtering
• Paginated listing for workspaces with many Activator items

AVOID

• Hardcoded workspace or item IDs — always resolve dynamically
• Using GET for getDefinition — it is a POST endpoint; GET will return 405
• Attempting to read definitions of items with encrypted sensitivity labels — it will be blocked
• Modifying data — this is a read-only skill; use activator-authoring-cli for write operations

---

Examples

List All Activators and Show Their Rules

# Step 1: List activators
az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {id, displayName}'

# Step 2: For a specific activator, get and decode its definition
az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "Content-Type=application/json" \
  --body '{}' \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d \
  | jq '.[] | select(.type == "timeSeriesView-v1" and .payload.definition.type == "Rule") | {name: .payload.name, active: .payload.definition.settings.shouldRun}'

Inspect a Specific Rule's Full Configuration

# Decode definition and extract rule details
az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "Content-Type=application/json" \
  --body '{}' \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d \
  | jq '.[] | select(.payload.name == "Too hot for medicine") | .payload.definition.instance' -r \
  | jq '.steps[] | {step: .name, details: .rows}'

---

Querying Activation History

Activation history (when rules fired) is not available via the public REST API. It is accessible via the Activator MCP server using the get_activations_for_rule tool.

Prerequisites

Use the shared authentication guidance in COMMON-CLI.md § Authentication Recipes before connecting to the Activator MCP endpoint.

pip install mcp httpx azure-identity aiohttp

Workflow

1. List rules using the public API (getDefinition → decode → filter for Rule entities) to get the rule's uniqueIdentifier
2. Connect to the Activator MCP server and call get_activations_for_rule with the rule ID

MCP Server Connection

The Activator MCP endpoint is at:

https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspaceId}/reflexes/{activatorId}

Use the shared Fabric API authentication guidance from COMMON-CORE.md § Authentication & Token Acquisition. MCP clients should rely on standard Azure identity flows and must not hardcode tokens.

Calling get_activations_for_rule

Connect using the MCP streamable_http_client, then call the tool:

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

# After connecting and initializing the session:
result = await session.call_tool(
    "get_activations_for_rule",
    {
        "getActivationsParams": {
            "workspaceId": "<workspace-id>",
            "artifactId": "<activator-id>",
            "ruleId": "<rule-uniqueIdentifier>",
        }
    },
)

The response contains totalCount and an activations array with details of each time the rule fired.

Available MCP Tools

Tool	Purpose
list_rules	List rules in an Activator (alternative to public API decode)
get_activations_for_rule	Get activation history for a specific rule

---

Agent Integration Notes

• This skill uses the Fabric Items API (/reflexes) for listing and getDefinition for inspection
• No additional data-plane protocols are needed for item/rule inspection — all use az rest with the Fabric API audience
• getDefinition requires ReadWrite scopes even for read-only access — this is a known API requirement
• Activation history requires the MCP server connection (not available via public REST API)
• For creating or modifying Activator items and rules, use the activator-authoring-cli skill