# Variable Reference System
How to pass data between actions in Shortcuts.
## Overview
Shortcuts uses a UUID-based system for referencing output from previous actions:
1. **Source action** has a `UUID` parameter identifying its output
2. **Consuming action** references that UUID via `OutputUUID` in `attachmentsByRange`
3. The placeholder character `` (U+FFFC) marks where variables are inserted in text
## UUID Format
UUIDs must be:
- **Uppercase** letters
- Standard UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
Example: `A1B2C3D4-E5F6-7890-ABCD-EF1234567890`
Generate with any UUID generator, just ensure uppercase.
---
## WFSerializationType Values
The `WFSerializationType` key indicates the type of value:
| Type | Description | Usage |
|------|-------------|-------|
| `WFTextTokenString` | Text with embedded variable references | Most common for text params |
| `WFTextTokenAttachment` | Single variable reference (no text) | When param is just a variable |
| `WFContentPredicateTableTemplate` | Filter/predicate definition | For filter actions |
| `WFDictionaryFieldValueItems` | Dictionary entries | For dictionary creation |
---
## attachmentsByRange Format
The `attachmentsByRange` dictionary maps character positions to variable references:
```xml
attachmentsByRange
{position, length}
OutputUUID
SOURCE-ACTION-UUID
OutputName
Display Name
Type
ActionOutput
```
### Range Key Format
`{position, length}` where:
- **position**: Character index in the string (0-based)
- **length**: Always `1` (the placeholder is 1 character)
Examples:
- `{0, 1}` - Variable at start of string
- `{5, 1}` - Variable at position 5
- `{10, 1}` - Variable at position 10
---
## The Placeholder Character
The Object Replacement Character `` (U+FFFC, Unicode code point 65532) serves as a placeholder in the `string` value where variables are inserted.
In XML, represent it as:
- Direct character: ``
- Or escaped: `` or ``
Example string with two variables:
```xml
string
Hello , the weather is 
```
With attachments at positions 6 and 24.
---
## Complete Variable Reference Structure
### WFTextTokenString (Text with Variables)
Use when the parameter is text that may contain variable references:
```xml
ParameterName
Value
string
The result is: 
attachmentsByRange
{16, 1}
OutputUUID
11111111-1111-1111-1111-111111111111
OutputName
Result
Type
ActionOutput
WFSerializationType
WFTextTokenString
```
### WFTextTokenAttachment (Single Variable)
Use when the parameter is just a variable reference with no surrounding text:
```xml
ParameterName
Value
OutputUUID
11111111-1111-1111-1111-111111111111
OutputName
Text
Type
ActionOutput
WFSerializationType
WFTextTokenAttachment
```
---
## Type Values
The `Type` key in attachment dictionaries indicates the variable source:
| Type | Description |
|------|-------------|
| `ActionOutput` | Output from a previous action |
| `Variable` | Named variable (from Set Variable) |
| `CurrentDate` | Current date/time |
| `Clipboard` | Clipboard contents |
| `Ask` | Ask When Run |
| `ExtensionInput` | Shortcut input |
| `DeviceDetails` | Device information |
Example with CurrentDate:
```xml
Type
CurrentDate
```
---
## Aggrandizements (Property Access)
Aggrandizements modify how a variable is accessed, like getting a property or coercing type:
```xml
Aggrandizements
PropertyName
Name
Type
WFPropertyVariableAggrandizement
```
### Common Aggrandizement Types
#### Property Access
```xml
PropertyName
Name
Type
WFPropertyVariableAggrandizement
```
#### Dictionary Key Access
```xml
DictionaryKey
keyName
Type
WFDictionaryValueVariableAggrandizement
```
#### Type Coercion
```xml
CoercionItemClass
WFStringContentItem
Type
WFCoercionVariableAggrandizement
```
---
## Common Output Names
When referencing action outputs, use these common `OutputName` values:
| Action | OutputName |
|--------|------------|
| Text (gettext) | `Text` |
| Ask for Input | `Provided Input` |
| Ask LLM | `Response` |
| Get Weather | `Weather Conditions` |
| Get Current Location | `Current Location` |
| URL | `URL` |
| Get Contents of URL | `Contents of URL` |
| Number | `Number` |
| Date | `Date` |
| List | `List` |
| Dictionary | `Dictionary` |
| Repeat Each | `Repeat Item` |
| Repeat Count | `Repeat Index` |
---
## Example: Chaining Three Actions
```xml
WFWorkflowActionIdentifier
is.workflow.actions.gettext
WFWorkflowActionParameters
UUID
11111111-1111-1111-1111-111111111111
WFTextActionText
Hello World
WFWorkflowActionIdentifier
is.workflow.actions.askllm
WFWorkflowActionParameters
UUID
22222222-2222-2222-2222-222222222222
WFLLMPrompt
Value
string
Translate this to French: 
attachmentsByRange
{26, 1}
OutputUUID
11111111-1111-1111-1111-111111111111
OutputName
Text
Type
ActionOutput
WFSerializationType
WFTextTokenString
WFWorkflowActionIdentifier
is.workflow.actions.showresult
WFWorkflowActionParameters
Text
Value
attachmentsByRange
{0, 1}
OutputUUID
22222222-2222-2222-2222-222222222222
OutputName
Response
Type
ActionOutput
string

WFSerializationType
WFTextTokenString
```
---
## Multiple Variables in One Parameter
When a parameter contains multiple variable references:
```xml
Text
Value
string
Name: , Age: 
attachmentsByRange
{6, 1}
OutputUUID
UUID-FOR-NAME
OutputName
Name
Type
ActionOutput
{14, 1}
OutputUUID
UUID-FOR-AGE
OutputName
Age
Type
ActionOutput
WFSerializationType
WFTextTokenString
```
Note: Position counting includes all characters including the placeholder ``.