cloud-flows
Skill8 starsChanged 41 days agoMITView on GitHub
Work with Power Automate solution-aware Cloud Flows on Dataverse — inspect, save draft, publish, restore versions, trigger runs, debug action outputs, and patch FetchXML / action inputs surgically. Includes a compact iteration workflow for safe edit-test-publish cycles, and FetchXML guidance (rollup trade-offs, comment pitfalls, aggregate limits) for classification flows. Use when the user asks about Power Automate cloud flows in a Dataverse environment.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- business-process-flowsSkill
- classic-workflowsSkill
- command-bar-buttonsSkill
- form-authoringSkill
- modeling-patternsSkill
- solution-pipelinesSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 76
When a flow drives lifecycle decisions via FetchXML against accounts / contacts etc., a handful of dataverse-specific traps recur.
- Very specific: line 125
Use operationId: CreateRecordWithOrganization (not CreateRecord) and pass organization: "current" in parameters.
- Very specific: line 184
Prefer this over GET .../runs/{runId}?$expand=properties/actions, which intermittently returns ASP.NET runtime-error HTML.
- Very specific: line 192
RestoreComponentVersionis async: After calling it, give Dataverse 1–2 seconds before re-listing versions to assert the Op=3 row exists.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cloud Flows on Dataverse
Expert reference for managing solution-aware Power Automate cloud flows via the dataverse-modelling-mcp server.
Hard prerequisites
- Only solution-aware flows have version history. Flows in the default solution get no
componentversionrows. If a flow is missing from version-history queries, check that it belongs to a non-default solution (solutioncomponentsfiltered onobjectid eq <flowid>). - Environment write policy:
contoso-devis the safe write target.contoso-prod(production) andcontoso-stagingneed explicit user confirmation before any mutating call. - The
componentversionvirtual entity refuses direct Create. The Microsoft Learn doc lists Create as supported, but every POST/PATCH against/componentversionsor the elastic backing table/componentversionnrddatasourcesetfails. The bound actions documented below are the only working write path.
Tool map
| User intent | MCP tool | Underlying call |
| List flows | flow_list | Power Automate Flow API |
| Inspect single flow | flow_get, flow_describe | Power Automate Flow API |
Get raw clientdata (with connectionReferences wrapper) | flow_get_clientdata | Dataverse GET /workflows({id})?$select=clientdata |
| Create solution-aware flow (version history + draft/publish) | flow_create(…, solutionUniqueName=…) | Dataverse POST /workflows (category=5, type=1) |
| Create personal flow (no versioning) | flow_create(…) without solutionUniqueName | Power Automate Flow API |
| List version history | flow_list_versions | Dataverse GET /workflows({id})/componentversions |
| Inspect single version | flow_get_version | Filtered list (direct GET-by-key is blocked) |
| Save a draft (Op=1 Update version) | flow_save_draft | PATCH /workflows({id}) + header mscrm.AsUnpublished: true |
| Publish current draft (Op=2 Publish version) | flow_publish | POST /PublishComponent?ActivateFlowOnPublish=<bool> |
| Save draft + publish in one call | flow_save_draft_and_publish | combined PATCH + PublishComponent |
| Surgical update of one action input | flow_patch_action_input | GET clientdata → mutate one key under actions.<X>.inputs.parameters → save draft (optional publish) |
| Validate a FetchXML against Dataverse | fetchxml_validate | GET /{entitySet}?fetchXml=<xml> read-only |
| Activate/deactivate at runtime (no snapshot) | flow_set_state | Power Automate /start or /stop |
| Restore a prior published version (Op=3 Restore) | flow_restore_version | POST /workflows({id})/Microsoft.Dynamics.CRM.RestoreComponentVersion |
| Get run history | flow_get_runs | Power Automate Flow API |
| Trigger a flow run | flow_trigger_run | POST .../triggers/{triggerName}/run |
| Wait until a run reaches a terminal state | flow_wait_for_run | Polls GET .../runs/{runId} until status != Running |
| List actions of a single run (status + outputsLink) | flow_get_run_actions | GET .../runs/{runId}/actions |
| Fetch the raw outputs of one action | flow_get_action_outputs | resolves SAS-signed outputsLink — no Bearer header |
Conceptual model
The workflow row carries the live flow. Alongside it, the virtual componentversion view exposes snapshots. Each snapshot has an Operation discriminator:
| Operation | Label | Triggered by |
| 0 | Create | Initial flow creation |
| 1 | Update | flow_save_draft (PATCH with mscrm.AsUnpublished: true) |
| 2 | Publish | flow_publish (POST PublishComponent) |
| 3 | Restore | flow_restore_version |
| 4 | Solution Import | Solution-import pipeline |
Restore semantics: RestoreComponentVersion only acts on Publish-typed (Op=2) versions. Calls against Create/Update IDs return HTTP 204 but produce no observable change.
Publish vs. Activate: independent. flow_publish snapshots the draft as the new published version but leaves the runtime state unchanged. ActivateFlowOnPublish=true combines both. flow_set_state toggles runtime alone without touching version history.
Solution-flow patch & test workflow
The full iteration cycle for a safe edit on contoso-dev, with MCP tools alone (no PowerShell escape hatches required for the common path):
- Inspect —
flow_getto confirm the action name and current shape. For fullclientdata(incl.connectionReferences),flow_get_clientdata.flow_list_versions(flowId)to note the last good Op=2 version-id as rollback anchor. - Edit — choose the smallest path that fits:
- One parameter on one action (most edits):
flow_patch_action_input(flowId, actionName, parameterName, valueJson, publish=false). Avoids round-tripping the full clientdata. - Multi-action / structural change:
flow_get_clientdata→ mutate locally →flow_save_draft(orflow_save_draft_and_publish).
- One parameter on one action (most edits):
- Pre-flight FetchXML changes —
fetchxml_validate(entitySet, fetchXml, sampleSize)against the active org before patching it into a List action. Catches well-formedness errors (e.g.--in comments) and reports the row count to be classified. - Publish —
flow_publish(flowId, activateFlow=false)(or passpublish=truedirectly toflow_patch_action_input). Confirm viaflow_list_versionsthat a new Op=2 row landed andconnectionReferencesis still populated. - Trigger —
flow_trigger_run(flowId, triggerName). For Recurrence-triggered flows,triggerName="Recurrence"is the canonical name. - Wait —
flow_wait_for_run(flowId, runId, timeoutSeconds=300). Blocks server-side until terminal state. - Validate the run —
flow_get_run_actions(flowId, runId)lists every action's status; for anyFailedrow, follow itsOutputsLinkviaflow_get_action_outputs(flowId, runId, actionName)to get the error body (Dataverse error code, BadRequest message, etc.). For Compose-style telemetry actions, fetch the same way and inspect the produced JSON / HTML. - Rollback if needed —
flow_restore_version(flowId, <lastGoodOp2Id>)thenflow_publish. Restore produces an Op=3 row pointing at the source for audit.
Single-action edits commonly compress to two tool calls: fetchxml_validate (read-only) followed by flow_patch_action_input(..., publish=true).
FetchXML inside classification / lifecycle flows
When a flow drives lifecycle decisions via FetchXML against accounts / contacts etc., a handful of dataverse-specific traps recur. Each carries a trade-off — none of these is a hard ban, but the consequences should be conscious.
Rollup-field reliance — convenient but lagged
Dataverse rollup fields like sample_open_opportunities or sample_number_orders are asynchronously recomputed. Real lag observed: minutes to hours, sometimes longer for cold accounts. They can be stale in either direction:
- A new opportunity exists but
sample_open_opportunitiesstill shows0. - A record's rollup was never computed → the field is
null, not0.condition operator='eq' value='0'then matches nothing.
Trade-off: rollups are cheap (single attribute, no join), and for thresholds like eq 1 or ge 2 they are essentially the only practical option (see below). For existence checks they can quietly mis-classify records.
When to prefer an outer-join existence check (<link-entity ... link-type='outer' alias='X'> + condition entityname='X' attribute='<id>' operator='null'/'not-null'):
- The check is the only thing gating a destructive / overwriting classification (e.g. „has zero open opps" used to mark
Verlorener Potentialkunde). - The records are recent / volatile (frequently changing leads, opps, orders).
- A wrong classification has measurable downstream cost.
When the rollup is fine:
- Threshold semantics that an existence-check cannot express (
exactly 1,>= 2). - A higher-priority phase in the same flow will overwrite an incorrect classification anyway (e.g.
AafterNcovers stalesample_number_orders eq 1for accounts that actually have 2+ orders).
Aggregate FetchXML — no cross-entity HAVING
FetchXML supports aggregate='true' with groupby and aggregate='countcolumn' on a linked entity. Documentation suggests aggregate aliases can be used as filters. In practice, an aggregate-alias condition on a cross-entity outer-join is rejected by Dataverse:
<!-- This is "Attribute not found in XNode" or value-coerced-to-GUID error -->
<filter><condition alias='ordercount' operator='ge' value='2' /></filter>What works:
- Boolean existence on the outer-join:
<condition entityname='oa' attribute='salesorderid' operator='not-null' />(≥1) or'null'(=0). - Numeric threshold via the rollup field on the parent entity itself (
<condition attribute='sample_number_orders' operator='ge' value='2' />) — same trade-off as above. - Aggregate-alias HAVING on the same entity (no joins) — that case works as documented.
For „exactly N" or „at least N≥2" cross-entity, you either accept the rollup-field dependency or accept a structural workaround (e.g. two outer-joins with disjoint filters to prove ≥2 distinct rows, at the cost of edge cases that match neither).
XML-comment pitfall: -- is invalid
Per W3C, an XML comment may not contain --. Dataverse parses FetchXML strictly:
<!-- Verlorener Potentialkunde (772600007) -- NEU --> <!-- ❌ rejected: "Invalid XML." -->Easy to overlook in dash-separated section headers. fetchxml_validate catches this pre-flight.
Sending emails from a flow (Dataverse connector)
The Dataverse connector supports inline activity parties on email creation — via a specific op/parameter combination:
- Use
operationId: CreateRecordWithOrganization(notCreateRecord) and passorganization: "current"in parameters. - The parameter is named
item/activitypointer_activity_parties(notitem/email_activity_parties). The latter triggersInvalidOpenApiFlow / WorkflowOperationParametersExtraParameter. - Inline array shape:
"item/activitypointer_activity_parties": [ { "participationtypemask": 1, "partyid@odata.bind": "/systemusers(<sender-guid>)" }, { "participationtypemask": 2, "partyid@odata.bind": "/systemusers(<recipient-guid>)" }, { "participationtypemask": 2, "addressused": "team@example.com" } ]addressusedworks for distribution lists / shared mailboxes without resolving a systemuser. - Send via
PerformBoundAction,actionName: Microsoft.Dynamics.CRM.SendEmail,item/IssueSend: true(false = mark sent in CRM without SMTP delivery). - Reference flow (example): a scheduled nightly cloud flow, workflowid
50000000-0000-0000-0000-000000000006.
Reverse-engineered endpoints (Maker UI parity)
These came from Playwright network traces of make.powerautomate.com and are now wrapped by the MCP tools. Documented here for the rare case the wrapper needs extending — most work belongs in the service layer, not in tool callers.
Restore (bound action on workflow)
POST /api/data/v9.2/workflows({flowId})/Microsoft.Dynamics.CRM.RestoreComponentVersion
Content-Type: application/json
{"RestoringVersionId": "componentversions(<componentversionId>)"}- Parameter name is PascalCase. A C# anonymous object
new { RestoringVersionId = ... }gets serialized asrestoringVersionIdby the sharedJsonSerializerOptions(CamelCase policy) and rejected. Use aDictionary<string, object?>. - Returns 204 even when the snapshot wasn't actually applied — verify via re-list.
Publish (unbound action)
POST /api/data/v9.2/PublishComponent?ActivateFlowOnPublish=false
Content-Type: application/json
{"Target": "/workflows({flowId})"}Save draft (direct PATCH with special header)
PATCH /api/data/v9.2/workflows({flowId})
Content-Type: application/json
mscrm.AsUnpublished: true
If-Match: *
{"clientdata": "<stringified-logic-apps-json>", "name": "..."}- Without
mscrm.AsUnpublished, the PATCH may try to validate/publish immediately and fail. - A second header
mscrm.SkipComponentVersioning: trueis what the Maker UI uses in the publish-batch's first PATCH to avoid double-versioning; do not add it to plain Save-draft calls — it would suppress the Update version row entirely.
Manual run (PA Flow API)
POST https://{region}.api.flow.microsoft.com/providers/Microsoft.ProcessSimple/environments/{envId}/flows/{flowId}/triggers/{triggerName}/run?api-version=2016-11-01- Returns 200 with no usable body. Read the new RunId by listing runs (
/runs?$top=1) right after.
Action outputs (per-action endpoint — stable)
GET .../flows/{flowId}/runs/{runId}/actions/{actionName}?api-version=2016-11-01- Returns
properties.outputsLink.uri— a SAS-signed URL. Download it without a Bearer header; otherwiseDirectApiRequestHasMoreThanOneAuthorization. - Prefer this over
GET .../runs/{runId}?$expand=properties/actions, which intermittently returns ASP.NET runtime-error HTML.
General pitfalls
clientdatais a stringified JSON, not nested JSON. When constructing it manually, the innerproperties.definitionblock must use Logic Apps keys$schema,$connections,$authentication— verbatim with dollar signs. Don't try to coerce them viastring.Replace; build the JSON literal directly (raw string interpolation in C# works well).- Manual trigger schema: the Request trigger's
inputs.schemamust be a JSON-schema object ({"type":"object","properties":{},"required":[]}), not an empty{}. - Direct OData PATCH on
clientdatabypasses versioning. It modifies the live flow without creating acomponentversionrow. To get a proper Update snapshot, go throughflow_save_draft(or any wrapper that includes themscrm.AsUnpublished: trueheader). - Composite key lookups are blocked:
GET /componentversions({id})andGET /workflows({wfid})/componentversions({verId})both fail with "Get with NavigationKey is allowed only on Metadata Entities." Resolve a single version by listing and filtering client-side. RestoreComponentVersionis async. After calling it, give Dataverse 1–2 seconds before re-listing versions to assert the Op=3 row exists.- External PA-MCP
update_flowcorrupts solution-aware flows. It transformsconnectionReferencesinto the flat Flow-API shape and losesconnectionReferenceLogicalName, leaving everyOpenApiConnectionaction broken. Always use the dataverse-modelling-mcp save-draft path for solution-aware flows.
Typical workflows
"Roll a flow back to yesterday's published version"
flow_list_versions(flowId)→ identify the target row whereOperation == 2andCreatedOnmatches.flow_restore_version(flowId, versionId)— produces a new Op=3 row and a fresh Draft on the workflow.- (Optional)
flow_publish(flowId, activateFlow=true)to re-publish-and-activate immediately.
"Replace the FetchXML of one List action"
fetchxml_validate(entitySet="accounts", fetchXml=<new>, sampleSize=3)— well-formed? row count plausible?flow_patch_action_input(flowId, actionName="List_Lost_Customers", parameterName="fetchXml", valueJson="\"<the new xml>\"", publish=true)— saves draft and publishes in one go.flow_trigger_run(flowId, "Recurrence")→flow_wait_for_run(flowId, runId)→flow_get_run_actions(flowId, runId).
"Apply a small edit safely without breaking the active flow"
flow_get(flowId)to confirm structure (orflow_get_clientdatafor the full wrapper).flow_patch_action_input(...)(no publish) — creates Op=1 Update version, runtime unaffected.- Inspect & test via run, then
flow_publish(flowId)when ready.
"Disable a noisy flow temporarily"
flow_set_state(flowId, enable=false)— stops runs without changing version history. Re-enable later withenable=true.
"Audit who changed what"
flow_list_versions(flowId)returns each row withCreatedByName,Operation,CreatedOn.
Related memories
- See [[feedback_environment_write_policy]] for the contoso-dev vs contoso-prod/contoso-staging write rules.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

