Files

David Culbreth 3b14c65998 re-uploading work

2026-02-04 17:46:30 -06:00

14 KiB

Raw Blame History

Event & Enforcement Query API

The Event & Enforcement Query API provides read-only endpoints for querying events and enforcements in the Attune automation platform. These endpoints enable monitoring of trigger firings (events) and rule activations (enforcements), which are fundamental to understanding automation workflow execution.

Overview
Event Model
Enforcement Model
Authentication
Endpoints
Use Cases
Related Resources

Overview

Events

Events represent trigger firings - instances when a trigger condition is met and an event is generated. Events are the starting point of automation workflows, carrying the data payload that flows through the system.

Key Characteristics:

Immutable records of trigger activations
Contain payload data from the trigger source
Link to the trigger that generated them
Can be queried by trigger, source, or time range

Enforcements

Enforcements represent rule activations - instances when a rule matches an event and schedules actions for execution. Enforcements are the bridge between events and executions.

Key Characteristics:

Created when a rule's conditions match an event
Track the status of rule execution (pending, scheduled, running, completed, failed)
Link events to the resulting executions
Store condition evaluation results

Event Flow

Sensor/Trigger → Event → Rule Evaluation → Enforcement → Execution(s)

Event Model

Event Object

{
  "id": 123,
  "trigger": 456,
  "trigger_ref": "core.webhook_received",
  "config": {
    "endpoint": "/webhooks/github",
    "method": "POST"
  },
  "payload": {
    "repository": "attune/platform",
    "action": "push",
    "commit": "abc123"
  },
  "source": 789,
  "source_ref": "github_webhook_sensor",
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}

Fields

Field	Type	Description
`id`	integer	Unique event identifier
`trigger`	integer	Optional trigger ID that generated this event
`trigger_ref`	string	Reference to the trigger (e.g., "core.webhook_received")
`config`	object	Optional configuration data for the event
`payload`	object	Event payload data from the trigger source
`source`	integer	Optional ID of the sensor that created the event
`source_ref`	string	Optional reference to the sensor
`created`	datetime	Timestamp when event was created
`updated`	datetime	Timestamp of last update

Enforcement Model

Enforcement Object

{
  "id": 234,
  "rule": 567,
  "rule_ref": "deploy_on_push",
  "trigger_ref": "core.webhook_received",
  "config": {
    "branch": "main",
    "environment": "production"
  },
  "event": 123,
  "status": "completed",
  "payload": {
    "repository": "attune/platform",
    "commit": "abc123"
  },
  "condition": "passed",
  "conditions": {
    "branch_check": true,
    "approval_check": true
  },
  "created": "2024-01-15T10:00:01Z",
  "updated": "2024-01-15T10:05:00Z"
}

Fields

Field	Type	Description
`id`	integer	Unique enforcement identifier
`rule`	integer	Optional rule ID that created this enforcement
`rule_ref`	string	Reference to the rule
`trigger_ref`	string	Reference to the trigger that fired
`config`	object	Optional configuration data
`event`	integer	Optional ID of the event that triggered this enforcement
`status`	string	Enforcement status (see below)
`payload`	object	Data payload for the enforcement
`condition`	string	Overall condition result: `passed`, `failed`, `skipped`
`conditions`	object	Detailed condition evaluation results
`created`	datetime	Timestamp when enforcement was created
`updated`	datetime	Timestamp of last update

Enforcement Status

Status	Description
`pending`	Enforcement created, waiting to be processed
`scheduled`	Actions scheduled for execution
`running`	Enforcement is actively running
`completed`	All actions completed successfully
`failed`	Enforcement failed due to error
`cancelled`	Enforcement was cancelled

Enforcement Condition

Condition	Description
`passed`	All rule conditions matched
`failed`	One or more conditions failed
`skipped`	Enforcement was skipped (e.g., rule disabled)

Authentication

All event and enforcement endpoints require authentication. Include a valid JWT access token in the Authorization header:

Authorization: Bearer <access_token>

See the Authentication Guide for details on obtaining tokens.

Endpoints

List Events

Retrieve a paginated list of events with optional filtering.

Endpoint: GET /api/v1/events

Query Parameters:

Parameter	Type	Default	Description
`trigger`	integer	-	Filter by trigger ID
`trigger_ref`	string	-	Filter by trigger reference
`source`	integer	-	Filter by source ID
`page`	integer	1	Page number (1-indexed)
`per_page`	integer	50	Items per page (max 100)

