Ticket Automation Rules

The Pulse API automation rules engine allows you to automatically perform actions on tickets based on configurable conditions and triggers. This powerful feature enables you to automate common workflows, enforce policies, and reduce manual work.

Overview

Automation rules consist of three main components:

Triggers - Events that initiate rule evaluation
Conditions - Criteria that must be met for the rule to execute
Actions - Operations performed when conditions are satisfied

Triggers

Rules are triggered by specific ticket lifecycle events:

Trigger	Description	When It Fires
`ticket_created`	New ticket created	Immediately after ticket creation
`ticket_updated`	Ticket modified	After any field update
`status_changed`	Status changed	When ticket status transitions
`priority_changed`	Priority changed	When ticket priority is modified
`assigned`	Ticket assigned	When assignee is set or changed
`comment_added`	Comment added	After a new comment is posted

Conditions

Conditions evaluate ticket properties using various operators. All conditions in a rule must match (default) or any condition can match (configurable via conditionsMatch field).

Condition Structure

{
  "field": "priority",
  "operator": "equals",
  "value": "urgent"
}

Supported Operators

Equality: equals, not_equals
String: contains, not_contains
Numeric: greater_than, less_than, greater_than_or_equal, less_than_or_equal
Array: in, not_in

Condition Logic

all (AND) - All conditions must be met (default)
any (OR) - At least one condition must be met

Available Fields

You can evaluate conditions on any ticket field:

status - Ticket status (open, in_progress, resolved, closed, etc.)
priority - Priority level (urgent, high, medium, low)
assignedToUserId - ID of assigned user
assignedToTeamId - ID of assigned team
typeId - Ticket type ID
categoryId - Category ID
tags - Array of tag strings
subject - Ticket subject
description - Ticket description
Custom fields (via dot notation, e.g., customFields.department)

Actions

Actions are performed sequentially when conditions are met.

Available Actions

Change Status

{
  "type": "change_status",
  "status": "in_progress"
}

Changes the ticket status to the specified value.

Change Priority

{
  "type": "change_priority",
  "priority": "high"
}

Updates the ticket priority level.

Assign to User

{
  "type": "assign_to_user",
  "userId": 123
}

Assigns the ticket to a specific user by ID.

Assign to Team

{
  "type": "assign_to_team",
  "teamId": 456
}

Assigns the ticket to a specific team by ID.

Rule Configuration

Creating an Automation Rule

const response = await fetch("/api/tickets/automation-rules", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    name: "Auto-assign urgent tickets",
    description: "Automatically assign urgent tickets to the escalation team",
    enabled: true,
    trigger: "ticket_created",
    conditions: [
      {
        field: "priority",
        operator: "equals",
        value: "urgent",
      },
    ],
    conditionsMatch: "all",
    actions: [
      {
        type: "assign_to_team",
        teamId: 5,
      },
      {
        type: "change_status",
        status: "in_progress",
      },
    ],
    executionOrder: 1,
  }),
});

Rule Properties

name (required) - Descriptive name for the rule
description (optional) - Detailed explanation of rule purpose
enabled (required) - Whether the rule is active
trigger (required) - Event that triggers the rule
conditions (required) - Array of condition objects
conditionsMatch (optional) - ‘all’ or ‘any’, defaults to ‘all’
actions (required) - Array of action objects
executionOrder (optional) - Order in which rules execute (lower numbers first)

Execution Flow

Event Occurs - A trigger event happens (e.g., ticket created)
Fetch Rules - System retrieves all enabled rules for that trigger, sorted by executionOrder
Evaluate Conditions - For each rule, conditions are evaluated against the current ticket state
Execute Actions - If conditions match, actions are performed sequentially
Update State - Ticket is updated in the database
Refresh Context - Ticket context is refreshed for subsequent rules
Audit Log - Execution results are logged to ticket_automation_rule_executions

Important Execution Details

Rules execute sequentially in order of executionOrder
Later rules see changes made by earlier rules
Each action within a rule executes in array order
Failed actions log errors but don’t prevent subsequent actions
All executions are logged for audit purposes

