Activator Consumption CLI

> 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 | SKILL.md § Connection | |

| Listing Activator Items | SKILL.md § Listing Activator Items | |

| Inspecting a Single Activator | SKILL.md § Inspecting a Single Activator | |

| Reading the Definition | SKILL.md § Reading the Definition | |

| Exploring Rules, Sources, and Actions | SKILL.md § Exploring Rules, Sources, and Actions | |

| Inspecting Power BI Sources | SKILL.md § Inspecting Power BI Sources | powerBiSource-v1, stored query JSON, metricDefinition, report/model lineage |

| Must / Prefer / Avoid | SKILL.md § Must / Prefer / Avoid | |

| Examples | SKILL.md § Examples | |

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}]
}'

Inspecting Power BI Sources

Power BI-backed Activator sources use powerBiSource-v1. The source's parent

container-v1 must use exact case-sensitive payload.type: "pbiMetrics".

The source query.queryString is a JSON-string Power BI source query payload,

and metricDefinition describes the same semantic model metric,

dimensions, filters, and report visual lineage. The Activator API does not

accept semantic-model query text in query.queryString.

> Current public API limitation: Power BI-backed Activator definitions

> cannot currently be relied on for public ALM readback. getDefinition can

> reject an artifact that was imported successfully when PBI ALM export is

> disabled. Preserve the exact response and request/correlation ID, describe

> inspection as unavailable, and do not claim that persistence failed or that

> the source is absent solely because the definition cannot be exported.

Flag a missing parent container or any container type other than pbiMetrics.

In particular, powerBiQueries is invalid.

Parse the Stored Query and Metric Definition

jq -r '.[] | select(.type == "powerBiSource-v1")
  | .payload.query.queryString' reflex-entities.json | jq .

metricDefinition can be either a JSON string or an object. Parse both forms

before explaining the metric:

import json
from pathlib import Path

entities = json.loads(Path("reflex-entities.json").read_text(encoding="utf-8"))
for entity in entities:
    if entity.get("type") != "powerBiSource-v1":
        continue
    payload = entity["payload"]
    metric = payload.get("metricDefinition")
    if isinstance(metric, str):
        metric = json.loads(metric)
    print(json.dumps({
        "sourceName": payload.get("name"),
        "datasetId": payload.get("datasetId") or payload.get("metadata", {}).get("datasetId"),
        "reportId": payload.get("reportId") or payload.get("metadata", {}).get("reportId"),
        "pageId": payload.get("pageId") or payload.get("metadata", {}).get("pageId"),
        "visualId": payload.get("visualId") or payload.get("metadata", {}).get("visualId"),
        "measureName": payload.get("measureName") or payload.get("metadata", {}).get("measureName"),
        "dimensionValue": payload.get("dimensionValue"),
        "metricDefinition": metric,
    }, indent=2))

Persisted Power BI source queries should omit top.

Consistency Checks

Call out any of these issues:

• getDefinition is blocked because PBI ALM export is disabled. Report the

limitation rather than fabricating source details.

• query.queryString or metricDefinition is not parseable JSON.
• The parent container is missing or is not exact pbiMetrics.
• metricDefinition.type is not DatasetMetric.
• Source datasetId, query provider.datasetId, and

metricDefinition.definition.datasetId disagree.

• The persisted query includes top.
• A personalized source has dimensionValue, but the same value is absent

from the query filters or metricDefinition.definition.filter.

• metricDefinition.definition.filter uses BasicFilter instead of the

semantic-query Version / From / Where contract.

• Report, page, visual, or measure lineage is missing.

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
• For Power BI sources, JSON-parse both query.queryString and metricDefinition before explaining metrics, dimensions, or filters

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
• Report Power BI lineage — include dataset/report/page/visual/measure metadata when available
• Flag Power BI filter inconsistencies — especially missing personalized dimension values

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
• Treating Power BI source queries as semantic-model query text — they are source payloads stored as JSON strings

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

• List rules using the public API (getDefinition → decode → filter for Rule entities) to get the rule's uniqueIdentifier
• 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