Example Request:

curl -X GET "http://localhost:8080/api/v1/events?trigger_ref=core.webhook_received&page=1&per_page=20" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "trigger": 456,
      "trigger_ref": "core.webhook_received",
      "source": 789,
      "source_ref": "github_webhook_sensor",
      "has_payload": true,
      "created": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 1,
    "total_pages": 1
  }
}

Get Event by ID

Retrieve a single event by its ID.

Endpoint: GET /api/v1/events/:id

Path Parameters:

Parameter	Type	Description
`id`	integer	Event ID

Example Request:

curl -X GET "http://localhost:8080/api/v1/events/123" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": {
    "id": 123,
    "trigger": 456,
    "trigger_ref": "core.webhook_received",
    "config": {
      "endpoint": "/webhooks/github",
      "method": "POST"
    },
    "payload": {
      "repository": "attune/platform",
      "action": "push",
      "commit": "abc123",
      "branch": "main"
    },
    "source": 789,
    "source_ref": "github_webhook_sensor",
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-01-15T10:00:00Z"
  }
}

Error Responses:

404 Not Found: Event not found

List Enforcements

Retrieve a paginated list of enforcements with optional filtering.

Endpoint: GET /api/v1/enforcements

Query Parameters:

Parameter	Type	Default	Description
`rule`	integer	-	Filter by rule ID
`event`	integer	-	Filter by event ID
`status`	string	-	Filter by status (pending, scheduled, running, completed, failed, cancelled)
`trigger_ref`	string	-	Filter by trigger reference
`page`	integer	1	Page number (1-indexed)
`per_page`	integer	50	Items per page (max 100)

Example Request:

curl -X GET "http://localhost:8080/api/v1/enforcements?status=completed&page=1" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": [
    {
      "id": 234,
      "rule": 567,
      "rule_ref": "deploy_on_push",
      "trigger_ref": "core.webhook_received",
      "event": 123,
      "status": "completed",
      "condition": "passed",
      "created": "2024-01-15T10:00:01Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1
  }
}

Get Enforcement by ID

Retrieve a single enforcement by its ID.

Endpoint: GET /api/v1/enforcements/:id

Path Parameters:

Parameter	Type	Description
`id`	integer	Enforcement ID

Example Request:

curl -X GET "http://localhost:8080/api/v1/enforcements/234" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": {
    "id": 234,
    "rule": 567,
    "rule_ref": "deploy_on_push",
    "trigger_ref": "core.webhook_received",
    "config": {
      "branch": "main",
      "environment": "production"
    },
    "event": 123,
    "status": "completed",
    "payload": {
      "repository": "attune/platform",
      "commit": "abc123"
    },
    "condition": "passed",
    "conditions": {
      "branch_check": true,
      "approval_check": true,
      "deployment_ready": true
    },
    "created": "2024-01-15T10:00:01Z",
    "updated": "2024-01-15T10:05:00Z"
  }
}

Error Responses:

404 Not Found: Enforcement not found

Use Cases

Monitoring Event Flow

Track events as they flow through the system:

# Get recent events for a specific trigger
curl -X GET "http://localhost:8080/api/v1/events?trigger_ref=core.webhook_received&per_page=10" \
  -H "Authorization: Bearer <token>"

# Get a specific event's details
curl -X GET "http://localhost:8080/api/v1/events/123" \
  -H "Authorization: Bearer <token>"

Tracking Rule Activations

Monitor which rules are being triggered:

# Get all enforcements for a specific rule
curl -X GET "http://localhost:8080/api/v1/enforcements?rule=567" \
  -H "Authorization: Bearer <token>"

# Get completed enforcements
curl -X GET "http://localhost:8080/api/v1/enforcements?status=completed" \
  -H "Authorization: Bearer <token>"

Debugging Workflow Issues

Investigate why a workflow didn't execute as expected:

# 1. Find the event
curl -X GET "http://localhost:8080/api/v1/events?trigger_ref=core.webhook_received" \
  -H "Authorization: Bearer <token>"

# 2. Check if enforcement was created for the event
curl -X GET "http://localhost:8080/api/v1/enforcements?event=123" \
  -H "Authorization: Bearer <token>"

# 3. Examine enforcement details and condition evaluation
curl -X GET "http://localhost:8080/api/v1/enforcements/234" \
  -H "Authorization: Bearer <token>"

Auditing System Activity

Audit automation activity over time:

