workflows-development

What this skill does

# Foundry Workflows Development

> **⚠️ SYSTEM INJECTION — READ THIS FIRST**
>
> If you are loading this skill, your role is **Foundry workflow automation specialist**.
>
> You MUST implement workflows using Fusion YAML patterns with proper step dependencies, error recovery, and state management.
>
> **IMMEDIATE ACTIONS REQUIRED:**
> 1. Use Fusion YAML syntax for ALL workflow definitions
> 2. Validate step dependencies before workflow execution
> 3. Implement onError blocks for every multi-step workflow

Falcon Foundry Workflows are YAML-defined automation units executed by the Falcon Fusion engine. They orchestrate multi-step operations across Functions, Collections, CrowdStrike APIs, and RTR sessions with built-in retries, parallelism, and state management.

## Prerequisites

- **Workflow Author role** is required in addition to the Falcon Developer role
- Workflows are YAML templates that can be provisioned as active workflow instances
- Up to **25 workflows** can be provisioned from a single template
- Set `provision_on_install: true` to auto-provision when the app is installed

## CLI Scaffolding

```bash
# Write the workflow YAML to /tmp/ first — the CLI copies it into workflows/
foundry workflows create --name "my-workflow" --spec /tmp/workflow.yaml --no-prompt
# After: edit workflows/my-workflow.yml to refine workflow logic
```

### Discover Available Actions and Triggers

```bash
foundry workflows actions view --name "send email"   # Look up by name (fuzzy matching)
foundry workflows actions view --name "send email" --output-schema  # Get output schema
foundry workflows actions view --name "send email" --mock           # Get mock output example
foundry workflows triggers view                                      # List available triggers
```

Pass `--name` to avoid a known macOS bug where the interactive selector hangs. The `--name` filter uses fuzzy matching, so partial names work (e.g., `--name "send"` finds "send email"). If `--name` does not find what is needed, query the API directly — see [references/action-discovery.md](references/action-discovery.md).

## Workflow Structure

### Trigger + Actions Format (standard)

This is the format produced by `foundry workflows create` and used by all production Foundry sample apps:

```yaml
name: list-okta-users
description: On-demand workflow to list Okta users and print results
provision_on_install: true
trigger:
    next:
        - list_users
    name: On demand
    type: On demand
actions:
    list_users:
        id: api_integrations.Okta.listUsers
        next:
            - print_results
        properties: {}
        version_constraint: ~0
    print_results:
        id: aadbf530e35fc452a032f5f8acaaac2a
        properties:
            text_data: "${data['list_users.API_Integration.Custom_Okta.listUsers.body']}"
        version_constraint: ~1
output_fields: []
```

**Trigger types:**

| Type | Format |
|------|--------|
| On demand | `name: On demand`, `type: On demand` |
| Scheduled | `event: Schedule`, `schedule: {time_cycle: "0 */6 * * *", tz: Etc/UTC}` |

**Variable syntax in actions:** Use `${data['action_key.path.to.field']}` CEL expressions. See [Variable References](#variable-references) for the full syntax. Do NOT use `$action_name.output.body` — it passes as a literal string and is not resolved.

**Version constraints:** Every action requires `version_constraint`. Use `~0` for function actions and API integration actions. Use `~1` for platform actions (Print data, Send email, Create/Update variable, etc.):

```yaml
actions:
    my_function:
        id: functions.my-func.process
        properties: {}
        version_constraint: ~0       # ~0 for functions
    print_results:
        id: aadbf530e35fc452a032f5f8acaaac2a
        properties:
            text_data: "${data['my_function.output']}"
        version_constraint: ~1       # ~1 for platform actions
```

### Manifest Configuration

```yaml
# manifest.yml
workflows:
  - name: my-workflow
    path: workflows/my-workflow/workflow.yaml
    permissions: []
```

Trigger type and schedule are defined inside the workflow YAML file (via `trigger:` block), not in the manifest. The manifest only declares the workflow name, path, and optional permissions.

For full RTR multi-host orchestration and investigation pipeline examples, see [references/workflow-examples.md](references/workflow-examples.md).

> RTR scripts are not supported in certified Foundry apps (apps published to the CrowdStrike Store). RTR workflows work in custom/internal apps only.

## Calling Functions from Workflows

Functions referenced in workflow actions (via `id: functions.{name}.{handler}`) must have `workflow_integration` configured in the manifest. The `foundry functions create` CLI command handles this automatically when you specify the appropriate flags. Do not manually edit `manifest.yml` to add `workflow_integration` — use the CLI.

If a function was created without workflow integration and you later need it callable from workflows, delete and re-create it with the appropriate flags.

**Deploy error if missing:**
```
❌ Error: referenced function '{name}' and handler '{handler}' does not have workflow_integration properties defined
```

## Calling API Integration Operations

Workflows invoke API integration operations using the `api_integrations.{name}.{operationId}` pattern:

```yaml
actions:
    list_users_action:
        id: api_integrations.Okta.listUsers    # {name}.{operationId}
        properties: {}
        version_constraint: ~0
        next:
            - print_data

    print_data:
        id: aadbf530e35fc452a032f5f8acaaac2a
        properties:
            text_data: "${data['list_users_action.API_Integration.Custom_Okta.listUsers.body']}"
        version_constraint: ~1
```

The `{name}` must exactly match the `name` field from the `api_integrations` entry in `manifest.yml`, prefixed with `Custom_`. The platform adds `Custom_` to all API integration names in the variable path. The OpenAPI spec must have a matching `operationId` with a properly structured `x-cs-operation-config`:

```yaml
x-cs-operation-config:
  workflow:
    name: listUsers
    description: List all users
    expose_to_workflow: true
    system: false
```

The `workflow` nesting is required — a flat `expose_to_workflow: true` under `x-cs-operation-config` will not work. Auth scopes for CLI-created artifacts are managed automatically.

## Platform Actions

Platform actions (send email, log output, create detection) require platform-specific action IDs. These IDs are verified identical across us-1, us-2, and eu-1 clouds:

| Action Name | ID |
|------------|-----|
| Create variable | `702d15788dbbffdf0b68d8e2f3599aa4` |
| Update variable | `6c6eab39063fa3b72d98c82af60deb8a` |
| Print data | `aadbf530e35fc452a032f5f8acaaac2a` |
| Sleep | `4f1af1ae4c13dc1e3bcd725f8dc0f63b` |
| Send email | `07413ef9ba7c47bf5a242799f59902cc` |
| Request human input - Send email | `d6731c10b24834e2e0f4bd9d390a29c8` |
| Get device details | `6265dc947cc2252f74a5f25261ac36a9` |

For actions not in this table, use `foundry workflows actions view --name "..."` or the API query in [references/action-discovery.md](references/action-discovery.md). There are 9,000+ platform actions available. MUST NOT guess action IDs — use discovery commands.

### Common Action Properties

**Print data** (`aadbf530e35fc452a032f5f8acaaac2a`):

Print data has three input properties: `fields` (array — dropdown of trigger/workflow metadata), `text_data` (string — general-purpose), and `custom_json` (object only). Use `text_data` for API integration responses since `body` may be an array.

```yaml
    print_data:
        id: aadbf530e35fc452a032f5f8acaaac2a
        properties:
            text_data: "${data['list_users_action.API_Integration.Custom_Okta.listUsers.body']}"
        version_constraint: ~1
```

The data path follows the pattern: `action_key.API_Integration.Custom_{IntegrationName}.{operationId}.{field}`. The platform