Skip to main content

​
Contact Tagging — Admin Guide

This guide is for org admins responsible for the tag vocabulary in Settings → CE → Contact Tags. Requires ce.settings.tags.manage.

​
Tag definition fields

​
Seeded defaults

Each organization is seeded with four starter tags. You can rename, recolor, or delete them; new orgs get them automatically.
  • High Acuity (alert, orange) — needs immediate clinical attention.
  • Do Not Admit (alert, red) — policy violation; do not re-admit.
  • Justice Referral / JTOP (purple) — justice-involved intake pathway.
  • Peer Support Candidate (green) — candidate for peer support engagement.

​
Deletion guard

You cannot delete a tag definition while it is still assigned to one or more contacts. The settings UI surfaces an inline error with the assignment count; remove the tag from contacts first (or reassign to a different tag) and then delete the definition.

​
Audit

Every add/remove on a contact emits a tag_added / tag_removed event in the CE-60 audit log (ce_contact_audit_log, category tag). The event includes tag_id, tag_name, tag_color, is_alert, and the actor. The SECURITY DEFINER helper signature is fixed at 12 parameters; CE-61 packs all extended context into the p_details JSONB field.

​
Permission seeding

The migration seeds three permission keys mapped to system roles:

​
Cross-core integration

  • CE-60 (history): tag add/remove events appear in the All History tab.
  • CE-65 (pipeline tiles): tile metadata exposes tags: TagBadge[] and has_alert_tag: boolean. CE-65 owns visual rendering; CE-61 owns the semantic state. Distinct from CE-58 urgency.
  • CE-05 (reporting): tag-name dimension is planned and will be wired once CE-05 reporting ships. No schema blocker.

​
Where the code lives

  • Tables: ce_contact_tags, ce_contact_tag_assignments
  • Hooks: src/cores/ce/hooks/useContactTags.ts, useContactTagMutations.ts, useContactTagAssignments.ts
  • Audit wiring: src/cores/ce/lib/contactTagAudit.ts
  • Filter logic: src/cores/ce/lib/contactTagFilter.ts
  • Settings UI: src/cores/ce/components/settings/ContactTagsSettingsCard.tsx
  • Tile/profile UI: src/cores/ce/components/contacts/ContactTagBadge.tsx, ContactTagAssignmentField.tsx
  • Filter UI: src/cores/ce/components/pipeline/TagFilterControl.tsx