> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machina.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Automated sequences of actions that coordinate the flow of data and interactions between different components of the Machina Sports platform. They define how your fan experiences respond to events, process data, and deliver personalized content.

## Workflow Structure

Workflows in Machina Sports are defined in YAML format with the following key sections:

```yaml theme={null}
workflow:
  name: "workflow-name"                # Unique identifier for the workflow
  title: "Workflow Title"              # Human-readable title
  description: "Workflow description"  # Brief description of purpose
  context-variables:                   # Environment variables and API keys
    variable-name:
      key: "value"
  inputs:                              # Input parameters
    input-name: "$.get('parameter')"   # JSONPath expressions for inputs
  outputs:                             # Output parameters
    output-name: "$.get('result')"     # JSONPath expressions for outputs
  tasks:                               # Sequential tasks to execute
    - type: "task-type"                # Type of task (connector, document, prompt, mapping)
      name: "task-name"                # Unique name for the task
      description: "Task description"  # Brief description
      # Task-specific configuration
```

## Task Types

Workflows support several task types to handle different operations:

### Connector Tasks

Connect to external APIs and services to fetch or send data.

```yaml theme={null}
- type: "connector"
  name: "fetch-team-data"
  connector:
    name: "sportradar-nba"
    command: "get-teams/{team_id}/{data_type}"
    command_attribute:
      team_id: "$.get('team_id')"
      data_type: "'profile.json'"
  inputs:
    api_key: "$.get('api_key')"
  outputs:
    team-profile: "$"
```

### Document Tasks

Perform operations on documents in the Machina database (search, update, bulk-save).

```yaml theme={null}
- type: "document"
  name: "load-similar-documents"
  config:
    action: "search"
    threshold-docs: 10
    search-vector: true
  connector:
    name: "machina-ai"
    command: "invoke_embedding"
    model: "text-embedding-3-small"
  inputs:
    name: "'content-snippet'"
    search-query: "$.get('messages')"
  outputs:
    documents: "$.get('documents')"
```

### Prompt Tasks

Execute AI prompts to generate content or analyze data.

```yaml theme={null}
- type: "prompt"
  name: "chat-completions-prompt"
  connector:
    name: "machina-ai"
    command: "invoke_prompt"
    model: "gpt-4o"
  inputs:
    documents: "$.get('documents')"
    messages: "$.get('messages')"
  outputs:
    message: "$.get('choices')[0].get('message').get('content')"
```

### Mapping Tasks

Transform data between different formats using predefined mappings.

```yaml theme={null}
- type: "mapping"
  name: "sportradar-nba-team-mapping"
  inputs:
    team_profile: "$.get('team-profile')"
  outputs:
    team_id: "$.get('team_id')"
    team_name: "$.get('team_name')"
    # Additional mapped fields
```

## Conditional Logic

Tasks can include conditions to control execution flow:

```yaml theme={null}
- type: "document"
  name: "update-thread-document"
  condition: "$.get('document_id') is not None"
  # Task configuration
```

## Real-World Example: Chat Completions Workflow

This example from our samples shows a workflow that processes chat messages and generates AI responses:

```yaml theme={null}
workflow:
  name: "chat-completions"
  title: "Chat Completions"
  description: "Workflow to execute a chat completion."
  context-variables:
    machina-ai:
      api_key: "$TEMP_CONTEXT_VARIABLE_SDK_OPENAI_API_KEY"
  inputs:
    messages: "$.get('messages', [])"
  outputs:
    message: "$.get('message')"
    workflow-status: "$.get('message') is not None and 'executed' or 'skipped'"
  tasks:
    # Load similar documents for context
    - type: "document"
      name: "load-similar-documents"
      config:
        action: "search"
        threshold-docs: 10
        search-vector: true
      connector:
        name: "machina-ai"
        command: "invoke_embedding"
        model: "text-embedding-3-small"
      inputs:
        name: "'content-snippet'"
        search-query: "$.get('messages')"
      outputs:
        documents: "$.get('documents')"

    # Generate response using AI
    - type: "prompt"
      name: "chat-completions-prompt"
      connector:
        name: "machina-ai"
        command: "invoke_prompt"
        model: "gpt-4o"
      inputs:
        documents: "$.get('documents')"
        messages: "$.get('messages')"
      outputs:
        message: "$.get('choices')[0].get('message').get('content')"
```

## Common Workflow Patterns

### Data Synchronization

Fetch data from external sources and store it in your Machina database.

### Content Generation

Create AI-generated content based on sports data and user context.

### Chat Processing

Handle user messages and generate contextually relevant responses.

### Scheduled Tasks

Execute workflows at regular intervals using scheduler agents.

## Next Steps

* Explore [Agents](/core-components/agents) to understand how to schedule workflows
* Learn about [Connectors](/core-components/connectors) to integrate data sources
* Review [Mappings](/core-components/mappings) to transform data between formats
* See [Prompts](/core-components/prompts) to optimize AI outputs