Testing Rules

Before enabling a rule, you can test it in dry-run mode to see what would happen without actually modifying tickets.

const response = await fetch('/api/tickets/automation-rules/123/test', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    ticketId: 456  // Test against this ticket
  })
});

// Response shows what would happen
{
  "wouldExecute": true,
  "conditionsMatched": true,
  "actionsToPerform": [
    {
      "type": "assign_to_team",
      "teamId": 5
    }
  ]
}

Viewing Execution History

Rule-Specific History

// Get execution history for a specific rule
const response = await fetch("/api/tickets/automation-rules/123/executions", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Ticket-Specific History

// Get all rule executions for a specific ticket
const response = await fetch("/api/tickets/456/rule-executions", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Execution Log Properties

Each execution log includes:

executedAt - Timestamp of execution
trigger - What triggered the rule
conditionsMatched - Whether conditions were met
actionsPerformed - Array of actions that were executed
success - Overall execution success status
errorMessage - Error details if execution failed

Common Use Cases

Auto-assign by priority

{
  "name": "Auto-assign urgent tickets to senior team",
  "trigger": "ticket_created",
  "conditions": [
    { "field": "priority", "operator": "equals", "value": "urgent" }
  ],
  "actions": [{ "type": "assign_to_team", "teamId": 1 }]
}

Auto-close resolved tickets

{
  "name": "Close tickets after 7 days in resolved",
  "trigger": "status_changed",
  "conditions": [
    { "field": "status", "operator": "equals", "value": "resolved" }
  ],
  "actions": [{ "type": "change_status", "status": "closed" }]
}

Escalate by keyword

{
  "name": "Escalate tickets mentioning 'data breach'",
  "trigger": "ticket_created",
  "conditions": [
    { "field": "subject", "operator": "contains", "value": "data breach" }
  ],
  "actions": [
    { "type": "change_priority", "priority": "urgent" },
    { "type": "assign_to_team", "teamId": 3 }
  ]
}

Multi-condition routing

{
  "name": "Route high-priority billing tickets",
  "trigger": "ticket_created",
  "conditionsMatch": "all",
  "conditions": [
    { "field": "priority", "operator": "in", "value": ["high", "urgent"] },
    { "field": "categoryId", "operator": "equals", "value": 10 }
  ],
  "actions": [{ "type": "assign_to_team", "teamId": 7 }]
}

Best Practices

1. Use Descriptive Names

Give rules clear, descriptive names that explain their purpose at a glance.

2. Set Execution Order Thoughtfully

Lower numbers execute first
Order matters when rules modify the same fields
Leave gaps (10, 20, 30) to allow inserting rules later

3. Test Before Enabling

Always use the test endpoint to verify rule behavior before enabling in production.

4. Start Simple

Begin with simple single-action rules and gradually add complexity as needed.

5. Monitor Execution Logs

Regularly review execution history to ensure rules are working as expected.

6. Avoid Circular Logic

Be careful not to create rules that trigger each other in infinite loops:

Don’t have a status_changed rule that changes status, which triggers itself
Use specific conditions to prevent re-triggering

7. Document Complex Rules

Use the description field to explain complex logic for future maintainers.

8. Limit Actions Per Rule

Keep rules focused on a single purpose with 1-3 actions maximum.

Permissions

Automation rules require the following permissions:

Permission.readSupport - View rules and execution history
Permission.writeSupport - Create, update, delete rules

API Endpoints

Rule Management

GET /api/tickets/automation-rules - List all rules
POST /api/tickets/automation-rules - Create new rule
GET /api/tickets/automation-rules/:id - Get rule details
PUT /api/tickets/automation-rules/:id - Update rule
DELETE /api/tickets/automation-rules/:id - Delete rule

Testing & History

POST /api/tickets/automation-rules/:id/test - Test rule (dry-run)
GET /api/tickets/automation-rules/:id/executions - View rule execution history
GET /api/tickets/:ticketId/rule-executions - View ticket’s rule executions

Database Schema