Automation Configuration

Event-Driven Processing

This guide covers discovering available triggers, understanding trigger schemas, configuring rules, and common automation patterns. For workflow fundamentals, see Rules & Triggers concept.

Discovering Available Triggers

The triggers endpoint lists all available triggers that can be configured for automated processing. Each trigger represents a built-in action that executes at specific extension points in the entity lifecycle. Trigger information includes identifiers and filter configuration schemas that enable you to understand trigger capabilities.

Trigger discovery enables you to understand what automation is possible before configuring rules. Each trigger description indicates which hook points it handles and what operations it performs. This information enables you to select appropriate triggers for your processing needs.

The triggers list is namespace-independent, showing all available triggers regardless of namespace context. This enables you to understand system capabilities before configuring namespace-specific rules.

Request

GET /v1/rules/triggers
Authorization: Bearer <your-token>

Response

{
  "triggers": [
    {
      "trigger_id": "corpus_parsing",
      "description": "Initiates parsing workflow for corpus nodes",
      "hook_points": ["root_node.created"],
      "execution_mode": "critical"
    },
    {
      "trigger_id": "node_embedding",
      "description": "Generates embeddings for text nodes",
      "hook_points": ["node.batch.created"],
      "execution_mode": "asynchronous"
    },
    {
      "trigger_id": "formula_augmentation",
      "description": "Extracts mathematical descriptions from formula nodes",
      "hook_points": ["node.updated"],
      "execution_mode": "asynchronous"
    }
  ]
}

See the API Reference for complete endpoint documentation.

Understanding Trigger Schemas

Trigger schemas describe the filter configuration structure for each trigger. Schemas specify which filter types are supported, what parameters are required, and how filters determine trigger execution. Understanding schemas enables you to configure rules correctly and predict trigger behavior.

Schema information includes the filter configuration type name and structure. Each trigger defines its own filter schema, enabling fine-grained control over trigger execution. Schemas enable validation of rule configurations, ensuring that filters match trigger requirements.

Retrieve trigger schemas before configuring rules to understand available filter options. Schema information enables you to construct valid filter configurations that achieve your processing goals while avoiding configuration errors.

Request

GET /v1/rules/triggers/corpus_parsing/schema
Authorization: Bearer <your-token>

Response

{
  "trigger_id": "corpus_parsing",
  "schema": {
    "type": "object",
    "properties": {
      "mime_types": {
        "type": "array",
        "items": { "type": "string" },
        "description": "MIME types to process"
      },
      "exclude_mime_types": {
        "type": "array",
        "items": { "type": "string" },
        "description": "MIME types to exclude"
      }
    }
  }
}

Schema Validation

The system validates filter configurations against trigger schemas when creating or updating rules. Invalid configurations are rejected with detailed error messages indicating which fields failed validation.

Configuring Rules

Rules associate triggers with namespaces and provide filter configurations that determine when triggers should execute. Creating or updating a rule requires a trigger identifier and filter configuration that matches the trigger's schema. The system validates filter configurations against trigger schemas, ensuring compatibility.

Rule configuration enables you to customize automated processing for your namespace. You can configure parsing triggers to process only specific document types, embedding triggers to process only certain node types, or augmentation triggers to process only specific content classifications. This customization enables processing strategies that match your organizational needs.

Rules are namespace-scoped, so each namespace can configure its own trigger behavior independently. This enables different organizations using the same MatsuDB instance to apply different processing strategies without interference. Rule configuration takes effect immediately for new operations, enabling dynamic reconfiguration of processing pipelines.

Create Rule

POST /v1/rules
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "trigger_id": "corpus_parsing",
  "filter": {
    "mime_types": ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"]
  }
}

Update Rule

PUT /v1/rules/corpus_parsing
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "filter": {
    "mime_types": ["application/pdf"],
    "exclude_mime_types": ["application/vnd.ms-excel"]
  }
}

Namespace Isolation

Rules are namespace-scoped, ensuring that automation configurations are isolated per organization. Each namespace can configure its own trigger behavior independently.

For more information about how rules and triggers work, see the Rules & Triggers concept documentation.

Common Rule Patterns

Common rule patterns include type-based filtering, classification-based filtering, and content-based filtering. Each pattern serves different use cases:

Type-Based Filtering

Restricts triggers to specific node types, enabling processing only for relevant content.

{
  "trigger_id": "node_embedding",
  "filter": {
    "node_types": ["TEXT"]
  }
}

Classification-Based Filtering

Restricts triggers to specific classifications, enabling processing only for content matching organizational categories.

{
  "trigger_id": "formula_augmentation",
  "filter": {
    "classifications": ["mathematical", "scientific"]
  }
}

Content-Based Filtering

Uses text matching or pattern recognition to determine trigger execution, enabling sophisticated filtering that considers content characteristics.

{
  "trigger_id": "node_embedding",
  "filter": {
    "content_patterns": ["research", "analysis", "study"]
  }
}

Combined Filters

Combines multiple filter types, creating complex conditions that determine trigger execution.

{
  "trigger_id": "corpus_parsing",
  "filter": {
    "mime_types": ["application/pdf"],
    "exclude_mime_types": ["application/vnd.ms-excel"],
    "min_file_size": 1024,
    "max_file_size": 10485760
  }
}

Rule patterns can combine multiple filter types, creating complex conditions that determine trigger execution. These combinations enable precise control over automated processing, ensuring that triggers execute only when appropriate while avoiding unnecessary processing.

Managing Rules

Rule management includes creating, retrieving, updating, and deleting rules. The upsert operation creates new rules or updates existing ones, enabling dynamic reconfiguration of processing pipelines. Rule retrieval enables you to understand current configurations, while rule deletion enables removal of configurations that are no longer needed.

List operations return all rules configured for your namespace, providing visibility into your automation configuration. This visibility enables you to understand which triggers are active and how they are configured, supporting operational understanding and troubleshooting.

Rule management enables iterative configuration where you refine processing strategies based on operational experience. You can test rule configurations, observe trigger behavior, and adjust filters to optimize processing pipelines. This iterative approach enables continuous improvement of automated processing.

List Rules

GET /v1/rules
Authorization: Bearer <your-token>

Returns all rules configured for your namespace.

Get Rule

GET /v1/rules/corpus_parsing
Authorization: Bearer <your-token>

Returns configuration for a specific trigger.

Delete Rule

DELETE /v1/rules/corpus_parsing
Authorization: Bearer <your-token>

Removes rule configuration, disabling trigger execution.

Best Practices

• Start with simple filter configurations and refine based on operational experience
• Monitor workflow execution to understand rule effectiveness
• Use status tracking to identify processing issues
• Test rule configurations with representative data before deploying to production

Next Steps

Now that you understand automation, explore:

1. Common Patterns: Real-world automation workflows
2. Rules & Triggers Concept: Deep dive into the automation system
3. Workflows Concept: Understanding how triggers initiate processing

Related Concepts

Understanding these concepts will help you configure automation effectively:

• Rules & Triggers: The automation system architecture
• Workflows: How automated processing executes
• Status Tracking: Monitor automated processing progress