Skip to content

Commit 1ad21bf

Browse files
ninihen1claude
ninihen1
and
claude
committed
fix: correct set_store_flow_state response shape docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent d13c208 commit 1ad21bf

4 files changed

Lines changed: 152 additions & 20 deletions

File tree

‎plugins/flowstudio-power-automate/skills/flowstudio-power-automate-mcp/references/tool-reference.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,17 +353,69 @@ Response keys: `flowKey`, `triggerName`, `triggerUrl`, `requiresAadAuth`, `authT
353353

354354
> **Only works for `Request` (HTTP) triggers.** Returns an error for Recurrence
355355
> and other trigger types: `"only HTTP Request triggers can be invoked via this tool"`.
356+
> `Button`-kind triggers return `ListCallbackUrlOperationBlocked`.
356357
>
357358
> `responseStatus` + `responseBody` contain the flow's Response action output.
358359
> AAD-authenticated triggers are handled automatically.
360+
>
361+
> **Content-type note**: The body is sent as `application/octet-stream` (raw),
362+
> not `application/json`. Flows with a trigger schema that has `required` fields
363+
> will reject the request with `InvalidRequestContent` (400) because PA validates
364+
> `Content-Type` before parsing against the schema. Flows without a schema, or
365+
> flows designed to accept raw input (e.g. Baker-pattern flows that parse the body
366+
> internally), will work fine. The flow receives the JSON as base64-encoded
367+
> `$content` with `$content-type: application/octet-stream`.
359368
360369
---
361370

362371
## Flow State Management
363372

373+
### `set_live_flow_state`
374+
375+
Start or stop a Power Automate flow via the live PA API. Does **not** require
376+
a Power Clarity workspace — works for any flow the impersonated account can access.
377+
Reads the current state first and only issues the start/stop call if a change is
378+
actually needed.
379+
380+
Parameters: `environmentName`, `flowName`, `state` (`"Started"` | `"Stopped"`) — all required.
381+
382+
Response:
383+
```json
384+
{
385+
"flowName": "6321ab25-7eb0-42df-b977-e97d34bcb272",
386+
"environmentName": "Default-26e65220-...",
387+
"requestedState": "Started",
388+
"actualState": "Started"
389+
}
390+
```
391+
392+
> **Use this tool** — not `update_live_flow` — to start or stop a flow.
393+
> `update_live_flow` only changes displayName/definition; the PA API ignores
394+
> state passed through that endpoint.
395+
364396
### `set_store_flow_state`
365397

366-
Start or stop a flow. Pass `state: "Started"` or `state: "Stopped"`.
398+
Start or stop a flow via the live PA API **and** persist the updated state back
399+
to the Power Clarity cache. Same parameters as `set_live_flow_state` but requires
400+
a Power Clarity workspace.
401+
402+
Response (different shape from `set_live_flow_state`):
403+
```json
404+
{
405+
"flowKey": "<environmentId>.<flowId>",
406+
"requestedState": "Stopped",
407+
"currentState": "Stopped",
408+
"flow": { /* full gFlows record, same shape as get_store_flow */ }
409+
}
410+
```
411+
412+
> Prefer `set_live_flow_state` when you only need to toggle state — it's
413+
> simpler and has no subscription requirement.
414+
>
415+
> Use `set_store_flow_state` when you need the cache updated immediately
416+
> (without waiting for the next daily scan) AND want the full updated
417+
> governance record back in the same call — useful for workflows that
418+
> stop a flow and immediately tag or inspect it.
367419
368420
---
369421

@@ -424,6 +476,8 @@ Non-obvious behaviors discovered through real API usage. These are things
424476
- `error` key is **always present** in response --- `null` means success.
425477
Do NOT check `if "error" in result`; check `result.get("error") is not None`.
426478
- On create, `created` = new flow GUID (string). On update, `created` = `false`.
479+
- **Cannot change flow state.** Only updates displayName, definition, and
480+
connectionReferences. Use `set_live_flow_state` to start/stop a flow.
427481

428482
### `trigger_live_flow`
429483
- **Only works for HTTP Request triggers.** Returns error for Recurrence, connector,

‎plugins/flowstudio-power-automate/skills/flowstudio-power-automate-monitoring/SKILL.md‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: flowstudio-power-automate-monitoring
2+
name: power-automate-monitoring
33
description: >-
44
Monitor Power Automate flow health, track failure rates, and inventory tenant
55
assets using the FlowStudio MCP cached store. The live API only returns
@@ -208,17 +208,29 @@ Parameters: `startTime`, `endTime`, `status` (array: `["Failed"]`,
208208
209209
### `set_store_flow_state`
210210

211-
Calls the live PA API then syncs state to cache.
211+
Calls the live PA API then syncs state to the cache and returns the
212+
full updated record.
212213

213214
```json
214215
{
215-
"flowName": "0f368466-...",
216-
"environmentName": "Default-26e65220-...",
216+
"flowKey": "Default-<envGuid>.<flowGuid>",
217217
"requestedState": "Stopped",
218-
"actualState": "Stopped"
218+
"currentState": "Stopped",
219+
"flow": { /* full gFlows record, same shape as get_store_flow */ }
219220
}
220221
```
221222

223+
> The embedded `flow` object reflects the new state immediately — no
224+
> follow-up `get_store_flow` call needed. Useful for governance workflows
225+
> that stop a flow and then read its tags/monitor/owner metadata in the
226+
> same turn.
227+
>
228+
> Functionally equivalent to `set_live_flow_state` for changing state,
229+
> but `set_live_flow_state` only returns `{flowName, environmentName,
230+
> requestedState, actualState}` and doesn't sync the cache. Prefer
231+
> `set_live_flow_state` when you only need to toggle state and don't
232+
> care about cache freshness.
233+
222234
### `update_store_flow`
223235

224236
Updates governance metadata. Only provided fields are updated (merge).
@@ -381,7 +393,7 @@ Direct array.
381393

382394
## Related Skills
383395

384-
- `flowstudio-power-automate-mcp` — Core connection setup, live tool reference
385-
- `flowstudio-power-automate-debug` — Deep diagnosis with action-level inputs/outputs (live API)
386-
- `flowstudio-power-automate-build` — Build and deploy flow definitions
387-
- `flowstudio-power-automate-governance` — Governance metadata, tagging, notification rules, CoE patterns
396+
- `power-automate-mcp` — Core connection setup, live tool reference
397+
- `power-automate-debug` — Deep diagnosis with action-level inputs/outputs (live API)
398+
- `power-automate-build` — Build and deploy flow definitions
399+
- `power-automate-governance` — Governance metadata, tagging, notification rules, CoE patterns

‎skills/flowstudio-power-automate-mcp/references/tool-reference.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,17 +353,69 @@ Response keys: `flowKey`, `triggerName`, `triggerUrl`, `requiresAadAuth`, `authT
353353

