create-flow

Plugin check: Run node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Create Power Automate Cloud Flow

Author a Power Automate cloud flow as a JSON definition file. The flow is designed for deployment via the Power Automate Flow API or solution import through PAC CLI.

Core Principles

• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
• JSON-first authoring: Flows are authored as JSON files following the Azure Logic Apps workflow schema. Never use the Power Automate portal — everything is code.
• Validate before deploy: Always validate the flow JSON using the validation script before offering deployment.
• Dataverse connector by default: When the flow interacts with Dataverse tables, use the shared_commondataserviceforapps connector with @parameters('$authentication').
• Never hardcode GUIDs: Record IDs, environment IDs, and connection references should use expressions or be parameterized, never hardcoded.

Reference: See ${CLAUDE_PLUGIN_ROOT}/references/flow-json-structure.md for the complete flow JSON schema, trigger types, action patterns, and expression syntax.

Reference: See ${CLAUDE_PLUGIN_ROOT}/references/dataverse-settings.md for common Dataverse table schemas, timezone codes, locale IDs, and user settings.

Reference: See ${CLAUDE_PLUGIN_ROOT}/references/dataverse-mcp-integration.md for how to use the Dataverse MCP server (list_tables, describe_table) for live schema discovery during flow authoring.

Initial request: $ARGUMENTS

---

Workflow

1. Phase 1: Verify Prerequisites → Check PAC CLI and authentication
2. Phase 2: Gather Requirements → Understand what the flow should do and check connector connections
3. Phase 3: Research Dataverse Schema → Query tables/columns the flow will use
4. Phase 4: Design the Flow → Present the flow design for user approval
5. Phase 5: Author the Flow JSON → Write the flow definition file
6. Phase 6: Validate the Flow → Run validation and fix any issues
7. Phase 7: Review & Deploy → Present summary and offer deployment

---

Phase 1: Verify Prerequisites

Goal: Ensure PAC CLI is installed, authenticated, connected to the correct environment, and Dataverse MCP is available for schema discovery

Actions:

1. Create todo list with all 7 phases (see Progress Tracking table).

2. Run pac help to check PAC CLI availability:

   pac help
   

3. If PAC CLI is not installed: Tell the user to install it:

   dotnet tool install --global Microsoft.PowerApps.CLI.Tool
   

4. Run pac org who to check authentication:

   pac org who
   

5. Extract and present: Environment Name, Org URL, Environment ID, User Email.

6. If not authenticated: Guide through pac auth create --environment "<URL>".

7. Confirm environment with the user via AskUserQuestion:

   Question	Options
   You are connected to <ENV_NAME> (<ENV_URL>). Is this the correct environment for this flow?	Yes, use this environment; No, let me choose a different one

8. If "No": Run pac org list, let user select, then pac org select --environment "<URL>".

9. Check for Dataverse MCP availability: Determine if the Dataverse MCP server is configured by checking whether the list_tables and describe_table tools are available in the current session.

   • If MCP tools are available: Note this — Phase 3 will use them for live schema discovery. This is the preferred path.

   • If MCP tools are NOT available: Ask the user if they want to set it up:

     Question	Options
     The Dataverse MCP server is not configured. It provides live schema discovery (tables, columns, relationships) which makes flow authoring much more accurate. Would you like to set it up?	Yes, run /dv-connect to configure MCP (Recommended); No, continue without MCP (will use Web API fallback)

     • If "Yes": Tell the user to run /dv-connect. After it completes and the session restarts, resume from Phase 2.
     • If "No": Continue — Phase 3 will fall back to the Web API for metadata queries.

Output: PAC CLI authenticated, environment confirmed, Dataverse MCP availability determined

---

Phase 2: Gather Requirements

Goal: Understand exactly what the flow should do — trigger, actions, tables, and business logic

Actions:

1. If the user already provided a description (via $ARGUMENTS), analyse it and identify:

   • Trigger type: Scheduled (recurrence), manual (button), or event-driven (Dataverse trigger)
   • Tables involved: Which Dataverse tables the flow reads/writes
   • Business logic: Conditions, loops, data transformations
   • Output: What the flow produces or changes

