activator-authoring-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-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](../../common/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](../../common/COMMON-CORE.md#authentication--token-acquisition) | Wrong audience = 401 | | Authentication Recipes | [COMMON-CLI.md § Authentication Recipes](../../common/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](../../common/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)](../../common/COMMON-CORE.md#long-running-operations-lro) | Create, getDefinition, updateDefinition may return 202 | | Fabric Item Definitions | [ITEM-DEFINITIONS-CORE.md § Definition Envelope](../../common/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](../../common/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](../../common/COMMON-CLI.md#long-running-operations-lro-pattern) | Poll 202 responses | | Entity Types, Sources & Views | [source-types.md](references/source-types.md) | Entity envelope, source entities, and `timeSeriesView-v1` variants | | Eventstream Source | [eventstream-source.md](references/eventstream-source.md) | Push-source workflow: create Eventstream sink first, then extend the discovered Activator entities | | KQL Source | [kql-source.md](references/kql-source.md) | KQL source schema, time-axis support, design guidance | | Digital Twin Builder / Ontology Source | [dtb-source.md](references/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](references/real-time-hub-source.md) | Real-time Hub source schema, workspace event types | | Rule Conditions | [rule-conditions.md](references/rule-conditions.md) | Rule template structure, detection conditions, aggregation, time windows, occurrence options, enrichments | | Action Types | [action-types.md](references/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 ```python import json, base64, uuid # Stringify template → JSON string for definition.instance instance_string = json.dumps(template_dict, separators=(',', ':')) # Encode entities and write updateDefinition request body payload_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 response response = 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 fields entity_id = str(uuid.uuid4()) ``` --- ## Connection Use the shared authentication guidance in [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes). Resolve workspace and item IDs per [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/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](../../common/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 > `getDefinition` is a **POST** (not GET), requires **ReadWrite** scopes, and may return **202 LRO**. Use the `fabric_lro` helper from [COMMON-CLI.md § Long-Running Operations (LRO) Pattern](../../common/COMMON-CLI.md#long-running-operations-lro-pattern) so 202 responses can be polled via the `Location` header before decoding. ```bash 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 build `update-body.json` (see [Python Patterns](#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: `kqlQueries` for KQL sources, `rthSubscriptions` for 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](references/eventstream-source.md), [kql-source.md](references/kql-source.md), [dtb-source.md](references/dtb-source.md), or [real-time-hub-source.md](references/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 an `Activator` destination first, then read the Activator definition and continue from the auto-created `eventstreamSource-v1` + SourceEvent entities. In public readback, those sink-created entities can appear without explicit `parentContainer`. - For `kqlSource-v1`: the KQL query should return ALL data (do NOT pre-filter conditions — let the rule handle that). Must include `eventhouseItem`, `metadata`, and `queryParameters`. For Fabric Eventhouse/KQL DB sources, use `eventhouseItem: { itemId, workspaceId, itemType: "KustoDatabase" }`. For external ADX/Kusto sources, use `eventhouseItem: { 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: []`, no `eventTimeSettings`, no time filtering) when the underlying data has no reasonable timestamp column and each row represents current state. See [kql-source.md](references/kql-source.md). - For `digitalTwinBuilderSource-v1`: use a DTB / Ontology `connection` item ref `{ itemId, workspaceId, itemType }`, where `itemType` is either `DigitalTwinBuilder` or `Ontology`. `query.queryString` must 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.** Prefer `eventTimeSettings` plus `DURATION_START`/`DURATION_END` query 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](references/dtb-source.md). **Step 3 — SourceEvent view** (exactly 1): - Type: `timeSeriesView-v1`, definition.type: `"Event"`, instance: `SourceEvent` template referencing Source by `entityId` - 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](references/rule-conditions.md)) - `AttributeTrigger` (v1.2.4): ScalarSelectStep → ScalarDetectStep → (DimensionalFilterStep)* → ActStep - `EventTrigger` (v1.2.4): FieldsDefaultsStep → (EventDetectStep)+ → (DimensionalFilterStep)* → ActStep - `instance` **MUST be a JSON string** (use `json.dumps()`) - Every template step inside `instance.steps[]` needs an `id` GUID. Missing step IDs can produce invalid expression graphs because backend translators use the step ID as the output node ID. - For `AttributeTrigger`, set `parentObject` → Object and `parentContainer` → Container - For `EventTrigger`, set `parentContainer` → Container and omit `parentObject` unless 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: false` when 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 `TeamsMessage` actions with dynamic content, preserve the field-specific reference shapes from working readback: inline mixed-content fragments in `headline` / `optionalMessage` use `AttributeReference` with `type: "complex"`, while structured `additionalInformation` entries use `NameReferencePair` + `AttributeReference` / `EventFieldReference` with `type: "complexReference"` and `name: "reference"` Example rule entity: ```python { "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),