Skill v1.0.0
Trusted Publisher100/100version: "1.0.0" name: activator-authoring-cli description: > Create alerts, notifications, and automated actions on Fabric data and events via Fabric REST API and az rest CLI. Use when the user wants to: (1) create, update, or delete an alert or notification flow, (2) send a Teams message, send an email, or run a Fabric item when something happens, (3) connect alert logic to Eventhouse, Eventstream, Real-time Hub, or Digital Twin Builder / Ontology data, (4) adjust thresholds, filters, event triggers, or actions, (5) troubleshoot or change an existing Activator/Reflex definition. Triggers: "create an alert", "notify me when", "let me know when", "take action when", "send me an email when", "send a teams message when", "run a pipeline when", "update an alert", "delete an alert", "activator rule"
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 thecheck-updatesskill (e.g.,/fabric-skills:check-updates).- Claude Code / Cowork / Cursor / Windsurf / Codex: read the localpackage.jsonversion, then compare it against the remote version viagit 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 NOTES1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering2. 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-authoring-cli — Activator Item & Rule Authoring 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] | |
| Authentication & Token Acquisition | COMMON-CORE.md § Authentication & Token Acquisition | Wrong audience = 401 | |
| Authentication Recipes | COMMON-CLI.md § Authentication Recipes | Use the shared az login / token guidance from common docs | |
| Core Control-Plane REST APIs | COMMON-CORE.md § Core Control-Plane REST APIs | List Workspaces, List Items, Item Creation | |
| Long-Running Operations (LRO) | COMMON-CORE.md § Long-Running Operations (LRO) | Create, getDefinition, updateDefinition may return 202 | |
| Fabric Item Definitions | ITEM-DEFINITIONS-CORE.md § Definition Envelope | Base64-encoded parts structure | |
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 | Poll 202 responses | |
| Entity Types, Sources & Views | source-types.md | Entity envelope, source entities, and timeSeriesView-v1 variants | |
| Eventstream Source | eventstream-source.md | Push-source workflow: create Eventstream sink first, then extend the discovered Activator entities | |
| KQL Source | kql-source.md | KQL source schema, time-axis support, design guidance | |
| Digital Twin Builder / Ontology Source | dtb-source.md | DTB / ontology source schema, JSON-string query payloads, snapshot vs time-axis guidance | |
| Real-time Hub Source | real-time-hub-source.md | Real-time Hub source schema, workspace event types | |
| Rule Conditions | rule-conditions.md | Rule template structure, detection conditions, aggregation, time windows, occurrence options, enrichments | |
| Action Types | action-types.md | TeamsMessage, EmailMessage, FabricItemInvocation action schemas |
Tool Stack
| Tool | Purpose | |
|---|---|---|
| az CLI | Fabric authentication and REST API token acquisition | |
| curl | Header-aware Fabric REST calls through the shared fabric_lro helper | |
| jq | JSON filtering and decoded definition inspection | |
| python | MUST use for building ReflexEntities.json — json.dumps() handles nested stringification correctly. PowerShell's ConvertTo-Json corrupts nested JSON strings. |
⚠️ CRITICAL: Always use Python (not PowerShell) to build the ReflexEntities.json payload and the API request body.
Python Patterns
import json, base64, uuid# Stringify template → JSON string for definition.instanceinstance_string = json.dumps(template_dict, separators=(',', ':'))# Encode entities and write updateDefinition request bodypayload_b64 = base64.b64encode(json.dumps(entities).encode('utf-8')).decode('utf-8')body = json.dumps({"definition": {"parts": [{"path": "ReflexEntities.json", "payload": payload_b64, "payloadType": "InlineBase64"}]}})with open('update-body.json', 'w', encoding='utf-8') as f:f.write(body)# Then: az rest --method POST --url "...updateDefinition" --resource "https://api.fabric.microsoft.com" --body @update-body.json# Decode a getDefinition responseresponse = json.loads(api_output)for part in response['definition']['parts']:if part['path'] == 'ReflexEntities.json':entities = json.loads(base64.b64decode(part['payload']).decode('utf-8'))# Generate GUIDs for uniqueIdentifier and step id fieldsentity_id = str(uuid.uuid4())
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.
Item CRUD
Use the shared mechanics in COMMON-CLI.md § Item CRUD Operations. Activator uses the reflexes endpoint rather than the generic items endpoint:
| Operation | Endpoint | Method | Scopes | Notes | |
|---|---|---|---|---|---|
| Create | /v1/workspaces/{workspaceId}/reflexes | POST | Reflex.ReadWrite.All or Item.ReadWrite.All | May return 202 LRO — use fabric_lro from COMMON-CLI | |
| Update metadata | /v1/workspaces/{workspaceId}/reflexes/{reflexId} | PATCH | Reflex.ReadWrite.All or Item.ReadWrite.All | Follow COMMON-CLI metadata update pattern | |
| Delete | /v1/workspaces/{workspaceId}/reflexes/{reflexId} | DELETE | Reflex.ReadWrite.All or Item.ReadWrite.All | Add ?hardDelete=true for permanent deletion | |
getDefinition | /v1/workspaces/{workspaceId}/reflexes/{reflexId}/getDefinition | POST | Reflex.ReadWrite.All or Item.ReadWrite.All | Empty body required; may return 202 LRO — use fabric_lro | |
updateDefinition | /v1/workspaces/{workspaceId}/reflexes/{reflexId}/updateDefinition | POST | Reflex.ReadWrite.All or Item.ReadWrite.All | Use Python to build update-body.json, then follow COMMON-CLI updateDefinition pattern |
Rule Management via Definitions
Rules are managed through getDefinition and updateDefinition. The payload is ReflexEntities.json, a Base64-encoded JSON array of entity objects. Workflow: Get → Decode → Modify → Re-encode → Update.
Get Definition
getDefinitionis a POST (not GET), requires ReadWrite scopes, and may return 202 LRO. Use thefabric_lrohelper from COMMON-CLI.md § Long-Running Operations (LRO) Pattern so 202 responses can be polled via theLocationheader before decoding.
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 .
Update Definition
MUST use Python to buildupdate-body.json(see Python Patterns), then upload it using the COMMON-CLI updateDefinition pattern against/v1/workspaces/{workspaceId}/reflexes/{reflexId}/updateDefinition.
ReflexEntities.json — Assembly Procedure
Build a JSON array of entities in order. Each needs a fresh GUID for uniqueIdentifier. For the hand-authored pull-source flows in this skill, use templateVersion 1.2.4. For Eventstream sink-created flows, preserve the template version already present in the decoded Activator definition; those readbacks can use 1.1.
Step 1 — Container (exactly 1):
- Type:
container-v1. Use the container payload type that matches the source graph:kqlQueriesfor KQL sources,rthSubscriptionsfor Real-Time Hub workspace subscriptions, or the service-created type already present in readback for Eventstream flows. - All other entities reference this via
parentContainer.targetUniqueIdentifier
Step 2 — Data Source (exactly 1, pick the right type):
- See eventstream-source.md, kql-source.md, dtb-source.md, or real-time-hub-source.md for the supported source workflows
- For hand-authored pull sources, set
parentContainer.targetUniqueIdentifier→ Container GUID - For
eventstreamSource-v1: do not start by hand-authoring the source. Create or update the Eventstream with anActivatordestination first, then read the Activator definition and continue from the auto-createdeventstreamSource-v1+ SourceEvent entities. In public readback, those sink-created entities can appear without explicitparentContainer. - For
kqlSource-v1: the KQL query should return ALL data (do NOT pre-filter conditions — let the rule handle that). Must includeeventhouseItem,metadata, andqueryParameters. For Fabric Eventhouse/KQL DB sources, useeventhouseItem: { itemId, workspaceId, itemType: "KustoDatabase" }. For external ADX/Kusto sources, useeventhouseItem: { clusterHostName, databaseName }. Before creating the Activator, run the KQL directly against the target source first and confirm the returned columns, timestamp field, and row shape are correct. Use `eventTimeSettings` plus `DURATION_START`/`DURATION_END` queryParameters whenever the query results have a reasonable timestamp column, and declare those parameters in the KQL with `declare query_parameters(startTime:datetime, endTime:datetime);`. Only use snapshot mode (queryParameters: [], noeventTimeSettings, no time filtering) when the underlying data has no reasonable timestamp column and each row represents current state. See kql-source.md. - For
digitalTwinBuilderSource-v1: use a DTB / Ontologyconnectionitem ref{ itemId, workspaceId, itemType }, whereitemTypeis eitherDigitalTwinBuilderorOntology.query.queryStringmust be a JSON-string payload, not KQL. Before creating the Activator, run the DTB / Ontology query directly first and confirm the returned columns, key fields, and timestamp field are correct. PrefereventTimeSettingsplusDURATION_START/DURATION_ENDquery parameters when the returned rows include a reasonable timestamp field; unlike KQL, those duration parameters are applied as DTB endpoint URL query params rather than referenced inside the query body. See dtb-source.md.
Step 3 — SourceEvent view (exactly 1):
- Type:
timeSeriesView-v1, definition.type:"Event", instance:SourceEventtemplate referencing Source byentityId - For hand-authored pull-source flows, set
parentContainer→ Container GUID - For Eventstream sink-created flows, reuse the auto-created SourceEvent from readback instead of creating a second one
Step 4 — Choose the entity graph based on trigger type
- For `AttributeTrigger` rules (thresholds, ranges, text matches, boolean checks, aggregations):
- Create an Object view
- Optionally create SplitEvent if events must be mapped to object instances
- Create IdentityPartAttribute and any required BasicEventAttribute entities
- The rule then references those value attributes in
ScalarSelectStep
- For `EventTrigger` rules (fire on every event, heartbeat, event field state/change):
- Use the minimal graph: Container → Source → SourceEvent → Rule (+ optional
fabricItemAction-v1) - Do NOT create Object, SplitEvent, IdentityPartAttribute, or BasicEventAttribute entities unless the scenario truly needs attribute-based modeling
- EventTrigger reads raw event fields directly in
FieldsDefaultsStep/EventDetectStep
Step 5 — Rule (1 per alert):
- Type:
timeSeriesView-v1, definition.type:"Rule" - Always add `"description": "Created by: skills-for-fabric"` for user clarity
- Instance: rule template (see rule-conditions.md)
AttributeTrigger(v1.2.4): ScalarSelectStep → ScalarDetectStep → (DimensionalFilterStep)* → ActStepEventTrigger(v1.2.4): FieldsDefaultsStep → (EventDetectStep)+ → (DimensionalFilterStep)* → ActStepinstanceMUST be a JSON string (usejson.dumps())- Every template step inside
instance.steps[]needs anidGUID. Missing step IDs can produce invalid expression graphs because backend translators use the step ID as the output node ID. - For
AttributeTrigger, setparentObject→ Object andparentContainer→ Container - For
EventTrigger, setparentContainer→ Container and omitparentObjectunless the design explicitly requires it - Default to
settings: { "shouldRun": true, "shouldApplyRuleOnUpdate": false }so newly created rules start in the started / running state - Only set
shouldRun: falsewhen the user explicitly asks for a stopped rule or when a specific safe verification / eval workflow requires a disabled rule to avoid side effects - For
TeamsMessageactions with dynamic content, preserve the field-specific reference shapes from working readback: inline mixed-content fragments inheadline/optionalMessageuseAttributeReferencewithtype: "complex", while structuredadditionalInformationentries useNameReferencePair+AttributeReference/EventFieldReferencewithtype: "complexReference"andname: "reference"
Example rule entity:
{"uniqueIdentifier": "<rule-guid>","payload": {"name": "My Rule Name","description": "Created by: skills-for-fabric", # Required for user clarity"parentObject": {"targetUniqueIdentifier": "<object-guid>"},"parentContainer": {"targetUniqueIdentifier": "<container-guid>"},"definition": {"type": "Rule","instance": stringify_instance(rule_template),"settings": {"shouldRun": True, "shouldApplyRuleOnUpdate": False}}},"type": "timeSeriesView-v1"}
Step 6 — Fabric Item Action (only for FabricItemInvocation):
- Type:
fabricItemAction-v1— use this standalone action entity whenever the rule invokes a Fabric item such as a Pipeline, Notebook, Spark job definition, Dataflow, or UDF / Function Set - See action-types.md for schema
- In the rule's
FabricItemBinding, setfabricJobConnectionDocumentIdto the standalonefabricItemAction-v1.uniqueIdentifier; this is the expected linkage between the binding row and the action entity. - For UDF / function-set actions, author the rule binding with
itemType: "UserDataFunctions". On latergetDefinitionreadback, the standalonefabricItemAction-v1entity may surfacepayload.fabricItem.itemType: "FunctionSet"while the embeddedFabricItemBindingstill showsUserDataFunctions. - For UDF / function-set actions, verify the target item actually exposes a non-empty function list and set
subitemIdto the discovered function name. Parameter names andparameterTypevalues must match the discovered Fabric function metadata exactly; omit parameters that are not exposed by the target function. If the target item has no registered functions, the Activator linkage is incomplete and the action should not be treated as valid.
Entity Wiring Summary
Container ← everything references this via parentContainer│├── Source ← parentContainer → Container│├── SourceEvent ← parentContainer → Container│ │ instance references Source by entityId│ ││ ├── EventTrigger Rule ← parentContainer → Container│ │ minimal event-only path; reads raw event fields directly│ ││ └── Object ← parentContainer → Container│ ││ ├── (SplitEvent) ← OPTIONAL, parentObject → Object, parentContainer → Container│ │ instance references SourceEvent by entityId│ │ maps events to objects via FieldIdMapping│ ││ ├── Identity Attr ← parentObject → Object, parentContainer → Container│ ││ ├── Value Attr(s) ← parentObject → Object, parentContainer → Container│ │ instance references SourceEvent (or SplitEvent if used) by entityId│ ││ └── AttributeTrigger Rule ← parentObject → Object, parentContainer → Container│ instance references Value Attr by entityId in ScalarSelectStep│└── (FabricItemAction) ← parentContainer → Container (for any FabricItemInvocation action: Pipeline, Notebook, Spark job, Dataflow, or UDF / Function Set)
Critical: definition.instance is a JSON String
instance inside timeSeriesView-v1 entity's definition is a JSON-encoded string, not a nested object. Always wrap rule templates in the full entity envelope.
❌ WRONG — raw template object (will fail):
{"templateId": "AttributeTrigger","templateVersion": "1.2.4","steps": [...]}
✅ CORRECT — entity envelope with stringified instance:
{"uniqueIdentifier": "<new-guid>","payload": {"name": "My Rule Name","parentObject": { "targetUniqueIdentifier": "<object-guid>" },"parentContainer": { "targetUniqueIdentifier": "<container-guid>" },"definition": {"type": "Rule","instance": "{\"templateId\":\"AttributeTrigger\",\"templateVersion\":\"1.2.4\",\"steps\":[...]}","settings": { "shouldRun": true, "shouldApplyRuleOnUpdate": false }}},"type": "timeSeriesView-v1"}
Use json.dumps() to stringify. Do NOT use PowerShell's `ConvertTo-Json`.
Two Rule Template Types
| Template | When to Use | Steps | |
|---|---|---|---|
AttributeTrigger | Monitor attribute value (numeric, text, boolean) | ScalarSelectStep → ScalarDetectStep → (DimensionalFilterStep)* → ActStep | |
EventTrigger | Fire on event occurrence (state, change, heartbeat) | FieldsDefaultsStep → (EventDetectStep)+ → (DimensionalFilterStep)* → ActStep |
EventTrigger does NOT have ScalarSelectStep/ScalarDetectStep. Use when acting on events directly. Supports state, change, and heartbeat detection via EventDetectStep.
Must / Prefer / Avoid
MUST DO
- Always use `--resource https://api.fabric.microsoft.com` with
az rest— without it, token audience is wrong - Always send `--body '{}'` for
getDefinition— it is a POST and omitting the body can cause 411 errors - Always Base64-encode
ReflexEntities.jsonpayload when callingupdateDefinition - Always JSON.stringify the
definition.instancefield intimeSeriesView-v1entities — it must be a string, not a nested object. Always wrap rule templates in the full entity envelope (see the ❌/✅ example above) — never output a raw template object without the entity wrapper - Always use the correct template type —
AttributeTriggerfor value-based conditions (has ScalarSelectStep + ScalarDetectStep),EventTriggerfor event-based firing (has FieldsDefaultsStep + EventDetectStep, no ScalarDetectStep) - Always use new GUIDs for
uniqueIdentifierwhen adding entities — duplicate GUIDs cause corruption - Always update all cross-references when changing a
uniqueIdentifier— other entities reference it viatargetUniqueIdentifier - Handle LRO responses —
create,getDefinition, andupdateDefinitionmay return 202; poll theLocationheader
PREFER
- Read-modify-write over full replacement — get the current definition, modify the entity array, and update
- Soft delete over hard delete unless permanent removal is intended
- Discover IDs dynamically via workspace listing + JMESPath rather than hardcoding GUIDs
- Transition-based alert conditions over steady-state conditions for most alerts — prefer detectors such as
NumberBecomes,NumberEntersOrLeavesRange,LogicalBecomes, or explicit change conditions even when the user says casual state-like wording such as "is greater than", "is below", or "is outside the range". Treat ordinary alert wording as "notify me when it crosses into that state" to avoid repeated notifications while the condition remains true - Steady-state conditions such as
IsGreaterThan,IsLessThan, orIsOutsideRangeonly when the user explicitly asks for repeated firing while the value stays in the triggered state, for example "notify me every time it is greater than 30", "fire on every evaluation while it is above 30", or when a downstream occurrence / windowing pattern truly depends on that semantics
AVOID
- Hardcoded workspace or item IDs — always resolve dynamically
- Forgetting the `.platform` part — only include it with
updateDefinitionwhen using?updateMetadata=true - SELECT * without filtering on list endpoints — use pagination for large workspaces
- Modifying definitions of items with encrypted sensitivity labels —
getDefinitionis blocked - Pre-filtering conditions in the KQL query — return all data from KQL and let the Activator rule steps handle thresholds, text conditions, and dimensional filters. KQL is the data source, not the rule engine
- Inline JSON in PowerShell `az rest --body` — PowerShell mangles quotes and special characters. Always write JSON to a temp file with
[System.IO.File]::WriteAllText($path, $json, [System.Text.UTF8Encoding]::new($false))and pass--body @$path - Reusing display names after deletion — soft-deleted items hold their name for several minutes. Use a unique name or hard-delete first
Examples
Follow the Assembly Procedure to build definitions. See reference docs for complete entity schemas: source-types.md, rule-conditions.md, action-types.md.
Agent Integration Notes
- This skill uses the Fabric Items API (
/reflexes) for CRUD and the Definition API for rule management - No additional data-plane protocols are needed — all operations use
az restwith the Fabric API audience - For reading Activator items and rules without modifying them, use the activator-consumption-cli skill instead