2. If requirements are unclear, ask targeted questions via AskUserQuestion:

   Question	Options
   What should trigger this flow?	Scheduled (runs on a timer), When a Dataverse record is created/modified, Manual (button press), Other (describe)

3. If the user mentions Dataverse tables but is vague about which ones (e.g., "user data", "customer info", "orders"), and Dataverse MCP is available, use list_tables to discover what tables exist in the environment and help the user identify the right ones:

   • Call list_tables (MCP tool) to get the list of tables in the environment
   • Filter/search the results for tables that match what the user described
   • Present the matching tables with their display names and logical names
   • Let the user confirm which tables the flow should use

   If MCP is NOT available, ask the user to provide exact table logical names:

   Question	Options
   Which Dataverse tables does this flow need to interact with? Please provide the logical names (e.g., account, contact, systemuser).	(free text)

4. Confirm the full requirements with the user before proceeding:

   "Here's what I understand the flow should do:"

   • Trigger: [description]
   • Tables: [list with logical names]
   • Logic: [description]
   • Output: [description]

   "Does this look correct?"

5. Once requirements are confirmed, identify all connectors the flow will need. Present them to the user:

   Connectors Required

   This flow will use the following connectors:

   Connector	API ID
   Dataverse	shared_commondataserviceforapps
   Office 365 Outlook	shared_office365
   ...	...

6. Check existing connections by running pac connection list and matching the API IDs from the table above against the API Id column in the output.

   • For each required connector, check if a connection with a matching API ID exists and has status Connected.
   • Present the results:

   Connection Status

   Connector	Status
   Dataverse	Connected (existing connection found)
   Office 365 Outlook	No connection found
   ...	...

7. If all connections exist: Inform the user and proceed to Phase 3.

8. If any connections are missing: Ask the user via AskUserQuestion:

   Question	Options
   The following connectors don't have connections set up yet: [list missing]. Connections for these connectors require interactive sign-in via the browser. Would you like to create them now before we continue?	Yes, I'll create them in Power Automate (open portal); No, continue — I'll set them up after deployment

   • If "Yes": Provide the direct URL to the Power Automate connections page:

     Go to Power Automate → Connections → New connection and create connections for each missing connector. Let me know when you're done and I'll re-check.

     After the user confirms, re-run pac connection list to verify the connections are now available, then proceed to Phase 3.

   • If "No": Note the missing connections and continue. Remind the user again in Phase 7 that they will need to set up connections after deployment.

Output: Complete, confirmed flow requirements with exact Dataverse table logical names and connection status verified

---

Phase 3: Research Dataverse Schema

Goal: Query the live Dataverse environment to get exact table and column metadata for every table the flow will use. This ensures the flow JSON uses correct logical names, plural entity names, column types, and relationship navigation properties.

Strategy: MCP First, Web API Fallback

Use the Dataverse MCP server as the primary discovery tool when available. It provides list_tables and describe_table which return rich, structured metadata directly from the environment. Fall back to the Dataverse Web API (EntityDefinitions) only if MCP is not configured.

Path A: Dataverse MCP Available (Preferred)

Actions:

1. Discover tables — If you need to explore what tables exist or confirm table names, call:

   list_tables
   

   This returns all tables in the environment with their logical names, display names, and plural names. Use keyword search to narrow down results if the environment has many tables.

2. Get detailed schema — For each table the flow will interact with, call:

   describe_table(table_logical_name="<table>")
   

   This returns:

   • Columns: Logical name, display name, data type, required level, max length
   • Relationships: Related tables, navigation property names, relationship type (1:N, N:1, N:N)
   • Primary key: The primary ID column name
   • Plural name: The EntitySetName — this is what goes in the entityName parameter of Dataverse flow actions