354354
> **Only works for `Request` (HTTP) triggers.** Returns an error for Recurrence
355355
> and other trigger types: `"only HTTP Request triggers can be invoked via this tool"`.
356+
> `Button`-kind triggers return `ListCallbackUrlOperationBlocked`.
356357
>
357358
> `responseStatus` + `responseBody` contain the flow's Response action output.
358359
> AAD-authenticated triggers are handled automatically.
360+
>
361+
> **Content-type note**: The body is sent as `application/octet-stream` (raw),
362+
> not `application/json`. Flows with a trigger schema that has `required` fields
363+
> will reject the request with `InvalidRequestContent` (400) because PA validates
364+
> `Content-Type` before parsing against the schema. Flows without a schema, or
365+
> flows designed to accept raw input (e.g. Baker-pattern flows that parse the body
366+
> internally), will work fine. The flow receives the JSON as base64-encoded
367+
> `$content` with `$content-type: application/octet-stream`.
359368
360369
---
361370

362371
## Flow State Management
363372

373+
### `set_live_flow_state`
374+
375+
Start or stop a Power Automate flow via the live PA API. Does **not** require
376+
a Power Clarity workspace — works for any flow the impersonated account can access.
377+
Reads the current state first and only issues the start/stop call if a change is
378+
actually needed.
379+
380+
Parameters: `environmentName`, `flowName`, `state` (`"Started"` | `"Stopped"`) — all required.
381+
382+
Response:
383+
```json
384+
{
385+
"flowName": "6321ab25-7eb0-42df-b977-e97d34bcb272",
386+
"environmentName": "Default-26e65220-...",
387+
"requestedState": "Started",
388+
"actualState": "Started"
389+
}
390+
```
391+
392+
> **Use this tool** — not `update_live_flow` — to start or stop a flow.
393+
> `update_live_flow` only changes displayName/definition; the PA API ignores
394+
> state passed through that endpoint.
395+
364396
### `set_store_flow_state`
365397

