ABS-Odoo Integration Pattern: No Custom Fields Required¶

Integration Pattern Overview¶

Core Principle: Clean Integration with Zero Odoo Customization¶

No custom fields added to Odoo models
Semantic mapping using existing Odoo fields only
MQTT-based synchronization for real-time updates
Standard Odoo subscription workflow preserved

Three-Phase Integration Pattern¶

Product Template Creation: ABS → Odoo (ABS leads)
Subscription Creation: Odoo → ABS (Odoo leads)
Payment Synchronization: Odoo → ABS (MQTT-based updates)

Entity Relationship¶

ABS ServicePlanTemplate ≡ Odoo Product Template (catalog level)
ABS ServicePlan ≡ Odoo Subscription (customer instance level)

Phase 1: Product Template Creation (ABS → Odoo)¶

ABS ServicePlanTemplate → Odoo Product Template Creation¶

{
  "_comment_product_creation_flow": "ABS creates ServicePlanTemplate, then pushes to Odoo",
  "integration_flow": {
    "step_1": "ABS creates ServicePlanTemplate with business logic",
    "step_2": "ABS publishes MQTT: emit/ABS/product_template/{template_id}/created",
    "step_3": "Odoo integration service receives MQTT and creates product template",
    "step_4": "Odoo uses ABS template_id as product default_code"
  },

  "semantic_mapping": {
    "abs_template_id": "product.template.default_code",
    "name": "product.template.name",
    "description": "product.template.description_sale",
    "billing_currency": "product.template.currency_id",
    "status": "product.template.active"
  },

  "product_naming_convention": {
    "format": "[service]-[duration]-[location]",
    "example": "BSS-Monthly-Nairobi",
    "alignment": "User memory: Product Structure and Naming Convention"
  }
}

CommonTerms → Subscription Template Configuration¶

Following user memory "Semantic Mapping Source":

{
  "_comment_subscription_template": "CommonTerms provide subscription configuration",
  "billing_terms_mapping": {
    "billing_cycle": "MONTHLY → recurring_rule_type: monthly",
    "service_duration_days": "30 → recurring_interval: 1",
    "monthly_fee": "list_price for subscription product",
    "deposit_amount": "separate deposit product if needed"
  }
}

Phase 2: Subscription Creation (Odoo → ABS)¶

Odoo Subscription → ABS ServicePlan Creation¶

{
  "_comment_subscription_creation_flow": "Odoo creates subscription, ABS follows",
  "integration_flow": {
    "step_1": "Customer signs up in Odoo and creates subscription",
    "step_2": "Odoo publishes MQTT: emit/Odoo/subscription/{subscription_id}/created",
    "step_3": "ABS MQTT listener receives subscription creation event",
    "step_4": "ABS creates ServicePlan with Odoo subscription_id as link",
    "step_5": "ABS copies all payment and terms fields from Odoo subscription"
  },

  "mqtt_payload_structure": {
    "topic": "emit/Odoo/subscription/{subscription_id}/created",
    "payload": {
      "subscription_id": "odoo_subscription.id",
      "partner_id": "customer_id",
      "template_id": "product.template.default_code (ABS template_id)",
      "recurring_rule_type": "monthly",
      "recurring_interval": 1,
      "currency_id": "KES",
      "amount_total": 0.0,
      "start_date": "2025-01-15",
      "state": "in_progress"
    }
  },

  "abs_serviceplan_creation": {
    "customer_id": "payload.partner_id",
    "template_id": "payload.template_id (ABS template reference)",
    "odoo_subscription_id": "payload.subscription_id (linking mechanism)",
    "service_state": "ACTIVE (derived from Odoo state)",
    "payment_state": "CURRENT (derived from Odoo payment status)",
    "billing_currency": "payload.currency_id"
  }
}

Phase 3: Payment Synchronization (Odoo → ABS via MQTT)¶

ServiceAgent.syncOdooSubscription Method¶

{
  "_comment_payment_sync_flow": "Odoo payment events trigger ABS updates",
  "integration_flow": {
    "step_1": "Odoo processes payment transaction (invoice, payment, etc.)",
    "step_2": "Odoo publishes MQTT: emit/Odoo/subscription/{subscription_id}/payment_updated",
    "step_3": "ABS MQTT listener routes to serviceAgent.syncOdooSubscription",
    "step_4": "ABS updates ServicePlan payment fields based on semantic mapping"
  },

  "mqtt_topic_patterns": {
    "payment_events": "emit/Odoo/subscription/{subscription_id}/payment_updated",
    "state_changes": "emit/Odoo/subscription/{subscription_id}/state_changed",
    "billing_events": "emit/Odoo/subscription/{subscription_id}/invoice_created",
    "alignment": "User memory: MQTT Topic Subscription Patterns"
  },

  "serviceAgent_method": {
    "function_name": "syncOdooSubscription",
    "purpose": "Update BSS agent_state with Odoo subscription data",
    "input": "ABSEnvelope with Odoo subscription payload",
    "agent_state_updates": {
      "odoo_subscription_id": "payload.subscription_id",
      "odoo_last_sync_at": "current_timestamp",
      "odoo_payment_state": "payload.payment_state",
      "odoo_subscription_state": "payload.state",
      "odoo_currency_id": "payload.currency_id",
      "odoo_amount_total": "payload.amount_total"
    },
    "state_management": "Uses existing AgentStateManager.update() for validation",
    "domain_isolation": "Odoo data stays within BSS agent_state, no schema pollution"
  }
}

State Mapping Tables¶

