From d4ce94ddf83145b6c0ffdfc226ef177c74273cd1 Mon Sep 17 00:00:00 2001 From: Darren Clarke Date: Wed, 17 Dec 2025 14:53:13 +0100 Subject: [PATCH] Split/merge WIP --- ...bridge-ticket-split-merge-investigation.md | 506 ++++++++++ docs/ticket-field-propagation-design.md | 906 ++++++++++++++++++ 2 files changed, 1412 insertions(+) create mode 100644 docs/bridge-ticket-split-merge-investigation.md create mode 100644 docs/ticket-field-propagation-design.md diff --git a/docs/bridge-ticket-split-merge-investigation.md b/docs/bridge-ticket-split-merge-investigation.md new file mode 100644 index 0000000..ebf48b3 --- /dev/null +++ b/docs/bridge-ticket-split-merge-investigation.md @@ -0,0 +1,506 @@ +# Zammad Ticket Splits & Merges with Bridge Channels + +## Investigation Summary + +This document analyzes how Zammad handles ticket splits and merges, and the implications for our custom bridge channels (WhatsApp, Signal, Voice). + +## Current State + +### How Zammad Handles Split/Merge (Built-in) + +#### Merge (`ticket.merge_to` in `app/models/ticket.rb:330`) + +When ticket A is merged into ticket B: + +1. All articles from A are moved to B +2. A "parent" link is created between A and B +3. Mentions and external links are migrated +4. Source ticket A's state is set to "merged" +5. Source ticket A's owner is reset to System (id: 1) + +**Critical issue:** Ticket preferences are NOT copied or migrated. The target ticket B keeps its original preferences, and source ticket A's preferences become orphaned. + +```ruby +# From app/models/ticket.rb - merge_to method +# Articles are moved: +Ticket::Article.where(ticket_id: id).update_all(['ticket_id = ?', data[:ticket_id]]) + +# But preferences are never touched - they stay on the source ticket +``` + +#### Split (`app/models/form_updater/concerns/applies_split_ticket_article.rb`) + +When an article is split from ticket A to create new ticket C: + +1. Basic ticket attributes are copied (group, customer, state, priority, title) +2. Attachments are cloned +3. A link is created to the original ticket +4. `owner_id` is explicitly deleted (not copied) + +**Critical issue:** Preferences are NOT copied. The new ticket C has no channel metadata. + +```ruby +# From applies_split_ticket_article.rb +def attributes_to_apply + attrs = selected_ticket_article.ticket.attributes + attrs['title'] = selected_ticket_article.subject if selected_ticket_article.subject.present? + attrs['body'] = body_with_form_id_urls + attrs.delete 'owner_id' # Explicitly deleted + attrs + # Note: preferences are NOT included in .attributes +end +``` + +#### Email Follow-up Handling (`app/models/channel/filter/follow_up_merged.rb`) + +Zammad has a postmaster filter that handles incoming emails to merged tickets: + +```ruby +def self.run(_channel, mail, _transaction_params) + return if mail[:'x-zammad-ticket-id'].blank? + + referenced_ticket = Ticket.find_by(id: mail[:'x-zammad-ticket-id']) + return if referenced_ticket.blank? + + new_target_ticket = find_merge_follow_up_ticket(referenced_ticket) + return if new_target_ticket.blank? + + mail[:'x-zammad-ticket-id'] = new_target_ticket.id +end +``` + +This follows the parent link to find the active target ticket. **This only works for email** - no equivalent exists for other channels like Telegram, WhatsApp, or Signal. + +--- + +## Bridge Channel Metadata Structure + +Our bridge channels store critical routing metadata in `ticket.preferences`: + +### WhatsApp + +```ruby +ticket.preferences = { + channel_id: 123, + cdr_whatsapp: { + bot_token: "abc123", # Identifies which bot/channel + chat_id: "+1234567890" # Customer's phone number - WHERE TO SEND + } +} +``` + +### Signal (Direct Message) + +```ruby +ticket.preferences = { + channel_id: 456, + cdr_signal: { + bot_token: "xyz789", + chat_id: "+1234567890" # Customer's phone number + } +} +``` + +### Signal (Group) + +```ruby +ticket.preferences = { + channel_id: 456, + cdr_signal: { + bot_token: "xyz789", + chat_id: "group.abc123...", # Signal group ID + group_joined: true, # Whether customer accepted invite + group_joined_at: "2024-01-01", + original_recipient: "+1234567890" + } +} +``` + +--- + +## How Bridge Channels Use This Metadata + +### Outgoing Messages + +The communication jobs (`CommunicateCdrWhatsappJob`, `CommunicateCdrSignalJob`) rely entirely on ticket preferences: + +```ruby +# From communicate_cdr_whatsapp_job.rb +def perform(article_id) + article = Ticket::Article.find(article_id) + ticket = Ticket.lookup(id: article.ticket_id) + + # These MUST exist or the job fails: + unless ticket.preferences['cdr_whatsapp']['bot_token'] + log_error(article, "Can't find ticket.preferences['cdr_whatsapp']['bot_token']") + end + unless ticket.preferences['cdr_whatsapp']['chat_id'] + log_error(article, "Can't find ticket.preferences['cdr_whatsapp']['chat_id']") + end + + channel = Channel.lookup(id: ticket.preferences['channel_id']) + result = channel.deliver(article) # Uses chat_id to know where to send +end +``` + +### Incoming Messages + +The webhook controllers look up existing tickets: + +**WhatsApp** (`channels_cdr_whatsapp_controller.rb`): +```ruby +# Find open ticket for this customer +state_ids = Ticket::State.where(name: %w[closed merged removed]).pluck(:id) +ticket = Ticket.where(customer_id: customer.id) + .where.not(state_id: state_ids) + .order(:updated_at).first +``` + +**Signal Groups** (`channels_cdr_signal_controller.rb`): +```ruby +# Find ticket by group ID in preferences +ticket = Ticket.where.not(state_id: state_ids) + .where("preferences LIKE ?", "%channel_id: #{channel.id}%") + .where("preferences LIKE ?", "%chat_id: #{receiver_phone_number}%") + .order(updated_at: :desc) + .first +``` + +--- + +## Problem Scenarios + +### Scenario 1: Merge Bridge Ticket → Non-Bridge Ticket + +**Setup:** Ticket A (has WhatsApp metadata) merged into Ticket B (no bridge metadata) + +**What happens:** +- A's articles move to B +- A's preferences stay on A (now in merged state) +- B still has no bridge preferences + +**Result:** Agent replies on ticket B fail - no `chat_id` to send to. + +### Scenario 2: Merge Bridge Ticket → Different Bridge Ticket + +**Setup:** Ticket A (WhatsApp to +111) merged into Ticket B (WhatsApp to +222) + +**What happens:** +- A's articles move to B +- B keeps its preferences (`chat_id: +222`) + +**Result:** Agent replies go to +222, not to +111. Customer +111 never receives responses. + +### Scenario 3: Split Article from Bridge Ticket + +**Setup:** Split an article from Ticket A (has WhatsApp metadata) to create Ticket C + +**What happens:** +- New ticket C is created with no preferences +- C is linked to A + +**Result:** Agent cannot reply via WhatsApp on ticket C at all - job fails immediately. + +### Scenario 4: Incoming Message to Merged Ticket's Customer + +**Setup:** Ticket A (customer +111) was merged into B. Customer +111 sends new message. + +**What happens:** +- Webhook finds customer by phone number +- Looks for open ticket for customer +- A is excluded (merged state) +- Either finds B (if same customer) or creates new ticket + +**Result:** May work if B has same customer, but conversation context is fragmented. + +### Scenario 5: Signal Group Ticket Merged + +**Setup:** Ticket A (Signal group X) merged into Ticket B (no Signal metadata) + +**What happens:** +- All group messages went to A +- A is now merged, B has no group reference +- New messages from group X create a new ticket (can't find existing by group ID) + +**Result:** Conversation splits into multiple tickets unexpectedly. + +--- + +## Recommended Solutions + +### Option 1: Preferences Migration on Merge (Recommended) + +Create a concern that copies bridge channel metadata when tickets are merged: + +```ruby +# app/models/ticket/merge_bridge_channel_preferences.rb +module Ticket::MergeBridgeChannelPreferences + extend ActiveSupport::Concern + + included do + after_update :migrate_bridge_preferences_on_merge + end + + private + + def migrate_bridge_preferences_on_merge + return unless saved_change_to_state_id? + return unless state.state_type.name == 'merged' + + target_ticket = find_merge_target + return unless target_ticket + + # Copy bridge preferences if target doesn't have them + %w[cdr_whatsapp cdr_signal cdr_voice].each do |channel_key| + next unless preferences[channel_key].present? + next if target_ticket.preferences[channel_key].present? + + target_ticket.preferences[channel_key] = preferences[channel_key].deep_dup + target_ticket.preferences['channel_id'] ||= preferences['channel_id'] + end + + target_ticket.save! if target_ticket.changed? + end + + def find_merge_target + Link.list(link_object: 'Ticket', link_object_value: id) + .find { |l| l['link_type'] == 'parent' && l['link_object'] == 'Ticket' } + &.then { |l| Ticket.find_by(id: l['link_object_value']) } + end +end +``` + +**Pros:** +- Handles the common case (merging bridge ticket into non-bridge ticket) +- Automatic, no agent action required +- Non-destructive (doesn't overwrite existing preferences) + +**Cons:** +- Doesn't handle case where both tickets have different bridge metadata +- May need additional logic for conflicting preferences + +### Option 2: Follow-up Filter for Bridge Channels + +Create filters similar to `FollowUpMerged` that redirect incoming bridge messages: + +```ruby +# Modify webhook controllers to check for merged tickets +def find_active_ticket_for_customer(customer, state_ids) + ticket = Ticket.where(customer_id: customer.id) + .where.not(state_id: state_ids) + .order(:updated_at).first + + # If ticket is merged, follow parent link + if ticket&.state&.state_type&.name == 'merged' + ticket = find_merge_target(ticket) || ticket + end + + ticket +end + +def find_merge_target(ticket) + Link.list(link_object: 'Ticket', link_object_value: ticket.id) + .filter_map do |link| + next if link['link_type'] != 'parent' + next if link['link_object'] != 'Ticket' + + Ticket.joins(state: :state_type) + .where.not(ticket_state_types: { name: 'merged' }) + .find_by(id: link['link_object_value']) + end.first +end +``` + +**Pros:** +- Handles incoming messages to merged tickets correctly +- Follows same pattern as Zammad's email handling + +**Cons:** +- Requires modifying webhook controllers +- Only handles incoming direction, not outgoing + +### Option 3: Copy Preferences on Split + +Modify the split form updater or add a callback to copy bridge preferences: + +```ruby +# Add to ticket creation from split +module Ticket::SplitBridgeChannelPreferences + extend ActiveSupport::Concern + + included do + after_create :copy_bridge_preferences_from_source + end + + private + + def copy_bridge_preferences_from_source + # Find source ticket via link + source_link = Link.list(link_object: 'Ticket', link_object_value: id) + .find { |l| l['link_type'] == 'child' } + return unless source_link + + source_ticket = Ticket.find_by(id: source_link['link_object_value']) + return unless source_ticket + + # Copy bridge preferences + %w[cdr_whatsapp cdr_signal cdr_voice channel_id].each do |key| + next unless source_ticket.preferences[key].present? + self.preferences[key] = source_ticket.preferences[key].deep_dup + end + + save! if changed? + end +end +``` + +### Option 4: UI Warning + Manual Handling + +Add frontend validation to warn agents: + +1. Check for bridge preferences before merge/split +2. Show warning dialog explaining implications +3. Optionally provide UI to manually transfer channel association + +```typescript +// In merge confirmation dialog +const hasBridgeChannel = ticket.preferences?.cdr_whatsapp || + ticket.preferences?.cdr_signal; +if (hasBridgeChannel) { + showWarning( + "This ticket uses WhatsApp/Signal messaging. " + + "Merging may affect message routing. " + + "Replies will be sent to the target ticket's contact." + ); +} +``` + +### Option 5: Multi-Channel Preferences (Long-term) + +Allow tickets to have multiple channel associations: + +```ruby +ticket.preferences = { + bridge_channels: [ + { type: 'cdr_whatsapp', chat_id: '+111...', channel_id: 1, customer_id: 100 }, + { type: 'cdr_whatsapp', chat_id: '+222...', channel_id: 1, customer_id: 101 }, + { type: 'cdr_signal', chat_id: 'group.xxx', channel_id: 2 } + ] +} +``` + +This would require significant refactoring of communication jobs to handle multiple recipients. + +--- + +## Signal Groups - Special Considerations + +Signal groups add complexity: + +1. **Group ID is the routing key**, not phone number +2. **Multiple customers** might be in the same group +3. **`group_joined` flag** tracks invite acceptance - messages can't be sent until true +4. **Group membership changes** could affect ticket routing + +### Merge Rules for Signal Groups + +| Source Ticket | Target Ticket | Recommendation | +|---------------|---------------|----------------| +| Signal group A | No Signal | Copy preferences (Option 1) | +| Signal group A | Signal group A (same) | Safe to merge | +| Signal group A | Signal group B (different) | **Block or warn** - can't merge different group conversations | +| Signal group A | Signal DM | **Block or warn** - different communication modes | + +Consider adding validation: + +```ruby +def validate_signal_group_merge(source, target) + source_group = source.preferences.dig('cdr_signal', 'chat_id') + target_group = target.preferences.dig('cdr_signal', 'chat_id') + + return true if source_group.blank? || target_group.blank? + return true if source_group == target_group + + # Different groups - this is problematic + raise Exceptions::UnprocessableEntity, + "Cannot merge tickets from different Signal groups" +end +``` + +--- + +## Recommended Implementation Path + +### Phase 1: Immediate (Low Risk) + +1. **Add preferences migration on merge** (Option 1) + - Only copies if target doesn't have existing preferences + - Handles most common case safely + +2. **Add preferences copy on split** (Option 3) + - New tickets get parent's channel metadata + - Enables replies on split tickets + +### Phase 2: Short-term + +3. **Add follow-up handling in webhooks** (Option 2) + - Modify webhook controllers to follow merge parent links + - Handles incoming messages to merged ticket's customer + +4. **Add UI warnings** (Option 4) + - Warn agents about implications + - Especially for conflicting metadata scenarios + +### Phase 3: Medium-term + +5. **Add merge validation for Signal groups** + - Block merging tickets from different groups + - Or add clear warning about implications + +6. **Add audit logging** + - Track when preferences are migrated + - Help agents understand what happened + +--- + +## Files to Modify + +### Zammad Addon (zammad-addon-bridge) + +| File | Change | +|------|--------| +| `src/app/models/ticket/merge_bridge_channel_preferences.rb` | New - preferences migration | +| `src/app/models/ticket/split_bridge_channel_preferences.rb` | New - preferences copy on split | +| `src/app/controllers/channels_cdr_whatsapp_controller.rb` | Add merge follow-up handling | +| `src/app/controllers/channels_cdr_signal_controller.rb` | Add merge follow-up handling | +| `src/config/initializers/bridge.rb` | Include new concerns in Ticket model | + +### Link Frontend (optional) + +| File | Change | +|------|--------| +| Merge dialog component | Add warning for bridge tickets | + +--- + +## Testing Scenarios + +1. Merge WhatsApp ticket → empty ticket → verify agent can reply +2. Merge WhatsApp ticket → WhatsApp ticket (same number) → verify routing +3. Merge WhatsApp ticket → WhatsApp ticket (different number) → verify warning/behavior +4. Split article from WhatsApp ticket → verify new ticket has preferences +5. Customer sends message after their ticket was merged → verify routing +6. Merge Signal group ticket → verify group_joined flag is preserved +7. Merge two different Signal group tickets → verify validation/warning + +--- + +## References + +- Zammad merge implementation: `app/models/ticket.rb:330-450` +- Zammad split implementation: `app/models/form_updater/concerns/applies_split_ticket_article.rb` +- Zammad email follow-up filter: `app/models/channel/filter/follow_up_merged.rb` +- Bridge WhatsApp controller: `packages/zammad-addon-bridge/src/app/controllers/channels_cdr_whatsapp_controller.rb` +- Bridge Signal controller: `packages/zammad-addon-bridge/src/app/controllers/channels_cdr_signal_controller.rb` +- Bridge WhatsApp job: `packages/zammad-addon-bridge/src/app/jobs/communicate_cdr_whatsapp_job.rb` +- Bridge Signal job: `packages/zammad-addon-bridge/src/app/jobs/communicate_cdr_signal_job.rb` diff --git a/docs/ticket-field-propagation-design.md b/docs/ticket-field-propagation-design.md new file mode 100644 index 0000000..61d4bec --- /dev/null +++ b/docs/ticket-field-propagation-design.md @@ -0,0 +1,906 @@ +# Ticket Field Propagation System + +## Overview + +A configurable system for copying/syncing fields between related tickets (parent/child, merged, linked). This addresses the bridge channel preferences problem while providing a general-purpose solution for custom fields. + +## Problem Statement + +Zammad creates relationships between tickets through: +- **Split**: Creates child ticket from parent's article +- **Merge**: Source ticket becomes child of target (merged state) +- **Manual linking**: Agents can link tickets as parent/child or related + +Currently, no field values are propagated across these relationships except basic attributes on split. This causes issues when: +- Bridge channel metadata needs to follow the conversation +- Custom fields (account ID, region, priority score) should be inherited +- Parent ticket context should flow to children (or vice versa) + +## Use Cases + +### Use Case 1: Bridge Channel Inheritance (Immediate Need) +When a ticket is split or merged, the bridge channel metadata (`preferences.cdr_whatsapp`, `preferences.cdr_signal`) should be copied so agents can reply via the same channel. + +### Use Case 2: Custom Field Inheritance +Organization uses custom fields like `account_tier`, `region`, `contract_id`. When splitting a ticket, the child should inherit these values. + +### Use Case 3: Escalation Propagation +When a child ticket is escalated (custom `escalation_level` field), the parent should be updated to reflect this. + +### Use Case 4: SLA Context +Parent ticket has SLA deadline. Child tickets should inherit or reference this deadline. + +### Use Case 5: Bulk Operations +When updating a parent ticket's category, optionally cascade to all children. + +--- + +## Design + +### Terminology + +| Term | Definition | +|------|------------| +| **Source** | The ticket providing the field value | +| **Target** | The ticket receiving the field value | +| **Direction** | Which way data flows (parent→child, child→parent, source→target on merge) | +| **Trigger** | The event that initiates propagation (split, merge, update, link_create) | +| **Condition** | When to apply the copy (always, if_empty, if_greater, custom) | +| **Field Path** | Dot-notation path to the field (`preferences.cdr_whatsapp.chat_id`) | + +### Field Types + +The system must handle different field storage mechanisms: + +```ruby +# 1. Standard ticket attributes +ticket.group_id +ticket.priority_id +ticket.organization_id + +# 2. Preferences hash (nested) +ticket.preferences['channel_id'] +ticket.preferences['cdr_whatsapp']['chat_id'] +ticket.preferences['cdr_signal']['group_joined'] + +# 3. Custom object attributes (Zammad ObjectManager) +ticket.custom_account_id # Added via Admin → Objects → Ticket +ticket.custom_region +ticket.custom_escalation_level + +# 4. Tags (special handling) +ticket.tag_list # Array of strings +``` + +### Configuration Schema + +```ruby +# Stored in Setting or dedicated table +TicketFieldPropagation.configure do |config| + + # Define field groups for convenience + config.field_group :bridge_channel, [ + 'preferences.channel_id', + 'preferences.cdr_whatsapp', # Copies entire hash + 'preferences.cdr_signal', + 'preferences.cdr_voice' + ] + + config.field_group :customer_context, [ + 'organization_id', + 'custom_account_id', + 'custom_region', + 'custom_contract_id' + ] + + config.field_group :sla_context, [ + 'custom_sla_deadline', + 'custom_escalation_level' + ] + + # Define propagation rules + + # Bridge preferences: copy to child on split if child doesn't have them + config.rule :bridge_on_split do |r| + r.fields :bridge_channel + r.trigger :split + r.direction :parent_to_child + r.condition :if_target_empty + r.timing :immediate + end + + # Bridge preferences: copy to target on merge if target doesn't have them + config.rule :bridge_on_merge do |r| + r.fields :bridge_channel + r.trigger :merge + r.direction :source_to_target + r.condition :if_target_empty + r.timing :immediate + end + + # Customer context: always copy to child on split + config.rule :customer_context_on_split do |r| + r.fields :customer_context + r.trigger :split + r.direction :parent_to_child + r.condition :always + r.timing :immediate + end + + # Escalation: propagate highest level to parent + config.rule :escalation_to_parent do |r| + r.fields ['custom_escalation_level'] + r.trigger :update + r.direction :child_to_parent + r.condition :if_greater + r.timing :deferred # Use job queue + end + + # Manual sync: allow agent to trigger full sync + config.rule :manual_sync do |r| + r.fields [:customer_context, :sla_context] + r.trigger :manual + r.direction :parent_to_children # All children + r.condition :always + r.timing :immediate + end +end +``` + +### Alternative: JSON Configuration + +For storage in Zammad's `Setting` table: + +```json +{ + "field_groups": { + "bridge_channel": [ + "preferences.channel_id", + "preferences.cdr_whatsapp", + "preferences.cdr_signal" + ], + "customer_context": [ + "organization_id", + "custom_account_id", + "custom_region" + ] + }, + "rules": [ + { + "name": "bridge_on_split", + "fields": ["@bridge_channel"], + "trigger": "split", + "direction": "parent_to_child", + "condition": "if_target_empty", + "enabled": true + }, + { + "name": "bridge_on_merge", + "fields": ["@bridge_channel"], + "trigger": "merge", + "direction": "source_to_target", + "condition": "if_target_empty", + "enabled": true + }, + { + "name": "customer_context_inherit", + "fields": ["@customer_context"], + "trigger": "split", + "direction": "parent_to_child", + "condition": "always", + "enabled": true + } + ] +} +``` + +--- + +## Architecture + +### Components + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ TicketFieldPropagation │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ Configuration│ │ Engine │ │ FieldAccessor │ │ +│ │ │───▶│ │───▶│ │ │ +│ │ - field_groups │ - execute() │ │ - get(path) │ │ +│ │ - rules │ │ - apply_rule │ │ - set(path, val) │ │ +│ │ - load/save │ │ - find_related │ - deep_merge │ │ +│ └──────────────┘ └──────────────┘ └──────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ RelationshipFinder │ │ +│ │ │ │ +│ │ - find_parent(ticket) │ │ +│ │ - find_children(ticket) │ │ +│ │ - find_merge_target(ticket) │ │ +│ │ - find_merge_source(ticket) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Triggers │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────┐ ┌────────────────┐ ┌─────────────────┐ │ +│ │ Ticket Concern │ │ Transaction │ │ Manual API │ │ +│ │ │ │ Observer │ │ Endpoint │ │ +│ │ after_create │ │ │ │ │ │ +│ │ after_update │ │ on merge event │ │ POST /tickets/ │ │ +│ │ after_save │ │ on split event │ │ :id/propagate │ │ +│ └────────────────┘ └────────────────┘ └─────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Class Design + +```ruby +# lib/ticket_field_propagation/configuration.rb +module TicketFieldPropagation + class Configuration + attr_accessor :field_groups, :rules + + def self.load + # Load from Setting table or YAML + end + + def field_group(name, fields) + @field_groups[name] = fields + end + + def rule(name, &block) + rule = Rule.new(name) + block.call(rule) + @rules << rule + end + + def expand_fields(field_refs) + # Expand @group_name references to actual field list + field_refs.flat_map do |ref| + if ref.start_with?('@') + @field_groups[ref[1..].to_sym] || [] + else + [ref] + end + end + end + end + + class Rule + attr_accessor :name, :fields, :trigger, :direction, :condition, :timing + + def initialize(name) + @name = name + @timing = :immediate + @condition = :always + end + + def applies_to?(event_type) + @trigger == event_type || (@trigger.is_a?(Array) && @trigger.include?(event_type)) + end + end +end +``` + +```ruby +# lib/ticket_field_propagation/engine.rb +module TicketFieldPropagation + class Engine + def initialize(source_ticket, event_type, target_ticket: nil) + @source = source_ticket + @event = event_type + @explicit_target = target_ticket + @config = Configuration.load + end + + def execute + applicable_rules.each do |rule| + if rule.timing == :deferred + PropagationJob.perform_later(@source.id, rule.name) + else + apply_rule(rule) + end + end + end + + private + + def applicable_rules + @config.rules.select { |r| r.applies_to?(@event) && r.enabled } + end + + def apply_rule(rule) + targets = find_targets(rule.direction) + fields = @config.expand_fields(rule.fields) + + targets.each do |target| + source = determine_source(rule.direction, target) + PropagationResult.log(@source, target, rule) + + fields.each do |field_path| + copy_field(source, target, field_path, rule.condition) + end + + target.save! if target.changed? + end + end + + def find_targets(direction) + case direction + when :parent_to_child, :parent_to_children + RelationshipFinder.find_children(@source) + when :child_to_parent + [RelationshipFinder.find_parent(@source)].compact + when :source_to_target + [@explicit_target || RelationshipFinder.find_merge_target(@source)].compact + else + [] + end + end + + def determine_source(direction, target) + case direction + when :parent_to_child, :parent_to_children, :source_to_target + @source + when :child_to_parent + target # We're copying FROM child TO parent, so target is source here + # Wait, this is confusing. Let me reconsider... + @source # The ticket that triggered the event is the source + end + end + + def copy_field(source, target, field_path, condition) + source_value = FieldAccessor.get(source, field_path) + return if source_value.nil? + + target_value = FieldAccessor.get(target, field_path) + + case condition + when :if_target_empty + return if target_value.present? + when :if_greater + return if target_value.present? && target_value >= source_value + when :always + # proceed + end + + FieldAccessor.set(target, field_path, source_value) + end + end +end +``` + +```ruby +# lib/ticket_field_propagation/field_accessor.rb +module TicketFieldPropagation + class FieldAccessor + class << self + def get(ticket, field_path) + parts = field_path.split('.') + + value = ticket + parts.each do |part| + value = access_part(value, part) + return nil if value.nil? + end + + # Deep dup hashes to prevent mutation + value.is_a?(Hash) ? value.deep_dup : value + end + + def set(ticket, field_path, value) + parts = field_path.split('.') + + if parts.length == 1 + # Direct attribute + set_attribute(ticket, parts[0], value) + else + # Nested in preferences or similar + set_nested(ticket, parts, value) + end + end + + private + + def access_part(object, part) + if object.is_a?(Hash) + object[part] || object[part.to_sym] + elsif object.respond_to?(part) + object.send(part) + elsif object.respond_to?(:[]) + object[part] + else + nil + end + end + + def set_attribute(ticket, attr_name, value) + if ticket.respond_to?("#{attr_name}=") + ticket.send("#{attr_name}=", value) + else + raise ArgumentError, "Unknown attribute: #{attr_name}" + end + end + + def set_nested(ticket, parts, value) + # e.g., ['preferences', 'cdr_whatsapp'] + root = parts[0] + + if root == 'preferences' + ticket.preferences ||= {} + set_hash_path(ticket.preferences, parts[1..], value) + else + raise ArgumentError, "Unsupported nested path root: #{root}" + end + end + + def set_hash_path(hash, remaining_parts, value) + if remaining_parts.length == 1 + key = remaining_parts[0] + if value.is_a?(Hash) && hash[key].is_a?(Hash) + # Deep merge for hash values + hash[key] = hash[key].deep_merge(value) + else + hash[key] = value + end + else + key = remaining_parts[0] + hash[key] ||= {} + set_hash_path(hash[key], remaining_parts[1..], value) + end + end + end + end +end +``` + +```ruby +# lib/ticket_field_propagation/relationship_finder.rb +module TicketFieldPropagation + class RelationshipFinder + class << self + def find_parent(ticket) + # In Zammad links: parent ticket has link_type 'child' pointing to it + # Wait, need to verify Zammad's link semantics... + # + # From merge: source ticket gets a 'parent' link pointing TO target + # Link.add(link_type: 'parent', source: target_id, target: source_id) + # + # So to find parent of a ticket, look for 'parent' links where + # this ticket is the target (link_object_target_value) + + links = Link.list( + link_object: 'Ticket', + link_object_value: ticket.id + ) + + parent_link = links.find { |l| l['link_type'] == 'parent' } + return nil unless parent_link + + Ticket.find_by(id: parent_link['link_object_value']) + end + + def find_children(ticket) + links = Link.list( + link_object: 'Ticket', + link_object_value: ticket.id + ) + + child_links = links.select { |l| l['link_type'] == 'child' } + child_ids = child_links.map { |l| l['link_object_value'] } + + Ticket.where(id: child_ids).to_a + end + + def find_merge_target(ticket) + # Merged ticket has 'parent' link to target + return nil unless ticket.state.state_type.name == 'merged' + find_parent(ticket) + end + + def find_merge_sources(ticket) + # Find tickets that were merged into this one + links = Link.list( + link_object: 'Ticket', + link_object_value: ticket.id + ) + + # Look for child links where the child is in merged state + child_links = links.select { |l| l['link_type'] == 'child' } + + child_links.filter_map do |link| + child = Ticket.find_by(id: link['link_object_value']) + child if child&.state&.state_type&.name == 'merged' + end + end + end + end +end +``` + +### Integration Points + +#### 1. Ticket Concern (for create/update triggers) + +```ruby +# app/models/ticket/field_propagation.rb +module Ticket::FieldPropagation + extend ActiveSupport::Concern + + included do + after_create :trigger_propagation_on_create + after_update :trigger_propagation_on_update + end + + private + + def trigger_propagation_on_create + # Check if this is a split (has parent link created simultaneously) + # This is tricky because link might be created after ticket... + # May need to hook into Link.add instead + end + + def trigger_propagation_on_update + return unless saved_change_to_attribute?(:state_id) + + if state.state_type.name == 'merged' + TicketFieldPropagation::Engine.new(self, :merge).execute + end + end +end +``` + +#### 2. Transaction Observer (for merge/split events) + +```ruby +# app/models/transaction/ticket_field_propagation.rb +class Transaction::TicketFieldPropagation + def self.execute(object, type, _changes, user_id, _options) + return unless object.is_a?(Ticket) + + case type + when 'update.merged_into' + # Source ticket was merged - propagate to target + target = TicketFieldPropagation::RelationshipFinder.find_merge_target(object) + TicketFieldPropagation::Engine.new(object, :merge, target_ticket: target).execute + + when 'update.received_merge' + # Target ticket received a merge - could trigger reverse propagation if needed + + when 'create' + # Check if this is from a split (check for immediate parent link) + parent = TicketFieldPropagation::RelationshipFinder.find_parent(object) + if parent.present? + TicketFieldPropagation::Engine.new(parent, :split, target_ticket: object).execute + end + end + end +end +``` + +#### 3. Manual API Endpoint + +```ruby +# app/controllers/ticket_field_propagation_controller.rb +class TicketFieldPropagationController < ApplicationController + before_action :authenticate_and_authorize + + # POST /api/v1/tickets/:id/propagate + def propagate + ticket = Ticket.find(params[:id]) + direction = params[:direction] || 'to_children' + fields = params[:fields] || 'all' + + case direction + when 'to_children' + engine = TicketFieldPropagation::Engine.new(ticket, :manual) + engine.execute_for_fields(fields, direction: :parent_to_children) + when 'from_parent' + parent = TicketFieldPropagation::RelationshipFinder.find_parent(ticket) + return render json: { error: 'No parent ticket' }, status: :not_found unless parent + + engine = TicketFieldPropagation::Engine.new(parent, :manual, target_ticket: ticket) + engine.execute_for_fields(fields, direction: :parent_to_child) + end + + render json: { success: true } + end + + # GET /api/v1/tickets/:id/propagation_preview + def preview + # Show what would be copied without doing it + end +end +``` + +--- + +## Handling Edge Cases + +### 1. Circular Reference Prevention + +```ruby +class Engine + MAX_DEPTH = 5 + + def execute(depth: 0) + return if depth >= MAX_DEPTH + + # Track processed tickets in this chain + Thread.current[:propagation_chain] ||= Set.new + return if Thread.current[:propagation_chain].include?(@source.id) + + Thread.current[:propagation_chain].add(@source.id) + + begin + # ... execute rules + ensure + Thread.current[:propagation_chain].delete(@source.id) + end + end +end +``` + +### 2. Conflicting Values on Merge + +When both source and target have values, the default is "don't overwrite" (`if_target_empty`). But we could support strategies: + +```ruby +config.rule :merge_preferences do |r| + r.fields ['preferences.cdr_whatsapp'] + r.trigger :merge + r.direction :source_to_target + r.condition :merge_hash # Deep merge instead of replace +end +``` + +Or with explicit conflict resolution: + +```ruby +r.on_conflict do |source_val, target_val, field| + case field + when /escalation/ + [source_val, target_val].max + when /preferences\.cdr_/ + target_val.presence || source_val # Keep target if present + else + source_val # Default: source wins + end +end +``` + +### 3. Multiple Bridge Channels + +If source has WhatsApp and target has Signal, we might want both: + +```ruby +# Current behavior with if_target_empty: +# - Source: {cdr_whatsapp: {...}} +# - Target: {cdr_signal: {...}} +# - Result: Target keeps cdr_signal, gains cdr_whatsapp (both present) + +# This works because we check per-field, not per-category +``` + +### 4. Signal Group Merge Validation + +Special case: don't allow merging tickets from different Signal groups: + +```ruby +config.rule :validate_signal_merge do |r| + r.trigger :merge + r.validator ->(source, target) { + source_group = source.preferences.dig('cdr_signal', 'chat_id') + target_group = target.preferences.dig('cdr_signal', 'chat_id') + + # OK if either doesn't have signal, or same group + return true if source_group.blank? || target_group.blank? + return true if source_group == target_group + + # Different groups - block the merge + raise Exceptions::UnprocessableEntity, + "Cannot merge tickets from different Signal groups" + } +end +``` + +--- + +## Audit Trail + +Track what was propagated for debugging and transparency: + +```ruby +# app/models/ticket_field_propagation_log.rb +class TicketFieldPropagationLog < ApplicationRecord + belongs_to :source_ticket, class_name: 'Ticket' + belongs_to :target_ticket, class_name: 'Ticket' + + # Columns: + # - source_ticket_id + # - target_ticket_id + # - rule_name + # - field_path + # - old_value (serialized) + # - new_value (serialized) + # - trigger_event + # - created_by_id + # - created_at +end +``` + +Or simpler: add to ticket history: + +```ruby +target_ticket.history_log( + 'field_propagated', + UserInfo.current_user_id, + value_from: source_ticket.id, + value_to: { field: field_path, value: new_value.to_s.truncate(100) } +) +``` + +--- + +## Configuration UI (Future) + +Admin interface at Settings → Ticket → Field Propagation: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Field Propagation Rules [+Add]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ [✓] Bridge Channel on Split [Edit] │ │ +│ │ Copy: preferences.cdr_whatsapp, preferences.cdr_signal │ │ +│ │ When: Ticket is split │ │ +│ │ Direction: Parent → Child │ │ +│ │ Condition: Only if child field is empty │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ [✓] Bridge Channel on Merge [Edit] │ │ +│ │ Copy: preferences.cdr_whatsapp, preferences.cdr_signal │ │ +│ │ When: Ticket is merged │ │ +│ │ Direction: Source → Target │ │ +│ │ Condition: Only if target field is empty │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ [ ] Customer Context Inheritance [Edit] │ │ +│ │ Copy: organization_id, custom_account_id, custom_region │ │ +│ │ When: Ticket is split │ │ +│ │ Direction: Parent → Child │ │ +│ │ Condition: Always │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Default Configuration + +Out-of-the-box settings that solve the bridge preferences problem: + +```json +{ + "field_groups": { + "bridge_channel": [ + "preferences.channel_id", + "preferences.cdr_whatsapp", + "preferences.cdr_signal", + "preferences.cdr_voice" + ] + }, + "rules": [ + { + "name": "bridge_on_split", + "description": "Copy bridge channel info when splitting tickets", + "fields": ["@bridge_channel"], + "trigger": "split", + "direction": "parent_to_child", + "condition": "if_target_empty", + "enabled": true + }, + { + "name": "bridge_on_merge", + "description": "Copy bridge channel info when merging tickets", + "fields": ["@bridge_channel"], + "trigger": "merge", + "direction": "source_to_target", + "condition": "if_target_empty", + "enabled": true + } + ] +} +``` + +--- + +## Implementation Phases + +### Phase 1: Core Engine (Solves Bridge Problem) +- FieldAccessor with dot-notation support +- RelationshipFinder for parent/child/merge relationships +- Engine with basic rule processing +- Hardcoded rules for bridge channel propagation +- Integration with Ticket merge (via concern or observer) + +### Phase 2: Configuration System +- JSON configuration in Setting table +- Field groups support +- Multiple condition types (if_empty, always, if_greater) +- Deferred execution via jobs + +### Phase 3: Split Integration +- Hook into ticket split workflow +- Detect parent relationship after split +- Apply split rules + +### Phase 4: Manual Triggers +- API endpoint for manual propagation +- Preview endpoint +- Audit logging + +### Phase 5: Admin UI +- Configuration interface in Zammad admin +- Visual rule builder +- Field picker for custom object attributes + +### Phase 6: Advanced Features +- Bidirectional sync +- Conflict resolution strategies +- Cascading updates +- Validation rules (like Signal group merge prevention) + +--- + +## Files to Create + +``` +packages/zammad-addon-bridge/src/ +├── lib/ +│ └── ticket_field_propagation/ +│ ├── configuration.rb +│ ├── engine.rb +│ ├── field_accessor.rb +│ ├── relationship_finder.rb +│ └── propagation_job.rb +├── app/ +│ ├── models/ +│ │ └── ticket/ +│ │ └── field_propagation.rb # Concern +│ └── controllers/ +│ └── ticket_field_propagation_controller.rb +├── config/ +│ └── initializers/ +│ └── ticket_field_propagation.rb # Default config & include concern +└── db/ + └── seeds/ + └── field_propagation_settings.rb +``` + +--- + +## Relationship to Bridge Preferences Problem + +The bridge preferences problem from the previous investigation is solved by: + +1. **Default rule `bridge_on_merge`**: Copies `preferences.cdr_whatsapp` and `preferences.cdr_signal` from source to target when tickets are merged, if target doesn't already have them. + +2. **Default rule `bridge_on_split`**: Copies the same preferences from parent to child when tickets are split. + +3. **Extensibility**: Additional custom fields can be added to propagation rules without code changes. + +This makes the field propagation system a superset solution that handles the immediate bridge problem while providing a framework for future field synchronization needs.