366-
Start or stop a flow. Pass `state: "Started"` or `state: "Stopped"`.
398+
Start or stop a flow via the live PA API **and** persist the updated state back
399+
to the Power Clarity cache. Same parameters as `set_live_flow_state` but requires
400+
a Power Clarity workspace.
401+
402+
Response (different shape from `set_live_flow_state`):
403+
```json
404+
{
405+
"flowKey": "<environmentId>.<flowId>",
406+
"requestedState": "Stopped",
407+
"currentState": "Stopped",
408+
"flow": { /* full gFlows record, same shape as get_store_flow */ }
409+
}
410+
```
411+
412+
> Prefer `set_live_flow_state` when you only need to toggle state — it's
413+
> simpler and has no subscription requirement.
414+
>
415+
> Use `set_store_flow_state` when you need the cache updated immediately
416+
> (without waiting for the next daily scan) AND want the full updated
417+
> governance record back in the same call — useful for workflows that
418+
> stop a flow and immediately tag or inspect it.
367419
368420
---
369421

@@ -424,6 +476,8 @@ Non-obvious behaviors discovered through real API usage. These are things
424476
- `error` key is **always present** in response --- `null` means success.
425477
Do NOT check `if "error" in result`; check `result.get("error") is not None`.
426478
- On create, `created` = new flow GUID (string). On update, `created` = `false`.
479+
- **Cannot change flow state.** Only updates displayName, definition, and
480+
connectionReferences. Use `set_live_flow_state` to start/stop a flow.
427481

428482
### `trigger_live_flow`
429483
- **Only works for HTTP Request triggers.** Returns error for Recurrence, connector,

‎skills/flowstudio-power-automate-monitoring/SKILL.md‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: flowstudio-power-automate-monitoring
2+
name: power-automate-monitoring
33
description: >-
44
Monitor Power Automate flow health, track failure rates, and inventory tenant
55
assets using the FlowStudio MCP cached store. The live API only returns
@@ -208,17 +208,29 @@ Parameters: `startTime`, `endTime`, `status` (array: `["Failed"]`,
208208
209209
### `set_store_flow_state`
210210

211-
Calls the live PA API then syncs state to cache.
211+
Calls the live PA API then syncs state to the cache and returns the
212+
full updated record.
212213

213214
```json
214215
{
215-
"flowName": "0f368466-...",
216-
"environmentName": "Default-26e65220-...",
216+
"flowKey": "Default-<envGuid>.<flowGuid>",
217217
"requestedState": "Stopped",
218-
"actualState": "Stopped"
218+
"currentState": "Stopped",
219+
"flow": { /* full gFlows record, same shape as get_store_flow */ }
219220
}
220221
```
221222

223+
> The embedded `flow` object reflects the new state immediately — no
224+
> follow-up `get_store_flow` call needed. Useful for governance workflows
225+
> that stop a flow and then read its tags/monitor/owner metadata in the
226+
> same turn.
227+
>
228+
> Functionally equivalent to `set_live_flow_state` for changing state,
229+
> but `set_live_flow_state` only returns `{flowName, environmentName,
230+
> requestedState, actualState}` and doesn't sync the cache. Prefer
231+
> `set_live_flow_state` when you only need to toggle state and don't
232+
> care about cache freshness.
233+
222234
### `update_store_flow`
223235

224236
Updates governance metadata. Only provided fields are updated (merge).
@@ -381,7 +393,7 @@ Direct array.
381393

382394
## Related Skills
383395

384-
- `flowstudio-power-automate-mcp` — Core connection setup, live tool reference
385-
- `flowstudio-power-automate-debug` — Deep diagnosis with action-level inputs/outputs (live API)
386-
- `flowstudio-power-automate-build` — Build and deploy flow definitions
387-
- `flowstudio-power-automate-governance` — Governance metadata, tagging, notification rules, CoE patterns
396+
- `power-automate-mcp` — Core connection setup, live tool reference
397+
- `power-automate-debug` — Deep diagnosis with action-level inputs/outputs (live API)
398+
- `power-automate-build` — Build and deploy flow definitions
399+
- `power-automate-governance` — Governance metadata, tagging, notification rules, CoE patterns

0 commit comments

Comments
 (0)