{
  "_comment_state_mappings": "Semantic mapping between Odoo and ABS states",
  "subscription_state_mapping": {
    "draft": "SERVICE_INITIAL",
    "in_progress": "SERVICE_ACTIVE",
    "to_renew": "SERVICE_RENEWAL_DUE",
    "closed": "SERVICE_CLOSED",
    "cancel": "SERVICE_CANCELLED"
  },

  "payment_state_mapping": {
    "not_paid": "PAYMENT_PENDING",
    "in_payment": "PAYMENT_PROCESSING",
    "paid": "PAYMENT_CURRENT",
    "partial": "PAYMENT_PARTIAL",
    "reversed": "PAYMENT_REVERSED",
    "cancel": "PAYMENT_CANCELLED"
  }
}

Implementation Architecture¶

Zero Custom Fields Approach¶

{
  "_comment_no_custom_fields": "Clean integration using only standard Odoo fields",
  "linking_mechanism": {
    "product_level": "ABS template_id stored as Odoo product.default_code",
    "subscription_level": "Odoo subscription.id stored as ABS ServicePlan.odoo_subscription_id",
    "no_custom_odoo_fields": "Zero modifications to Odoo data model"
  },

  "integration_layers": {
    "layer_1": "MQTT messaging for event-driven synchronization",
    "layer_2": "Semantic field mapping using existing Odoo fields only",
    "layer_3": "ServiceAgent methods for subscription synchronization",
    "layer_4": "Existing ABS MQTT listener infrastructure"
  }
}

Minimal ABS Schema Changes¶

{
  "_comment_abs_changes": "ZERO ServicePlan schema changes - Odoo data in agent_state",
  "serviceplan_changes": "NONE - agent_state: JSON already supports Odoo integration",
  "agent_state_structure": {
    "existing_bss_fields": {
      "agent_version": "2.0.0",
      "swaps_today": 0,
      "suspended_until": null,
      "last_activity": "2025-01-15T10:00:00Z",
      "execution_count": 0
    },
    "new_odoo_integration_fields": {
      "odoo_subscription_id": 12345,
      "odoo_last_sync_at": "2025-01-15T10:00:00Z",
      "odoo_payment_state": "paid",
      "odoo_subscription_state": "in_progress"
    }
  },
  "benefits": {
    "no_schema_pollution": "Core ServicePlan remains clean",
    "agent_specific": "Only BSS agent deals with Odoo, other agents unaffected",
    "existing_infrastructure": "Leverages existing AgentStateManager validation",
    "domain_isolation": "Odoo integration confined to BSS agent domain"
  }
}

MQTT Integration Flow¶

Phase 1: ABS Template Creation
  ABS ServicePlanTemplate Created → 
  MQTT: emit/ABS/product_template/{template_id}/created →
  Odoo Product Template Created

Phase 2: Odoo Subscription Creation  
  Odoo Subscription Created →
  MQTT: emit/Odoo/subscription/{subscription_id}/created →
  ABS ServicePlan Created

Phase 3: Payment Synchronization
  Odoo Payment Event →
  MQTT: emit/Odoo/subscription/{subscription_id}/payment_updated →
  serviceAgent.syncOdooSubscription →
  ABS ServicePlan Updated

Benefits of Zero-Custom-Fields Pattern¶

✅ No Odoo Customization Required¶

Zero custom fields added to Odoo models
Standard Odoo workflow completely preserved
Upgrade compatibility maintained for Odoo versions
Minimal Odoo configuration required

✅ Clean Integration Architecture¶

ABS leads product definition - business logic ownership
Odoo leads customer relationships - CRM ownership
MQTT-based event synchronization - real-time updates
Semantic field mapping - no data structure changes

✅ Clean Domain Isolation¶

Core ServicePlan: Remains completely unchanged
BSS agent_state: Contains all Odoo-specific integration data
Other agents: Completely unaffected by Odoo integration
Schema purity: No Odoo concepts leak into core ABS schema

✅ Leverages Existing Infrastructure¶

AgentStateManager: Already handles state validation and updates
BSSAgentState interface: Already defined with proper TypeScript types
JSON @domainSpecific: Already designed for agent-specific data
agent_state pattern: Already established and working

✅ Perfect Architectural Alignment¶

Model confinement: Odoo data confined to BSS agent domain
No schema pollution: Core ABS types remain clean
Agent autonomy: BSS agent manages its own Odoo integration concerns
Domain boundaries: Clear separation between core platform and integration logic

✅ Aligns with User Memories¶

Product naming convention: BSS-Monthly-Nairobi format preserved
MQTT topic patterns: emit/+/BSS/+/+ and emit/Odoo/+/+/+ supported
Payment boundaries: "Customers pay on Odoo, services delivered by ABS"
Integration principles: Clean abstraction with clear responsibility transfer
BSS architecture: Payment processing by Odoo, service delivery by ABS

✅ Implementation Benefits¶

Low risk: No Odoo data model changes
High reuse: Leverages 95% of existing ABS architecture
Scalable: Standard MQTT patterns for future integrations
Maintainable: Clean separation of business logic ownership

Cost Analysis¶

ABS Changes Required¶

ServicePlan: ZERO schema changes (agent_state: JSON already supports this)
BSS Agent: +1 method (syncOdooSubscription) using existing AgentStateManager
BSSAgentState: +4 fields within existing agent_state JSON structure
Core Platform: Completely unchanged

Odoo Changes Required¶

Zero data model changes
MQTT publishing for subscription events (standard integration)
Product template creation via API (standard Odoo capability)

Integration Effort¶

Phase 1: Product template sync (low complexity)
Phase 2: Subscription creation sync (medium complexity)
Phase 3: Payment synchronization (medium complexity)
Total: 3 phases, incremental deployment possible

This approach achieves full Odoo-ABS integration with absolute minimal changes to both systems while maintaining clean architectural boundaries and leveraging existing infrastructure.