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

fabric_lro

json.dumps()

ConvertTo-Json

⚠️ CRITICAL: Always use Python (not PowerShell) to build the ReflexEntities.json payload and the API request body.

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 so 202 responses can be polled via the

Location

header 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 .

MUST use Python to build

update-body.json

(see Python Patterns), then upload it using the COMMON-CLI updateDefinition pattern against

/v1/workspaces/{workspaceId}/reflexes/{reflexId}/updateDefinition

.

uniqueIdentifier

1.2.4

1.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

• 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 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.
• 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.

• 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

• 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

• 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)* → 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"

{
    "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"
}

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

  , set

  fabricJobConnectionDocumentId

  to the standalone

  fabricItemAction-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 later

  getDefinition

  readback, the standalone

  fabricItemAction-v1

  entity may surface

  payload.fabricItem.itemType: "FunctionSet"

  while the embedded

  FabricItemBinding

  still shows

  UserDataFunctions

  .
• For UDF / function-set actions, verify the target item actually exposes a non-empty function list and set

  subitemId

  to the discovered function name. Parameter names and

  parameterType

  values 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.

AttributeTrigger

EventTrigger

EventTrigger does NOT have ScalarSelectStep/ScalarDetectStep. Use when acting on events directly. Supports state, change, and heartbeat detection via EventDetectStep.

• 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.json

  payload when calling

  updateDefinition

• Always JSON.stringify the

  definition.instance

  field in

  timeSeriesView-v1

  entities — 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 —

  AttributeTrigger

  for value-based conditions (has ScalarSelectStep + ScalarDetectStep),

  EventTrigger

  for event-based firing (has FieldsDefaultsStep + EventDetectStep, no ScalarDetectStep)
• Always use new GUIDs for

  uniqueIdentifier

  when adding entities — duplicate GUIDs cause corruption
• Always update all cross-references when changing a

  uniqueIdentifier

  — other entities reference it via

  targetUniqueIdentifier

• Handle LRO responses —

  create

  ,

  getDefinition

  , and

  updateDefinition

  may return 202; poll the

  Location

  header

• 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

  , or

  IsOutsideRange

  only 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

• Hardcoded workspace or item IDs — always resolve dynamically
• Forgetting the

  .platform

  part — only include it with

  updateDefinition

  when using

  ?updateMetadata=true

• SELECT * without filtering on list endpoints — use pagination for large workspaces
• Modifying definitions of items with encrypted sensitivity labels —

  getDefinition

  is 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

• 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 rest

  with the Fabric API audience
• For reading Activator items and rules without modifying them, use the activator-consumption-cli skill instead