Top-level Workflow Definition¶

This document describes the YAML structure for defining complete SLOP workflows, including their triggers and execution logic, within a single file.

Top-Level Structure¶

The root of the YAML file contains metadata and the main sections for the workflow definition.

---
workflow_name: string # Required: Unique identifier for this workflow definition file.
description: string   # Optional: Human-readable explanation of the workflow's purpose.
version: string     # Optional: Version string for this workflow definition (e.g., "1.0.0").

# Optional: Global configurations shared across the workflow.
global_configs: GlobalConfigsSchema

# Optional: Defines events that initiate taskflow execution.
triggers:
  - TriggerDefinition # List of Trigger Definitions

# Required: Defines the sequences of operations (tasks, subflows, conditions).
taskflows:
  - TaskflowDefinition # List of Taskflow Definitions

# Required: Defines the schemas referenced throughout the workflow definition.
schemas:
  - SchemaDefinition # List of Schema Definitions

Field Definitions¶

Top-Level Fields¶

workflow_name (string, Required): A unique identifier for this workflow definition file. Used for referencing and management.
description (string, Optional): A human-readable explanation of the workflow's overall purpose.
version (string, Optional): Version string for this workflow definition (e.g., "1.0.0").
global_configs (GlobalConfigsSchema, Optional): Reference to a schema defining configurations shared across the workflow, such as secret references. See GlobalConfigsSchema definition in the schemas section.
triggers (list, Optional): Defines the events or conditions that initiate the execution of specific taskflows within this file. Each item in the list must conform to the TriggerDefinition schema.
taskflows (list, Required): Defines the actual sequences of operations (tasks, subflows, conditions). Each item in the list must conform to the TaskflowDefinition schema.
schemas (list, Required): Contains the definitions for all named schemas referenced within this workflow file. Each item must conform to the SchemaDefinition structure.

Trigger Definition¶

Each item in the triggers list defines a specific mechanism that can start a taskflow.

# Structure for each item in the 'triggers' list
- id: string            # Required: Unique identifier for this trigger within this workflow file.
  type: string          # Required: Specifies the kind of trigger (e.g., "webhook", "schedule", "manual", "event").
  enabled: boolean      # Optional (default: true): If false, this trigger is ignored.
  config: TriggerConfigSchema # Required: Reference to a schema containing configuration specific to the trigger type.
  target_taskflow: string # Required: The taskflow_id (from the taskflows section) to execute when this trigger fires.
  input_mapping: InputMappingSchema # Optional: Reference to a schema defining how trigger data maps to the INPUT context of the target_taskflow.

id (string, Required): A unique identifier for this trigger within this workflow file.
type (string, Required): Specifies the kind of trigger. Common types include:
- webhook: Triggered by an incoming HTTP request to a specific SLOP endpoint.
- schedule: Triggered based on a time schedule (e.g., cron).
- manual: Intended to be triggered explicitly via an API call or UI action.
- event: Triggered by an internal SLOP system event.
enabled (boolean, Optional): Defaults to true. If false, this trigger is ignored.
config (TriggerConfigSchema, Required): Reference to a schema containing configuration specific to the trigger type. See TriggerConfigSchema and its type-specific variants (e.g., WebhookTriggerConfigSchema, ScheduleTriggerConfigSchema) in the schemas section.
target_taskflow (string, Required): The taskflow_id (from the taskflows section in this file) that should be executed when this trigger fires.
input_mapping (InputMappingSchema, Optional): Reference to a schema defining how data from the trigger event is mapped to the INPUT context of the target_taskflow. If omitted, the default behavior (e.g., passing the entire trigger payload) applies. See InputMappingSchema definition in the schemas section.
- Keys within the mapping define field names within the INPUT context.
- Values can be literal values or expressions referencing the trigger's payload (e.g., TRIGGER.payload.some_field). The exact expression syntax (e.g., CONTEXT.variable like TRIGGER.payload.field) needs to be consistently applied by the processing engine.

Taskflow Definition¶

Each item in the taskflows list defines a reusable sequence of operations.

# Structure for each item in the 'taskflows' list
- taskflow_id: string # Required: Unique identifier for this taskflow within this workflow file.
  description: string # Optional: Human-readable explanation of what this taskflow does.
  input_schema: TaskflowInputSchema # Optional: Reference to a schema defining the expected structure of the INPUT data.
  config: TaskflowConfigSchema # Optional: Reference to a schema for taskflow-specific execution configuration (e.g., concurrency, timeout).
  tasks: # Required: List of task definitions for this taskflow.
    - TaskDefinition
  subflows: # Optional: List of subflow definitions used within this taskflow.
    - SubflowDefinition
  conditions: # Optional: List of conditional branching points within this taskflow.
    - ConditionDefinition