3. For each table, extract and record:

   Property	Where to find it	Used in flow JSON
   Plural entity name (EntitySetName)	describe_table response	"entityName" parameter in all Dataverse actions
   Column logical names	Columns list	"$select", "$filter", "item/<column>" parameters
   Column data types	Columns list	Determines expression syntax (string vs integer vs datetime)
   Lookup navigation properties	Relationships list	"$expand", @odata.bind references
   Primary key column	Primary key field	"recordId" parameter for Get/Update/Delete actions

4. For lookup columns, use the relationship metadata from describe_table to determine:

   • The navigation property name (case-sensitive — must match exactly)
   • The related entity's plural name (for @odata.bind expressions)

5. Present the schema summary to confirm you have the right columns before designing the flow:

   Schema for <table> (<plural_name>):

   Column	Type	Description
   name	String	Account name
   createdon	DateTime	Record creation date
   statecode	Integer	Record status (0=Active)
   ...	...	...

   Key relationships:

   • <navigation_property> → <related_table> (N:1)

Path B: Web API Fallback (No MCP)

If the Dataverse MCP server is not configured, query metadata via the Web API:

1. Get table metadata and plural name:

   curl -s -H "Authorization: Bearer $(az account get-access-token --resource <ENV_URL> --query accessToken -o tsv)" \
     "<ENV_URL>/api/data/v9.2/EntityDefinitions(LogicalName='<table>')?$select=LogicalName,EntitySetName,DisplayName,PrimaryIdAttribute,PrimaryNameAttribute"
   

   The EntitySetName value is the plural name for entityName in flow actions.

2. Get columns:

   curl -s -H "Authorization: Bearer $(az account get-access-token --resource <ENV_URL> --query accessToken -o tsv)" \
     "<ENV_URL>/api/data/v9.2/EntityDefinitions(LogicalName='<table>')/Attributes?\$select=LogicalName,AttributeType,DisplayName,RequiredLevel"
   

3. Get relationships (for lookups):

   curl -s -H "Authorization: Bearer $(az account get-access-token --resource <ENV_URL> --query accessToken -o tsv)" \
     "<ENV_URL>/api/data/v9.2/EntityDefinitions(LogicalName='<table>')/ManyToOneRelationships?\$select=ReferencingAttribute,ReferencedEntity,ReferencingEntityNavigationPropertyName"
   

4. Extract the same information as Path A and present the schema summary.

Common Gotchas

• Plural names are not always obvious: systemuser → systemusers, but usersettings → usersettingscollection. Always verify with describe_table or EntityDefinitions.
• Navigation property names are case-sensitive: new_AccountId is NOT the same as new_accountid. Always use the exact casing from the metadata.
• Some system tables have restricted columns: Not all columns on systemuser or usersettings are writable. Check the RequiredLevel and IsValidForUpdate attributes if unsure.

Output: Complete, verified metadata for all tables and columns the flow will reference — including plural entity names, column logical names, data types, and relationship navigation properties

---

Phase 4: Design the Flow

Goal: Present the flow architecture for user review before writing JSON

Actions:

1. Design the complete flow, listing every step:

   Flow Design: [Flow Name]

   Trigger: [Type] — [Details]

   Step	Action	Type	Details
   1	List_New_Records	ListRecords	Query <table> where <filter>
   2	Apply_to_each	Foreach	Loop over results from step 1
   2.1	Get_Related_Record	GetItem	Get related record for each item
   2.2	Condition_Check	If	Check if <condition>
   2.2a	Update_Record	UpdateRecord	Update <table> with <values>

   Connection References: Dataverse (shared_commondataserviceforapps)

2. Present to user via AskUserQuestion:

   Question	Options
   Does this flow design look correct?	Yes, proceed to write the JSON; No, I have changes (describe)

3. If the user requests changes, update the design and re-present.

Output: Approved flow design

---

Phase 5: Author the Flow JSON

Goal: Write the complete flow definition as a JSON file

Actions:

1. Determine the output file path. Default: flows/<flow-name>.json in the project root. Create the flows/ directory if it doesn't exist.

