Skip to main content
When automating form-heavy workflows, you often need to pass many related fields. Instead of creating a separate variable for each field, you can pass structured JSON objects and access nested properties directly in your prompts.

​
The Problem

Consider a loan document with a “Section G” containing many fields. Without structured inputs, you’d need to define separate variables for each: 
{section_g_cost}
{section_g_account_number}
{section_g_customers_1_id}
{section_g_customers_1_name}
{section_g_customers_1_description}
... (many more)
This becomes unwieldy and error-prone.

​
The Solution: Nested Access

With structured inputs, you can pass a single JSON object and access nested properties directly: 
{section_g.cost}
{section_g.account_number}
{section_g.customers[0].id}
{section_g.customers[0].name}
{section_g.customers[1].description}
Then when creating a run, you simply pass: 
const { data: run } = await client.runs.create({
  workflow_id: 'workflow-uuid',
  input_values: {
    section_g: {
      cost: 50000,
      account_number: 'ACC-12345',
      customers: [
        { id: 'C001', name: 'John Doe', description: 'Primary applicant' },
        { id: 'C002', name: 'Jane Doe', description: 'Co-applicant' }
      ]
    }
  }
});

​
Syntax Reference

​
Dot Notation

Access object properties with .: 
{user.email}
{config.settings.theme}

​
Bracket Notation (Arrays)

Access array elements by index: 
{customers[0]}
{items[2].name}

​
Bracket Notation (Special Keys)

For keys with special characters, use bracket notation with quotes: 
{data['special-key']}
{headers["Content-Type"]}

​
Combining Notations

Chain any combination for deeply nested structures: 
{form.sections[0].fields['field-name'].value}
{response.data.users[0].profile.settings['notification-preferences']}

​
Works Across All Variable Types

Structured access works consistently for all three variable types:
TypeSyntaxExample
Input{var.path}{patient.demographics.dob}
Sensitive{$var.path}{$credentials.api_key}
Runtime{{var.path}}{{extracted_data.invoice_id}}

​
Sensitive Inputs Example

// Workflow prompt uses: {$credentials.username} and {$credentials.password}

const { data: run } = await client.runs.create({
  workflow_id: 'workflow-uuid',
  sensitive_input_values: {
    credentials: {
      username: 'admin',
      password: 's3cr3t'
    }
  }
});

​
Runtime Values Example

When a focused_action sets a runtime value as an object: 
"Use focused_action to extract the invoice details and save them as {{invoice}}"
You can then access nested properties in subsequent steps: 
"Enter the invoice number {{invoice.number}} in the search field"
"Verify the amount matches {{invoice.line_items[0].amount}}"

​
Error Handling

​
Type Mismatches (Fails the Run)

If you try to access a nested property on a value that isn’t an object or array, the run fails immediately with a clear error: 
// Prompt: {section_g.cost}
// Input: {"section_g": "just a string"}
// ❌ Error: Cannot access path '.cost' on input_values['section_g'] because it is a str, not an object or array
This catches configuration errors early, saving you time and usage costs.

​
Missing Fields (Uses __EMPTY__)

If a nested path simply doesn’t exist, it’s replaced with the __EMPTY__ sentinel value (same behavior as regular empty inputs): 
// Prompt: {section_g.optional_field}
// Input: {"section_g": {"cost": 500}}
// Result: __EMPTY__ (field doesn't exist)
This allows workflows to gracefully handle optional nested fields.

​
Array Out of Bounds

Accessing an array index that doesn’t exist is treated as missing (not a type error): 
// Prompt: {customers[5].name}
// Input: {"customers": [{"name": "John"}]}
// Result: __EMPTY__ (only 1 item in array)

​
Backward Compatibility

Existing workflows continue to work exactly as before:
  • {variable} with a string value → replaced with the string
  • {variable} with an object/array value (no nested access) → JSON stringified
// Prompt: {my_data}
// Input: {"my_data": {"a": 1, "b": 2}}
// Result: {"a": 1, "b": 2}  (stringified JSON)

​
Best Practices

Group Related Fields

Organize related inputs into logical objects (e.g., patient, billing, shipping) rather than dozens of flat variables.

Use Consistent Structures

Define a standard schema for your inputs across workflows. This makes SDK integration easier and reduces errors.

Validate Early

Cyberdesk validates type mismatches at run start. Structure your inputs correctly to catch errors before execution begins.

Handle Optional Fields

Missing nested fields become __EMPTY__. Design your prompts to handle this gracefully for optional data.

​
Real-World Example: Healthcare Form

Fill out the patient intake form:

**Demographics**
- First Name: {patient.demographics.first_name}
- Last Name: {patient.demographics.last_name}
- DOB: {patient.demographics.date_of_birth}
- SSN: {$patient.ssn}

**Insurance**
- Provider: {patient.insurance.provider}
- Policy Number: {patient.insurance.policy_number}
- Group ID: {patient.insurance.group_id}

**Emergency Contacts**
- Primary Contact: {patient.emergency_contacts[0].name}
- Primary Phone: {patient.emergency_contacts[0].phone}
- Secondary Contact: {patient.emergency_contacts[1].name}
- Secondary Phone: {patient.emergency_contacts[1].phone}

const { data: run } = await client.runs.create({
  workflow_id: 'patient-intake-workflow',
  input_values: {
    patient: {
      demographics: {
        first_name: 'John',
        last_name: 'Doe',
        date_of_birth: '1985-03-15'
      },
      insurance: {
        provider: 'Blue Cross',
        policy_number: 'BC123456',
        group_id: 'GRP001'
      },
      emergency_contacts: [
        { name: 'Jane Doe', phone: '555-0101' },
        { name: 'Bob Smith', phone: '555-0102' }
      ]
    }
  },
  sensitive_input_values: {
    patient: {
      ssn: '123-45-6789'
    }
  }
});
This approach transforms 15+ separate variables into a clean, hierarchical structure that mirrors your actual data model.