tessera/docs/rt-architecture-analysis.md

Request Tracker Architecture: Deep-Dive Technical Analysis

Source: RT 5.0.5 codebase analysis + official docs (docs.bestpractical.com)

Purpose: Reference for reimplementing RT's paradigm in Rust

---

1. SCRIPS — Event-Driven Automation Engine

Conceptual Model

A Scrip is a rule: "When X happens, if condition Y is met, execute action Z using template W."

Four primitives compose a scrip:

• Condition (RT::ScripCondition): Has ApplicableTransTypes — comma-separated string of transaction types it matches (e.g., "Create,Correspond") or "Any". Modules like OnCreate, OnStatusChange, UserDefined.
• Action (RT::ScripAction): Maps via ExecModule to a Perl module under RT::Action::* (SendEmail, AutoReply, CreateTickets, etc.). Has Argument field for parameterization.
• Template (RT::Template): Global or queue-specific. Types: "Perl" (Text::Template) or "Simple" (variable substitution).
• Stage: TransactionCreate (fires per-transaction) or TransactionBatch (fires once after batched updates).

Data Model

Scrips: id, Queue(0=global), Template(name), ScripCondition(id), ScripAction(id),
        Description, Disabled, CustomPrepareCode, CustomCommitCode, CustomIsApplicableCode
ObjectScrips: id, Scrip(FK), Stage, ObjectId(0=global or Queue id), SortOrder

Key insight: The same Scrip record can be applied to multiple queues via ObjectScrips, each with different Stage and SortOrder.

Dispatch Model — Prepare/Commit Two-Phase

Prepare phase (RT::Scrips::Prepare):

1. Load Ticket + Transaction as SystemUser (bypass ACL)
2. Find matching Scrips: global + queue-specific, filtered by Stage, matched by Condition.ApplicableTransTypes using SQL LIKE
3. Sort by SortOrder
4. For each: IsApplicable (no-side-effects check), then Prepare (builds message, determines recipients — no send), push to prepared_scrips

Commit phase (RT::Scrips::Commit): Iterate prepared_scrips in order, call Commit (actual side effects)

Dry-run mode: On Ticket Update page load, ALL scrips run in dry-run (Prepare only, no Commit) to populate the "Scrips and Recipients" preview.

Batch mode: With $UseTransactionBatch, multiple updates accumulate in _TransactionBatch. RanTransactionBatch flag prevents infinite loops. TransactionBatch-stage scrips see ALL batched transactions.

Invariants & Edge Cases

• Prepare failures silently skip the scrip; Commit failures are NOT retried
• Template scoping: queue-specific template overrides global for the same name
• Global + queue-specific scrips both apply; their union runs sorted together
• SystemUser escalation is essential — automation must not be gated by the triggering user's ACL
• CustomIsApplicableCode/CustomPrepareCode/CustomCommitCode allow code injection at three points, guarded by ExecuteCode right
• The Disabled boolean on Scrips is separate from the deprecated Disabled stage

---

2. TRANSACTION QUERY BUILDER

Conceptual Model

Five-layer pipeline: UI Tree → QueryBuilder::Tree (AST) → RT::SQL parser → RT::Tickets dispatch → DBIx::SearchBuilder SQL generation.

Transaction Model

Everything is a Transaction: Status changes, owner changes, comments, correspondence, CF updates, link changes, time worked — all create Transaction records.

Schema: id, ObjectType, ObjectId, Type, Field, OldValue, NewValue, Data, Creator, Created

Each transaction can have MIME attachments.

Dispatch Table Architecture

RT::Tickets::%FIELD_METADATA maps searchable fields to type handlers:

Status => [STRING], Queue => [QUEUE], Owner => [WATCHERFIELD => 'Owner'],
Requestor => [WATCHERFIELD => 'Requestor'], LinkedTo => [LINK => 'To'],
DependsOn => [LINK => To => 'DependsOn'], CF => [CUSTOMFIELD => 'Ticket'],
TxnCF => [CUSTOMFIELD => 'Transaction'], Content => [TRANSCONTENT],
Lifecycle => [LIFECYCLE], Created => [DATE => 'Created']

Each type dispatches to a handler (STRING → _StringLimit, WATCHERFIELD → _WatcherLimit, CUSTOMFIELD → _CustomFieldLimit, etc.) that generates appropriate SQL JOINs.

TicketSQL Parser

State-machine parser with states: KEYWORD, OP, VALUE, AGGREGATOR, OPEN_PAREN, CLOSE_PAREN.

Supports:

• Cross-field references (Due < CF.{TargetDate})
• IS/IS NOT NULL
• LIKE/STARTSWITH/ENDSWITH
• SHALLOW modifier

Key Optimizations

• OR→IN conversion: (Status='new' OR Status='open' OR Status='stalled') → Status IN ('new','open','stalled')
• EntryAggregator intelligence: String fields default to OR for =, AND for !=; dates default to OR for equality, AND for ranges
• Join deduplication: _sql_aliases hash tracks which JOINs exist, preventing duplicates
• Post-filtering: Deleted tickets and ACL checks applied after SQL, not in SQL