2. Author the flow JSON following the approved design. Follow these rules:

   • Use the schema from ${CLAUDE_PLUGIN_ROOT}/references/flow-json-structure.md
   • Every Dataverse action MUST include "authentication": "@parameters('$authentication')"
   • Use descriptive action names with underscores (e.g., List_New_Users, Update_Settings)
   • Set "state": "Started" to activate the flow on deployment
   • DO NOT include a description field at the properties level (Flow API rejects it)
   • Use the plural entity name for entityName parameters
   • Use proper runAfter dependencies to define execution order

3. Write the file using the Write tool.

Output: Flow JSON file written to disk

---

Phase 6: Validate the Flow

Goal: Validate the flow JSON is structurally correct before deployment

Actions:

1. Run the validation script:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-flow.js" --file "<path-to-flow.json>"
   

2. Review the output:

   • If valid: true: Proceed to Phase 7
   • If valid: false: Fix each error in the JSON file and re-validate

3. Present validation results to the user:

   "Flow validation passed:"

   • Display Name: [name]
   • Triggers: [count]
   • Actions: [count]
   • Connection References: [count]

Output: Validated flow JSON

---

Phase 7: Review & Deploy

Goal: Present a final summary and offer deployment

Actions:

1. Present the flow summary:

   Flow Summary

   Property	Value
   Name	[displayName]
   File	[file path]
   Trigger	[type and schedule]
   Actions	[count]
   Tables	[list of Dataverse tables used]
   Connector	Dataverse (shared_commondataserviceforapps)

2. Ask the user if they want to deploy:

   Question	Options
   The flow JSON is ready. Would you like to deploy it now?	Yes, deploy to [ENV_NAME] (Recommended); No, I'll deploy later with /deploy-flow

3. If "Yes, deploy": Tell the user to invoke the deploy skill:

   "Please run /deploy-flow to deploy the flow to your environment."

   Or deploy directly using the deployment script:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/deploy-flow.js" --file "<path>" --environment-id "<env-id>"
   

   Parse the JSON output:

   • If success: true: Report the flow ID and state
   • If success: false: Show the error and help troubleshoot

4. If "No, deploy later": Remind them:

   "The flow is saved at <path>. Run /deploy-flow when you're ready to deploy it."

5. Offer next steps:

   • /deploy-flow — Deploy the flow to an environment
   • /list-flows — List existing flows in the environment
   • Create another flow for a related process

Output: Flow reviewed and optionally deployed

---

Important Notes

Key Decision Points (Wait for User)

1. After Phase 1: Confirm environment
2. After Phase 2: Confirm requirements
3. After Phase 4: Approve flow design
4. After Phase 7: Deploy or skip

Action Naming Convention

Use descriptive names with underscores that reflect what the action does:

• List_New_Users (not ListRecords_1)
• Update_User_Settings_to_BST (not UpdateRecord)
• Condition_-_Check_if_not_already_set (not Condition_1)

Common Patterns

Filter for records created in the last N days:

"$filter": "createdon ge @{formatDateTime(addDays(utcNow(), -1), 'yyyy-MM-ddTHH:mm:ssZ')}"

Exclude system/service accounts from systemusers:

"$filter": "accessmode ne 4 and isdisabled eq false and not startswith(fullname, '#')"

Update usersettings by systemuserid: Use usersettingscollection as the entity name and the user's systemuserid as the recordId.

Progress Tracking

Before starting Phase 1, create a task list with all phases using TaskCreate:

Task subject	activeForm	Description
Verify prerequisites	Verifying prerequisites	Check PAC CLI installation and authentication status
Gather requirements	Gathering requirements	Understand flow trigger, actions, tables, business logic, and verify connector connections
Research Dataverse schema	Researching Dataverse schema	Query table and column metadata for the flow
Design the flow	Designing the flow	Present flow architecture for user approval
Author the flow JSON	Authoring flow JSON	Write the complete flow definition file
Validate the flow	Validating the flow	Run validation script and fix any issues
Review and deploy	Reviewing and deploying	Present summary and offer deployment

Mark each task in_progress when starting it and completed when done via TaskUpdate.

---

Begin with Phase 1: Verify Prerequisites