# Annotation catalog — Dispatch module (ClientVerse Modules 0.4.0) # Authored meaning for the Dispatch objects. Structural facts (package/module/fields) # are authoritative in ../catalog.json; this file adds descriptions/data_source/audience. # See ../README.md and ../../_conventions.md. module: dispatch package: modules applies_to: [modules] summary: > Dispatch is ClientVerse's data-driven notification and digest engine. An admin defines a Dispatch Definition (audience, content query, schedule, channel); a scheduled run evaluates it, creates one Run Item per recipient, renders the content, and delivers it by email and/or in-app notification. It also powers ERM (Experience/Relationship review) workflows such as single-threaded review and auto-promotion. annotation_status: drafted objects: - api_name: Dispatch_Definition__c label: Dispatch Definition kind: custom_object data_source: User-entered (admin configuration) audience: [admins] description: > The central configuration record for one scheduled notification or digest: what it queries, who receives it, how often it runs, how it is branded, and how it is delivered. Everything else in Dispatch hangs off a Definition. key_fields: - {api_name: Active__c, purpose: "Whether this definition is enabled for scheduling."} - {api_name: Primary_Object__c, purpose: "The object the digest is built from."} - {api_name: Entry_Criteria__c, purpose: "Filter selecting which records qualify."} - {api_name: Subscriber_Source__c, purpose: "How recipients are determined (criteria, list, role)."} - {api_name: Subscriber_Criteria__c, purpose: "Filter selecting recipients when source is criteria-based."} - {api_name: Frequency__c, purpose: "Cadence (e.g. Daily, Weekly, Monthly)."} - {api_name: Run_Times__c, purpose: "Time(s) of day the dispatch runs."} - {api_name: Day_of_Week__c, purpose: "Day for weekly cadence."} - {api_name: Day_of_Month__c, purpose: "Day for monthly cadence."} - {api_name: Timezone__c, purpose: "Timezone the schedule is evaluated in."} - {api_name: Email_Subject_Template__c, purpose: "Merge template for the email subject."} - {api_name: From_Name__c, purpose: "Sender display name."} - {api_name: From_Address__c, purpose: "Sender email address."} - {api_name: Reply_To__c, purpose: "Reply-to address."} - {api_name: Enable_Reply_Routing__c, purpose: "Route replies back into Salesforce via a flow."} - {api_name: Context_Mode__c, purpose: "Per-recipient vs shared digest context."} - {api_name: Use_External_MAP__c, purpose: "Send via an external marketing platform instead of Salesforce email."} - {api_name: Auto_Promotion_Behavior__c, purpose: "ERM: what happens when a review window expires."} - {api_name: Review_Window_Hours__c, purpose: "ERM: how long reviewers have before auto-promotion."} - {api_name: Production_ID__c, purpose: "Administrative external id (system-managed)."} notes: 48 fields total; the remainder cover throttling, retry, branding HTML, and activity creation. - api_name: Dispatch_Subscription__c label: Dispatch Subscription kind: custom_object data_source: User-entered / system-managed (enrollment) audience: [admins, attorneys, bd] description: > A recipient's enrollment in a Dispatch Definition, with their per-subscriber overrides (channel, frequency, send time, filters). Created by auto-enrollment rules or by the user subscribing. key_fields: - {api_name: Dispatch_Definition__c, purpose: "The definition subscribed to."} - {api_name: Subscriber__c, purpose: "Polymorphic subscriber reference."} - {api_name: Subscriber_User__c, purpose: "Subscriber when an internal user."} - {api_name: Subscriber_Contact__c, purpose: "Subscriber when a contact."} - {api_name: Delivery_Channel__c, purpose: "Email, in-app, or both."} - {api_name: Frequency_Override__c, purpose: "Per-subscriber cadence override."} - {api_name: Filters_JSON__c, purpose: "Per-subscriber content filter."} - {api_name: Is_Active__c, purpose: "Whether the subscription is active."} - {api_name: Assignment_Source__c, purpose: "How the subscription was created (auto-enroll vs manual)."} - {api_name: Unsubscribed_Date__c, purpose: "When the subscriber opted out."} - api_name: Dispatch_Run__c label: Dispatch Run kind: custom_object data_source: System-managed (execution record) audience: [admins] description: > One execution of a Dispatch Definition. Records what was evaluated, how many items were created/sent/failed/skipped, and any error summary. The audit trail for a scheduled send. key_fields: - {api_name: Dispatch_Definition__c, purpose: "The definition that ran."} - {api_name: Run_Type__c, purpose: "Scheduled, manual, or test."} - {api_name: Status__c, purpose: "Run status (queued, running, complete, failed)."} - {api_name: Records_Evaluated__c, purpose: "How many source records were considered."} - {api_name: Items_Created__c, purpose: "Run Items generated."} - {api_name: Items_Sent__c, purpose: "Successfully delivered items."} - {api_name: Items_Failed__c, purpose: "Failed deliveries."} - {api_name: Error_Summary__c, purpose: "Aggregated error detail for troubleshooting."} - api_name: Dispatch_Run_Item__c label: Dispatch Run Item kind: custom_object data_source: System-managed (per-recipient delivery) audience: [admins] description: > One rendered, addressed message produced by a Run for a single recipient. Holds the rendered subject/body, delivery + engagement timestamps (sent, opened, clicked, replied), and links back to its Run and Subscription. key_fields: - {api_name: Run__c, purpose: "Parent run."} - {api_name: Subscription__c, purpose: "The subscription this item was sent for."} - {api_name: Recipient_Email__c, purpose: "Delivery address."} - {api_name: Rendered_Subject__c, purpose: "Final merged subject."} - {api_name: Rendered_Body__c, purpose: "Final merged HTML body."} - {api_name: Status__c, purpose: "Delivery status."} - {api_name: Sent_At__c, purpose: "Send timestamp."} - {api_name: Opened_At__c, purpose: "First open."} - {api_name: Clicked_At__c, purpose: "First click."} - {api_name: Reply_Received__c, purpose: "Whether the recipient replied."} - {api_name: Skip_Reason__c, purpose: "Why an item was skipped, if applicable."} - api_name: Dispatch_Section__c label: Dispatch Section kind: custom_object data_source: User-entered (admin configuration) audience: [admins] description: > A content block within a digest (rich text or a data table), with its own visibility rule and ordering. Sections compose the body of a Dispatch Definition. key_fields: - {api_name: Dispatch_Definition__c, purpose: "Parent definition."} - {api_name: Section_Type__c, purpose: "Rich text vs data table."} - {api_name: Sort_Order__c, purpose: "Position in the digest."} - {api_name: Visibility_Rule__c, purpose: "Condition controlling whether the section shows."} - {api_name: Hide_If_Empty__c, purpose: "Suppress the section when it has no rows."} - api_name: Dispatch_DataTable_Config__c label: Dispatch Data Table Config kind: custom_object data_source: User-entered (admin configuration) audience: [admins] description: > Defines a tabular section: its data source (SOQL template, report, list view, or Apex provider), row limit, sort, and inline-edit behavior. key_fields: - {api_name: Section__c, purpose: "The section this table renders in."} - {api_name: Data_Source_Type__c, purpose: "SOQL, report, list view, or Apex."} - {api_name: SOQL_Template__c, purpose: "Query template when source is SOQL."} - {api_name: Object_API_Name__c, purpose: "Object the rows come from."} - {api_name: Enable_Inline_Edit__c, purpose: "Allow editing rows from the digest."} - api_name: Dispatch_DataTable_Column__c label: Dispatch Data Table Column kind: custom_object data_source: User-entered (admin configuration) audience: [admins] description: > One column in a data-table section: which field, its label, formatting, alignment, width, and highlight rule. key_fields: - {api_name: DataTable_Config__c, purpose: "Parent table config."} - {api_name: Field_API_Name__c, purpose: "Field rendered in this column."} - {api_name: Format_Type__c, purpose: "How the value is formatted."} - {api_name: Highlight_Rule__c, purpose: "Conditional highlighting."} - api_name: Dispatch_Action__c label: Dispatch Action kind: custom_object data_source: User-entered (admin configuration) audience: [admins] description: > A call-to-action button a recipient can take from a digest/notification (run a flow, open a URL, update a record), with placement, styling, and a visibility condition. key_fields: - {api_name: Dispatch_Definition__c, purpose: "Definition the action belongs to."} - {api_name: Action_Type__c, purpose: "Flow, URL, or record update."} - {api_name: Flow_API_Name__c, purpose: "Flow launched, when action type is Flow."} - {api_name: Visibility_Condition__c, purpose: "When the action is shown."} - api_name: Dispatch_Action_Log__c label: Dispatch Action Log kind: custom_object data_source: System-managed (audit) audience: [admins] description: > An immutable record of an action a recipient took on a Run Item (including ERM review decisions, exclusions, and created records). The compliance/audit trail for Dispatch actions. key_fields: - {api_name: Run_Item__c, purpose: "The item acted on."} - {api_name: Action_Type__c, purpose: "What kind of action."} - {api_name: Action_Taken__c, purpose: "The specific action/decision."} - {api_name: Actor_Contact__c, purpose: "Who took the action."} - {api_name: Exclusion_Reason__c, purpose: "Reason, for exclusion actions."} - api_name: Dispatch_Settings__c label: Dispatch Settings kind: custom_object data_source: System-managed (org throttle state) audience: [admins] description: > Org-level Dispatch state, primarily daily contact-email throttling counters and the last reset date. Backs the contact email limit guardrail. - api_name: Dispatch_Config__mdt label: Dispatch Config kind: custom_metadata data_source: Configuration (custom metadata) audience: [admins] description: > Tunable batch sizes for Dispatch processing (definition batch, run-item batch, insert chunk). Deploy-time configuration, not per-record data. - api_name: Dispatch_Role_Mapping__mdt label: Dispatch Role Mapping kind: custom_metadata data_source: Configuration (custom metadata) audience: [admins] description: > Maps a role/type to a Dispatch Definition for role-based auto-enrollment (e.g. enroll all relationship managers in a given digest). # Objects the Dispatch module *extends* (adds fields to) rather than owns — see ../catalog.json: extends: - api_name: Activity note: "Adds Dispatch_Run_Item__c lookup so tasks/events can link back to the digest that created them." - api_name: Clientverse_Log__c note: "Adds Action__c / Run_Item__c so Dispatch activity surfaces in the Core logging object."