# Activator Authoring Cli

> >

- **Type:** Skill
- **Install:** `agentstack add skill-microsoft-skills-for-fabric-activator-authoring-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [microsoft](https://github.com/microsoft)
- **Source:** https://github.com/microsoft/skills-for-fabric/tree/main/plugins/fabric-skills/skills/activator-authoring-cli

## Install

```sh
agentstack add skill-microsoft-skills-for-fabric-activator-authoring-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **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": "",
    "payload": {
        "name": "My Rule Name",
        "description": "Created by: skills-for-fabric",  # Required for user clarity
        "parentObject": {"targetUniqueIdentifier": ""},
        "parentContainer": {"targetUniqueIdentifier": ""},
        "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
- In the rule's `FabricItemBinding`, set `fabricJobConnectionDocumentId` to the standalone `fabricItemAction-v1.uniqueIdentifier`
- See [action-types.md](references/action-types.md) for per-target schemas and UDF-specific gotchas (`itemType` vs readback `FunctionSet`, `subitemId`, canonical `parameterType` mapping, dynamic parameter shape)

### Entity Wiring Summary

```text
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, parentContai

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [microsoft](https://github.com/microsoft)
- **Source:** [microsoft/skills-for-fabric](https://github.com/microsoft/skills-for-fabric)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-microsoft-skills-for-fabric-activator-authoring-cli
- Seller: https://agentstack.voostack.com/s/microsoft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.