12 KiB
Control Flow Patterns
How to implement loops, conditionals, and menus in Shortcuts.
Overview
Control flow actions use two key parameters:
- GroupingIdentifier: A UUID that links related actions (start, middle, end)
- WFControlFlowMode: An integer indicating the action's role
0= Start (begin block)1= Middle (else, case)2= End (close block)
Important: WFControlFlowMode must be an <integer>, not a <string>.
Repeat Count
Repeat a block of actions a specific number of times.
Structure
| Mode | Action | Description |
|---|---|---|
| 0 | Start | Begin repeat, set count |
| 2 | End | Close repeat block |
Template
<!-- Repeat Start -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.count</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>REPEAT-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<key>WFRepeatCount</key>
<integer>5</integer>
</dict>
</dict>
<!-- Actions inside the loop go here -->
<!-- Repeat End -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.count</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>UUID</key>
<string>END-ACTION-UUID</string>
<key>GroupingIdentifier</key>
<string>REPEAT-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
Accessing Repeat Index
Inside the loop, reference the current index using the End action's UUID:
<key>attachmentsByRange</key>
<dict>
<key>{0, 1}</key>
<dict>
<key>OutputUUID</key>
<string>END-ACTION-UUID</string>
<key>OutputName</key>
<string>Repeat Index</string>
<key>Type</key>
<string>ActionOutput</string>
</dict>
</dict>
Repeat with Each (For Each)
Iterate over each item in a list.
Structure
| Mode | Action | Description |
|---|---|---|
| 0 | Start | Begin loop, specify input list |
| 2 | End | Close loop |
Template
<!-- Repeat Each Start -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.each</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>FOREACH-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<key>WFInput</key>
<dict>
<key>Value</key>
<dict>
<key>OutputUUID</key>
<string>LIST-SOURCE-UUID</string>
<key>OutputName</key>
<string>List</string>
<key>Type</key>
<string>ActionOutput</string>
</dict>
<key>WFSerializationType</key>
<string>WFTextTokenAttachment</string>
</dict>
</dict>
</dict>
<!-- Actions inside the loop go here -->
<!-- Repeat Each End -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.each</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>UUID</key>
<string>END-ACTION-UUID</string>
<key>GroupingIdentifier</key>
<string>FOREACH-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
Accessing Current Item
Reference the current item using the Start action's UUID with OutputName "Repeat Item":
<key>attachmentsByRange</key>
<dict>
<key>{0, 1}</key>
<dict>
<key>OutputUUID</key>
<string>START-ACTION-UUID</string>
<key>OutputName</key>
<string>Repeat Item</string>
<key>Type</key>
<string>ActionOutput</string>
</dict>
</dict>
Conditional (If/Otherwise)
Execute different actions based on a condition.
Structure
| Mode | Action | Description |
|---|---|---|
| 0 | If | Start conditional, define condition |
| 1 | Otherwise | Else branch |
| 2 | End If | Close conditional |
Template
<!-- If -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>IF-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<key>WFCondition</key>
<string>Equals</string>
<key>WFInput</key>
<dict>
<key>Value</key>
<dict>
<key>OutputUUID</key>
<string>VALUE-TO-TEST-UUID</string>
<key>OutputName</key>
<string>Text</string>
<key>Type</key>
<string>ActionOutput</string>
</dict>
<key>WFSerializationType</key>
<string>WFTextTokenAttachment</string>
</dict>
<key>WFConditionalActionString</key>
<string>expected value</string>
</dict>
</dict>
<!-- Actions for "If" branch go here -->
<!-- Otherwise -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>IF-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>1</integer>
</dict>
</dict>
<!-- Actions for "Otherwise" branch go here -->
<!-- End If -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>IF-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
Condition Types
| WFCondition Value | Description |
|---|---|
Equals |
Value equals comparison |
Does Not Equal |
Value does not equal |
Contains |
String contains substring |
Does Not Contain |
String does not contain |
Begins With |
String starts with |
Ends With |
String ends with |
Is Greater Than |
Number comparison |
Is Less Than |
Number comparison |
Is Between |
Number in range |
Has Any Value |
Not empty |
Does Not Have Any Value |
Is empty |
Choose from Menu
Present a menu of options and execute different actions based on the user's choice.
Structure
| Mode | Action | Description |
|---|---|---|
| 0 | Menu | Define menu with items |
| 1 | Case | One case per menu item |
| 2 | End Menu | Close menu |
Template
<!-- Menu Definition -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.choosefrommenu</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>MENU-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<key>WFMenuPrompt</key>
<string>Choose an option:</string>
<key>WFMenuItems</key>
<array>
<string>Option 1</string>
<string>Option 2</string>
<string>Option 3</string>
</array>
</dict>
</dict>
<!-- Case 1: Option 1 -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.choosefrommenu</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>MENU-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>1</integer>
<key>WFMenuItemTitle</key>
<string>Option 1</string>
</dict>
</dict>
<!-- Actions for Option 1 go here -->
<!-- Case 2: Option 2 -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.choosefrommenu</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>MENU-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>1</integer>
<key>WFMenuItemTitle</key>
<string>Option 2</string>
</dict>
</dict>
<!-- Actions for Option 2 go here -->
<!-- Case 3: Option 3 -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.choosefrommenu</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>MENU-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>1</integer>
<key>WFMenuItemTitle</key>
<string>Option 3</string>
</dict>
</dict>
<!-- Actions for Option 3 go here -->
<!-- End Menu -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.choosefrommenu</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>MENU-GROUP-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
Important Notes
- Case order must match WFMenuItems order - Each case (mode 1) must appear in the same order as the items in WFMenuItems array
- WFMenuItemTitle must exactly match - The case title must exactly match the corresponding item in WFMenuItems
- One case per item - You need exactly one case action for each menu item
Nesting Control Flow
Control flow blocks can be nested. Each nested block needs its own unique GroupingIdentifier:
<!-- Outer Repeat -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.count</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>OUTER-LOOP-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<key>WFRepeatCount</key>
<integer>3</integer>
</dict>
</dict>
<!-- Inner Conditional -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>INNER-IF-UUID</string>
<key>WFControlFlowMode</key>
<integer>0</integer>
<!-- condition params -->
</dict>
</dict>
<!-- Inner Otherwise -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>INNER-IF-UUID</string>
<key>WFControlFlowMode</key>
<integer>1</integer>
</dict>
</dict>
<!-- Inner End If -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.conditional</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>INNER-IF-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
<!-- Outer End Repeat -->
<dict>
<key>WFWorkflowActionIdentifier</key>
<string>is.workflow.actions.repeat.count</string>
<key>WFWorkflowActionParameters</key>
<dict>
<key>GroupingIdentifier</key>
<string>OUTER-LOOP-UUID</string>
<key>WFControlFlowMode</key>
<integer>2</integer>
</dict>
</dict>
Common Mistakes
-
Using string instead of integer for WFControlFlowMode
- Wrong:
<string>0</string> - Right:
<integer>0</integer>
- Wrong:
-
Mismatched GroupingIdentifier
- All parts of a control flow block must share the same GroupingIdentifier
-
Missing End action
- Every start (mode 0) must have a corresponding end (mode 2)
-
Wrong order in menu cases
- Cases must appear in the same order as WFMenuItems
-
Referencing wrong UUID for loop items
- Repeat Item uses the start action's UUID
- Repeat Index uses the end action's UUID