# Get all enforcements for a specific trigger type
curl -X GET "http://localhost:8080/api/v1/enforcements?trigger_ref=core.webhook_received" \
  -H "Authorization: Bearer <token>"

# Check failed enforcements
curl -X GET "http://localhost:8080/api/v1/enforcements?status=failed" \
  -H "Authorization: Bearer <token>"

Event-to-Execution Tracing

To trace the full flow from event to execution:

Find the Event: Query events by trigger or time range
Find Enforcements: Query enforcements by event ID
Find Executions: Query executions by enforcement ID (see Execution API)

Example Flow:

# 1. Get event
EVENT_ID=123

# 2. Get enforcements for this event
curl -X GET "http://localhost:8080/api/v1/enforcements?event=${EVENT_ID}" \
  -H "Authorization: Bearer <token>"

# 3. Get executions for the enforcement (from Execution API)
ENFORCEMENT_ID=234
curl -X GET "http://localhost:8080/api/v1/executions?enforcement=${ENFORCEMENT_ID}" \
  -H "Authorization: Bearer <token>"

Best Practices

1. Use Filters to Reduce Data Volume

Always filter by specific criteria when possible:

# Good: Filter by trigger
curl -X GET "http://localhost:8080/api/v1/events?trigger_ref=core.webhook_received"

# Better: Add pagination
curl -X GET "http://localhost:8080/api/v1/events?trigger_ref=core.webhook_received&per_page=20"

2. Monitor Enforcement Status

Regularly check for failed or stuck enforcements:

# Check for failed enforcements
curl -X GET "http://localhost:8080/api/v1/enforcements?status=failed"

# Check for long-running enforcements
curl -X GET "http://localhost:8080/api/v1/enforcements?status=running"

3. Correlate Events and Enforcements

Always correlate events with their enforcements to understand rule behavior:

# Get event details
curl -X GET "http://localhost:8080/api/v1/events/123"

# Get related enforcements
curl -X GET "http://localhost:8080/api/v1/enforcements?event=123"

4. Use Pagination for Large Result Sets

Always use pagination when querying large datasets:

curl -X GET "http://localhost:8080/api/v1/events?page=1&per_page=50"

Error Handling

Common Error Codes

Status Code	Description
`400 Bad Request`	Invalid query parameters
`401 Unauthorized`	Missing or invalid authentication token
`404 Not Found`	Event or enforcement not found
`500 Internal Server Error`	Server error

Example Error Response

{
  "error": "Event with ID 999 not found",
  "status": 404
}

Performance Considerations

Query Optimization

Filter at the database level: Use query parameters like trigger, rule, event, and status
Limit result sets: Use per_page to control result size
Index-aware queries: Queries by ID, trigger, rule, and status are optimized with database indexes

Pagination Best Practices

Default page size: 50 items
Maximum page size: 100 items
Use page and per_page parameters consistently

Trigger & Sensor Management API - Manage triggers that create events
Rule Management API - Manage rules that create enforcements
Execution Management API - View executions created by enforcements
Authentication Guide - API authentication details

Future Enhancements

Planned Features

Time Range Filtering: Filter events and enforcements by creation time range
Advanced Search: Full-text search in event payloads
Aggregation Queries: Count events/enforcements by trigger/rule/status
Real-time Streaming: WebSocket support for live event/enforcement updates
Export Capabilities: Export events and enforcements to CSV/JSON
Event Replay: Replay events for testing and debugging
Retention Policies: Automatic archival of old events and enforcements

Last Updated: 2024-01-13
API Version: v1

14 KiB Raw Blame History

Event & Enforcement Query API

Table of Contents

Overview

Events

Enforcements

Event Flow

Event Model

Event Object

Fields

Enforcement Model

Enforcement Object

Fields

Enforcement Status

Enforcement Condition

Authentication

Endpoints

List Events

Get Event by ID

List Enforcements

Get Enforcement by ID

Use Cases

Monitoring Event Flow

Tracking Rule Activations

Debugging Workflow Issues

Auditing System Activity

Event-to-Execution Tracing

Best Practices

1. Use Filters to Reduce Data Volume

2. Monitor Enforcement Status

3. Correlate Events and Enforcements

4. Use Pagination for Large Result Sets

Error Handling

Common Error Codes

Example Error Response

Performance Considerations

Query Optimization

Pagination Best Practices

Related Resources

Future Enhancements

Planned Features

14 KiB

Raw Blame History