attune/docs/workflows/parameter-mapping-status.md

Parameter Mapping Status

Quick Reference

This document tracks the implementation status of rule parameter mapping — the system that resolves {{ }} template variables in rule action_params before passing them to action executions.

---

✅ Completed

Database Schema

• Migration: migrations/20240103000003_add_rule_action_params.sql
• Column: rule.action_params (JSONB, default {})
• Index: idx_rule_action_params_gin (GIN index for efficient querying)

Data Models

• File: crates/common/src/models.rs
• Struct: rule::Rule has pub action_params: JsonValue field

API Layer

• File: crates/api/src/dto/rule.rs
• Request DTOs:
  • CreateRuleRequest.action_params (with default {})
  • UpdateRuleRequest.action_params (optional)
• Response DTOs:
  • RuleResponse.action_params
  • RuleSummary.action_params

Repository Layer

• File: crates/common/src/repositories/rule.rs
• Operations: CREATE, UPDATE, and SELECT all handle action_params

Template Resolver Module

• File: crates/common/src/template_resolver.rs
• Struct: TemplateContext with event, pack_config, and system_vars fields
• Function: resolve_templates() — recursively resolves {{ }} templates in JSON values
• Re-exported from attune_common::template_resolver and attune_common::{TemplateContext, resolve_templates}
• Also re-exported from attune_sensor::template_resolver for backward compatibility
• 20 unit tests covering all template features

Template Syntax

Available Sources:

Namespace	Example	Description
event.payload.*	{{ event.payload.service }}	Event payload data
event.id	{{ event.id }}	Event database ID
event.trigger	{{ event.trigger }}	Trigger ref that generated the event
event.created	{{ event.created }}	Event creation timestamp (RFC 3339)
pack.config.*	{{ pack.config.api_token }}	Pack configuration values
system.*	{{ system.timestamp }}	System-provided variables

Integration in Executor

• File: crates/executor/src/event_processor.rs
• Method: resolve_action_params() builds a TemplateContext from the event and rule, then calls resolve_templates()
• Context includes:
  • event.id, event.trigger, event.created, event.payload.* from the Event model
  • system.timestamp (current time), system.rule.id, system.rule.ref
• Called during: enforcement creation in create_enforcement()

Data Flow

Rule.action_params (templates)
  ↓  resolve_templates() in EventProcessor
Enforcement.config (resolved values)
  ↓
Execution.config (passed through)
  ↓
Worker (receives as action parameters)

Template Features

• ✅ Static values pass through unchanged
• ✅ Single-template type preservation (numbers, booleans, objects, arrays)
• ✅ String interpolation with multiple templates
• ✅ Nested object access via dot notation (event.payload.metadata.host)
• ✅ Array element access by index (event.payload.tags.0)
• ✅ Missing values resolve to null with warning logged
• ✅ Empty/null action_params handled gracefully

Documentation

• ✅ docs/workflows/rule-parameter-mapping.md — comprehensive user guide
• ✅ docs/examples/rule-parameter-examples.md — real-world examples
• ✅ docs/api/api-rules.md — API documentation
• ✅ Inline code documentation in template_resolver.rs

---

🔄 Partially Implemented

Pack Config Loading

• Current: Executor passes empty {} for pack.config context
• Needed: Load pack configuration from database before template resolution
• Impact: {{ pack.config.* }} templates resolve to null until implemented
• TODO comment in event_processor.rs marks the location

---

📋 Remaining Work

Phase 1: Complete Core (Short-term)

• Pack config loading — Load pack config from database for {{ pack.config.* }} resolution
• Integration tests — End-to-end test: create rule with templates → fire event → verify enforcement has resolved params

Phase 2: Advanced Features (Future)

• Default values — Parse | default: 'value' syntax for fallback values
• Filters — upper, lower, trim, date, truncate, json
• Conditional templates — {% if event.payload.severity == 'critical' %}...{% endif %}
• Performance — Skip resolution early if no {{ }} patterns detected in action_params

---

🔍 Template Example

Input (Rule action_params):

{
  "message": "Error in {{ event.payload.service }}: {{ event.payload.message }}",
  "channel": "{{ pack.config.alert_channel }}",
  "severity": "{{ event.payload.severity }}",
  "event_id": "{{ event.id }}",
  "trigger": "{{ event.trigger }}"
}

Context (built from Event + Rule):

{
  "event": {
    "id": 456,
    "trigger": "core.error_event",
    "created": "2026-02-05T10:00:00Z",
    "payload": {
      "service": "api-gateway",
      "message": "Connection timeout",
      "severity": "critical"
    }
  },
  "pack": {
    "config": {
      "alert_channel": "#incidents"
    }
  },
  "system": {
    "timestamp": "2026-02-05T10:00:01Z",
    "rule": { "id": 42, "ref": "alerts.error_notification" }
  }
}

Output (Enforcement config):

{
  "message": "Error in api-gateway: Connection timeout",
  "channel": "#incidents",
  "severity": "critical",
  "event_id": 456,
  "trigger": "core.error_event"
}

---

Related Documentation

• Rule Parameter Mapping Guide
• Rule Parameter Examples
• Rule Management API
• Executor Service Architecture