taskflow_id (string, Required): A unique identifier for this taskflow within this workflow file. Referenced by target_taskflow in triggers.
description (string, Optional): Human-readable explanation of what this specific taskflow does.
input_schema (TaskflowInputSchema, Optional): Reference to a schema defining the expected structure of the INPUT data for this taskflow. Useful for validation and documentation. See TaskflowInputSchema definition in the schemas section.
config (TaskflowConfigSchema, Optional): Reference to a schema for configuration specific to the execution of this taskflow (e.g., max_concurrency, timeout). These might override global settings or provide defaults. See TaskflowConfigSchema definition in the schemas section.
tasks (list, Required): The list of individual task definitions. Each item must conform to the TaskDefinition schema (structure includes id, type, config, dependencies, successors, outputs, etc.). Tasks access initial data via INPUT.<field_name>. See TaskDefinition schema in the schemas section.
subflows (list, Optional): Definitions of subflows used within this taskflow. Each item must conform to the SubflowDefinition schema. See SubflowDefinition schema in the schemas section.
conditions (list, Optional): Definitions of conditional branching points. Each item must conform to the ConditionDefinition schema. See ConditionDefinition schema in the schemas section.

Global Configurations Schema (`GlobalConfigsSchema`)¶

Defines shared values or configurations.

# Example definition for GlobalConfigsSchema within the 'schemas' list
- name: GlobalConfigsSchema
  properties:
    secrets: SecretsSchema # Optional: Reference to a schema for defining secret references.
    # Other potential global settings...

secrets (SecretsSchema, Optional): Reference to a schema for defining references to secrets (e.g., API keys, webhook secrets). See SecretsSchema definition in the schemas section.

Secrets Schema (`SecretsSchema`)¶

Defines how secrets are referenced.

# Example definition for SecretsSchema within the 'schemas' list
- name: SecretsSchema
  # Represents a map where keys are secret names used in configs (e.g., secret_ref)
  # and values specify how to retrieve the secret (e.g., from environment variables).
  additionalProperties: string # Example: Allows any key, value indicates source like "ENV.SECRET_VAR_NAME"
  # Example Usage in global_configs:
  # secrets:
  #   unipile_webhook_secret: "ENV.UNIPILE_SECRET"
  #   github_api_key: "ENV.GH_TOKEN"

Values should indicate the source, e.g., ENV.VARIABLE_NAME for environment variables. Direct embedding of secrets is disallowed.

Schema Definition (`SchemaDefinition`)¶

Structure for defining a named schema within the top-level schemas list.

# Structure for each item in the 'schemas' list
- name: string # Required: The unique name of the schema, used for referencing.
  description: string # Optional: Explanation of the schema's purpose.
  # Schema definition fields (e.g., properties, required, type - avoid 'object')
  # Use standard YAML structure to define the expected data format.
  properties: # Example field
    # Define properties and their expected types (string, integer, boolean, list, map, or another SchemaName)
    example_field: string
    example_list: list
    nested_structure: AnotherSchemaName
  required: [list, of, required, property, names]
  # Use 'additionalProperties: SchemaName' or 'additionalProperties: boolean' for map-like structures
  # Use 'items: SchemaName' or 'items: type' for list structures

name (string, Required): The name used to reference this schema elsewhere in the workflow file.
description (string, Optional): A description of the schema.
Other fields (properties, required, items, additionalProperties, etc.) define the actual structure using standard YAML syntax and basic types (string, integer, boolean, list, map) or references to other defined schemas by name.
Avoid using type: object. Define structure using properties for maps or items for lists.

Variable Syntax¶

Data passing between tasks and access to context (like trigger input) uses a specific syntax interpreted by the workflow engine (e.g., CONTEXT.variable).

INPUT.<field_name>: Accesses data provided to the taskflow, typically mapped from a trigger via input_mapping.
TRIGGER.payload.<field_name>: Accesses data within the payload of the trigger event (used within input_mapping).
<task_id>.<output_key>: Accesses output data generated by a preceding task.
SYSTEM.<variable>: Accesses system variables like SYSTEM.DATE.

Example Workflow¶

---
workflow_name: "UnipileEmailProcessingWorkflow"
description: "Handles incoming emails from Unipile via webhook."
version: "1.0"

global_configs: GlobalConfigsSchema

triggers:
  - id: "unipile_new_email_webhook"
    type: "webhook"
    enabled: true
    config: WebhookTriggerConfigSchema # Specific config for this webhook
    target_taskflow: "process_email_sequence"
    input_mapping: EmailInputMappingSchema

taskflows:
  - taskflow_id: "process_email_sequence"
    description: "Fetches, analyzes, and tags an email."
    input_schema: ProcessEmailInputSchema
    tasks:
      - id: "get_email_content"
        name: "Get Email Resource Content"
        type: "mfo_api_resource_get"
        config:
          resource_id: "INPUT.email_resource_id"
        successors: ["analyze_email"]
        outputs:
          - get_email_content.resource # Output schema could be defined, e.g., UnipileResourceSchema

      - id: "analyze_email"
        name: "Analyze Email with LLM (using Template)"
        type: "mfo_api_chat_send"
        config:
          prompt_template_id: "email_analysis_v1"
          prompt_context: # Schema for context could be defined
            email_content: "get_email_content.resource.content"
          provider_id: "default_llm"
        dependencies: ["get_email_content"]
        successors: ["tag_email_thread"]
        outputs:
          - analyze_email.analysis_result # Output schema: EmailAnalysisResultSchema

      - id: "tag_email_thread"
        name: "Tag Email Thread via Tool"
        type: "mfo_api_tool_execute"
        config:
          tool_id: "unipile_email_tag_thread"
          arguments: # Schema for arguments could be defined
            tag_name: "ai_analyzed"
            thread_id: "INPUT.email_thread_id"
        dependencies: ["analyze_email"]

