PSA/ee/docs/plans/2026-05-25-ticket-audit-logs/conventions.md

Ticket Activity Conventions

Author: Robert Isaacs · Date: 2026-05-25

This document captures the conventions any new ticket mutation path must follow to participate in the unified ticket activity timeline. It complements PRD.md.

Where to write activity rows

Use the shared helper:

import {
  TICKET_ACTIVITY_ACTOR,
  TICKET_ACTIVITY_ENTITY,
  TICKET_ACTIVITY_EVENT,
  TICKET_ACTIVITY_SOURCE,
  writeTicketActivity,
} from '@alga-psa/shared/lib/ticketActivity';

Write inside the same transaction as the underlying ticket/comment/document mutation. This keeps activity rows atomically consistent with the data they describe.

await writeTicketActivity(trx, {
  tenant,
  ticketId,
  eventType: TICKET_ACTIVITY_EVENT.STATUS_CHANGED,
  entityType: TICKET_ACTIVITY_ENTITY.TICKET,
  entityId: ticketId,
  actor: { actorType: TICKET_ACTIVITY_ACTOR.USER, userId: user.user_id },
  source: TICKET_ACTIVITY_SOURCE.UI,
  changes: curatedDiff,
  details: { ...optionalMetadata },
});

Explicit tenant — required

writeTicketActivity never reads app.current_tenant. This is intentional so it works inside withAdminTransaction() paths (inbound email, workflow runner) which do not set the GUC.

If you are tempted to "let the helper figure out tenant," stop and pass it explicitly.

Field diffs — use the curated helper

For ticket updates, use buildCuratedTicketDiffWithLabels (or buildCuratedTicketDiff if you already have labels resolved). The helper:

• Returns only the user-meaningful fields listed in CURATED_TICKET_FIELDS.
• Skips no-op updates (deep-equal old and new).
• Optionally attaches oldLabel/newLabel resolved against the relevant lookup table.

If no curated fields changed, the helper returns {}. Use hasCuratedChanges() and skip the activity write — the UI does not want noise from updates that only touched updated_at or internal denormalized flags.

If you need to log a new field, add it to CURATED_TICKET_FIELDS (in shared/lib/ticketActivity/types.ts). Do not bypass the helper.

Safe metadata rules

details and changes are JSONB. They are read by the timeline UI and may be returned through internal APIs. They must NOT contain:

• Raw inbound email bodies (text/html). Store only messageId, threadId, from, subject, provider, receivedAt.
• Full old/new comment body content for edits. Store only edit-metadata (e.g., { edited: true, is_internal: false }).
• Secrets, API tokens, or PII not already visible on the ticket.

Comment edits are metadata-only by design. If a future feature needs body history, it should live in a separate body-snapshot table, not in ticket_audit_logs.

Event-type vocabulary

Use the constants in TICKET_ACTIVITY_EVENT. Names mirror the existing domain events in packages/event-schemas/src/schemas/domain/ticketEventSchemas.ts where one exists. If you need a new event, add it to the constant set rather than inventing strings at call sites; the UI formatter dispatches on these names.

When picking the event for a curated-diff update, prefer the most specific match:

• single status_id change → TICKET_STATUS_CHANGED (or TICKET_CLOSED/TICKET_REOPENED when transitioning the is_closed boundary)
• single priority_id → TICKET_PRIORITY_CHANGED
• single assigned_to → TICKET_ASSIGNED / TICKET_UNASSIGNED
• single board_id → TICKET_BOARD_MOVED
• single response_state → TICKET_RESPONSE_STATE_CHANGED
• multiple curated fields → TICKET_UPDATED

Actor and source

• actor.actorType should be the actor classification, not the channel. A request originating from the REST API is API; an inbound email parsed to a contact is EMAIL_SENDER; a bundle-master reopen triggered by a child reply is SYSTEM.
• source is the origin channel and is independent of actor type. For example, an inbound-email reply uses actor=EMAIL_SENDER and source=INBOUND_EMAIL.

Failure semantics

Activity writes are intended to fail fast inside the surrounding transaction (NFR-03). If you need a path to tolerate write failure as best-effort, wrap your call in try/catch and document the reason at the call site. Do not change the helper.

Display-name enrichment failures are best-effort: the helper logs and falls back to the actor's IDs without throwing.

Read paths

• readTicketActivity(knex, tenant, ticketId) — activity rows only, ordered newest-first.
• buildUnifiedTicketTimeline(knex, tenant, ticketId) — activity + comments merged chronologically (internal-only in v1; do NOT call from the client portal).
• getTicketTimelineEntries (server action) — production entry point used by the MSP UI. Enforces internal ticket:read permission and blocks client portal users.

Generic audit_logs is untouched

The legacy packages/db/src/lib/auditLog.ts (and its server/src/lib/logging/auditLog.ts copy) remain in place and continue to serve RBAC-style logging. Do not consolidate the two in v1. They have different scope, schema, and tenant-context contract than ticket_audit_logs.