Edge Cases

• CF name ambiguity (same name, global vs queue-scoped) falls back to name-based query
• IPAddressRange queries decompose = into two range comparisons
• DateTime day-equality decomposes = into >= midnight AND < next midnight
• NULL handling on CFs adds extra EXISTS check on CFs.Name
• UseSQLForACLChecks injects ACL JOINs at SQL level

---

3. CUSTOM FIELDS

Attachment Model

Two join tables:

ObjectCustomFields: Maps CF to container (Queue id, or 0 for global). Controls which CFs appear. ObjectCustomFieldValues: Stores actual values on records. CustomField(FK), ObjectType, ObjectId, Content, LargeContent, Disabled.

LookupTypes encode the relationship: RT::Queue-RT::Ticket (ticket CFs), RT::Queue-RT::Ticket-RT::Transaction (txn CFs), RT::User, RT::Queue, RT::Group.

Typing System

13 types: Select, Freeform, Text, HTML, Wikitext, Image, Binary, Combobox, Autocomplete, Date, DateTime, IPAddress, IPAddressRange.

Each has: sort_order, selection_type flag, canonicalization flag, render types, labels.

Values system: MaxValues (0=unlimited, 1=single, N=capped), UniqueValues, ValuesClass (external sources), CanonicalizeClass (normalization), Pattern (validation regex), BasedOn (cascading), LinkValueTo (object linking).

Permissions

Five distinct rights: SeeCustomField, AdminCustomField, AdminCustomFieldValues, ModifyCustomField, SetInitialCustomField.

The last creates a "set-once-at-creation" pattern. Rights are contextual (per-queue for tickets).

Queryability

Notation: CF.{Name}, TxnCF.{Name}, QueueCF.{Name}, QueueID.CF.{Name}.Content, cross-field comparison.

Compilation: _CustomFieldDecipher resolves name/id to CF object → _CustomFieldJoin performs LEFT JOINs → _LimitCustomField applies operator with type-aware value parsing.

Sorting: ORDER BY CF.{Name} joins ObjectCustomFieldValues and, for selection types, CustomFieldValues to sort by SortOrder.

Edge Cases

• Context-aware permissions (user sees CF on Queue A but not Queue B)
• CF name collision detection and fallback
• External values sources never stored locally
• Content vs LargeContent transparent handling
• SingleValue optimization (DISTINCT joins when MaxValues=1)

---

4. LIFECYCLES

Conceptual Model

A Lifecycle defines: valid statuses (initial/active/inactive), allowed transitions (directed graph), transition-gating rights, UI actions, defaults, and cross-lifecycle move maps.

Stored on Queue (not ticket); tickets inherit through queue.

State Machine Semantics

Date invariants:

• Moving FROM initial TO active/inactive → set Started
• Moving FROM initial/active TO inactive → set Resolved
• Moving BACK from inactive → clear Resolved (critical!)
• Moving FROM initial directly TO inactive → sets BOTH Started AND Resolved

Transition validation (ValidateStatusChange):

1. Is new status valid in lifecycle?
2. Is transition allowed? (IsTransition)
3. Does user have the required right? (CheckRight with 4-level priority: exact→wildcard-from→wildcard-to→full-wildcard→fallback)

CheckRight priority: 'new→open' > '*→open' > 'new→*' > '*→*' > fallback (DeleteTicket for deleted, ModifyTicket otherwise).

Lifecycle rights REPLACE ModifyTicket, not supplement it.

Queue Changes

Move maps are directional ('default→orders' vs 'orders→default'). Maps MUST be complete — any missing status causes a hard error.

On queue change, if owner lacks OwnTicket on new queue, ticket is auto-reassigned to Nobody (safety invariant).

Rights Model

Custom named rights are auto-created: '* → rejected' => 'RejectTicket' creates a RejectTicket right.

No explicit guards for behavioral hooks — handled entirely through Scrips (OnStatusChange, OnResolve conditions).

Edge Cases

• Action deduplication: specific 'from→to' overrides wildcard '*→to'
• Lifecycle caching; no hot-reload without restart
• Disabled lifecycles: existing queues keep working, can't be selected for new queues
• Default statuses cover specific named contexts: on_create, approved, denied, reminder_on_open, reminder_on_resolve
• Batched status changes: TransactionBatch scrips see all transactions atomically

---

Cross-Cutting Architectural Patterns

1. Transaction-centric: Everything produces a transaction → unified audit trail, unified query interface, single Scrip event stream
2. Container-scoped config: CFs, Scrips, Templates all follow global→queue override pattern
3. Prepare/Commit: Separates planning from execution (essential for dry-run, safety)
4. Dispatch tables: Field types → handlers, ApplicableTransTypes → conditions — config-driven, not code-driven extensibility
5. SystemUser identity: Automation runs elevated; reimplementation needs explicit service account concept
6. Aggressive caching: Lifecycle configs, CF join aliases, ACL roles, group memberships — essential at scale