schemas:
  - name: GlobalConfigsSchema
    properties:
      secrets: SecretsSchema

  - name: SecretsSchema
    additionalProperties: string # e.g., key: unipile_secret, value: ENV.UNIPILE_SECRET

  - name: TriggerDefinition # Base structure, specific types extend this
    properties:
      id: string
      type: string
      enabled: boolean
      config: TriggerConfigSchema
      target_taskflow: string
      input_mapping: InputMappingSchema
    required: [id, type, config, target_taskflow]

  - name: TriggerConfigSchema # Base, specific types like WebhookTriggerConfigSchema extend/use this
    description: Base schema for trigger configurations.
    # Specific trigger types will have their own config schemas

  - name: WebhookTriggerConfigSchema
    properties:
      provider: string
      webhook_id: string
      expected_payload_schema: UnipileWebhookPayloadSchema # Reference to the payload schema
      secret_ref: string # Key name defined in GlobalConfigsSchema.secrets
    required: [provider, webhook_id]

  - name: ScheduleTriggerConfigSchema
    properties:
      cron_expression: string
    required: [cron_expression]

  - name: InputMappingSchema
    additionalProperties: string # Allows mapping keys (input field names) to trigger payload expressions
    # Example Usage:
    # input_mapping:
    #   email_resource_id: "TRIGGER.payload.resource_id"
    #   email_thread_id: "TRIGGER.payload.thread_id"

  - name: TaskflowDefinition
    properties:
      taskflow_id: string
      description: string
      input_schema: TaskflowInputSchema # Reference to a schema defining taskflow input
      config: TaskflowConfigSchema
      tasks: list # Each item conforms to TaskDefinition
      subflows: list # Each item conforms to SubflowDefinition
      conditions: list # Each item conforms to ConditionDefinition
    required: [taskflow_id, tasks]

  - name: TaskflowInputSchema # Base schema, specific taskflows define their own
    description: Base schema for taskflow inputs.

  - name: ProcessEmailInputSchema
    properties:
      email_resource_id: string
      email_thread_id: string
    required: [email_resource_id, email_thread_id]

  - name: TaskflowConfigSchema
    properties:
      max_concurrency: integer
      timeout: string # e.g., "10m"

  - name: TaskDefinition
    properties:
      id: string
      name: string
      description: string
      type: string # e.g., mfo_api_resource_get, mfo_api_chat_send
      config: TaskConfigSchema # Reference to a generic or type-specific task config schema
      dependencies: list # List of task IDs
      successors: list # List of task IDs
      outputs: list # List of output keys/names, e.g., task_id.output_name
      # retry, timeout fields etc.
    required: [id, type]

  - name: TaskConfigSchema # Base schema for task configurations
    description: Base schema, specific task types will have their own config schemas.
    # Example for mfo_api_resource_get:
    # properties: { resource_id: string }, required: [resource_id]
    # Example for mfo_api_chat_send:
    # properties: { prompt_template_id: string, prompt_context: ContextSchema, provider_id: string }, required: [prompt_template_id, provider_id]

  - name: SubflowDefinition
    # Define structure for subflows
    properties:
      id: string
      # ... other subflow fields
    required: [id]

  - name: ConditionDefinition
    # Define structure for conditions
    properties:
      id: string
      # ... other condition fields
    required: [id]

  - name: SchemaDefinition # Meta-schema for schema definitions themselves
    properties:
      name: string
      description: string
      properties: map # Or reference another schema for properties structure
      required: list
      items: string # Or reference another schema for list items
      additionalProperties: string # Or boolean or reference another schema
    required: [name]

  # Schemas referenced in the example workflow:
  - name: EmailInputMappingSchema
    properties:
      email_resource_id: string # Value should be expression like "TRIGGER.payload.resource_id"
      email_thread_id: string   # Value should be expression like "TRIGGER.payload.thread_id"
    required: [email_resource_id, email_thread_id]

  - name: UnipileWebhookPayloadSchema # Example payload schema
    properties:
      resource_id: string
      thread_id: string
    required: [resource_id, thread_id]

  - name: EmailAnalysisResultSchema # Example output schema
    properties:
      sender: string
      subject: string
      summary: string
      intent: string
      priority: integer

  # Add definitions for other referenced schemas like TaskConfigSchema variants,
  # UnipileResourceSchema, ContextSchema etc. as needed.