bmc_hub/docs/ORDER_CASE_INTEGRATION.md

Order-Case Integration Model

Principle

Orders are transactional satellites that orbit cases. They exist independently but gain process context through relations.

Architecture

Order Table (Future - Not in Sag Module)

CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    order_number VARCHAR(50) UNIQUE NOT NULL,
    customer_id INT NOT NULL,
    total_amount DECIMAL(10,2),
    status VARCHAR(50), -- 'draft', 'sent', 'paid', etc.
    created_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP
);

Integration via Relations

When an Order is created from a Case:

1. Create Order independently

order = create_order({
    'customer_id': 123,
    'total_amount': 1500.00
})

2. Create relation to Case

create_relation({
    'kilde_sag_id': case_id,
    'målsag_id': None,  # Relations can point to other entities
    'relationstype': 'ordre',
    'metadata': {'order_id': order.id}
})

Valid Use Cases

✅ Scenario 1: Case Leads to Order

1. Customer opens case: "Need new server"
2. Tech works case, adds tags: ['hardware', 'quote_needed']
3. Salesperson closes tag 'quote_needed' by creating Order
4. Relation created: Case → Order (relationstype='ordre_oprettet')
5. Case continues with tag 'installation'
6. When installed, case closed

Result: Order exists, Case tracks the work process.

✅ Scenario 2: Order Triggers Case

1. Order created by salesperson
2. System auto-creates Case: "Deliver order #1234"
3. Relation created: Order → Case (relationstype='leverance')
4. Case gets tags: ['pick_items', 'ship', 'install']
5. Each tag closed as work progresses
6. Case closed when complete

Result: Order is transaction, Case is the delivery process.

✅ Scenario 3: Multiple Cases per Order

1. Large order for multiple items
2. Each item gets its own Case:
   • Case A: "Install firewall" (relation to Order)
   • Case B: "Configure switches" (relation to Order)
   • Case C: "Setup monitoring" (relation to Order)
3. Each Case has independent lifecycle with tags
4. Order tracks payment/billing
5. Cases track work processes

Result: One transactional Order, three process Cases.

Anti-Patterns (DO NOT)

❌ Anti-Pattern 1: Embedding Process in Order

# WRONG - Order should NOT have workflow state
order.status = 'awaiting_installation'  # This belongs in a Case tag!

Fix: Create Case with tag 'installation', link to Order.

❌ Anti-Pattern 2: Making Order Replace Case

# WRONG - Don't create Order instead of Case
order = Order(description="Fix customer server")

Fix: Create Case, optionally link to Order if billing needed.

❌ Anti-Pattern 3: Storing Case ID in Order

# WRONG - Don't embed references
order.case_id = 42

Fix: Use Relations table to link Order ↔ Case.

Implementation Guidelines

When to Create Order

• Customer needs invoice/quote
• Financial transaction required
• External system (e-conomic) integration needed
• Legal/accounting documentation

When to Create Case

• Work needs to be tracked
• Workflow has multiple steps
• Tags represent responsibilities
• Multiple people involved
• Need audit trail of process

When to Create Both

• Order for billing + Case for work process
• Link them via Relation

Database Schema Addition

To support Order-Case links, add metadata to relations:

ALTER TABLE sag_relationer 
ADD COLUMN metadata JSONB DEFAULT '{}';

-- Example usage:
INSERT INTO sag_relationer (kilde_sag_id, målsag_id, relationstype, metadata)
VALUES (42, NULL, 'ordre', '{"order_id": 1234, "order_number": "ORD-2025-001"}');

This allows relations to point to external entities (Orders) while keeping the Case model clean.

API Contract

Create Order from Case

POST /api/v1/cases/{case_id}/orders
{
  "customer_id": 123,
  "total_amount": 1500.00,
  "description": "Server upgrade"
}

Response:
{
  "order_id": 1234,
  "order_number": "ORD-2025-001",
  "relation_id": 56  // Auto-created relation
}

List Orders for Case

GET /api/v1/cases/{case_id}/orders

Response:
[
  {
    "order_id": 1234,
    "order_number": "ORD-2025-001",
    "status": "sent",
    "total_amount": 1500.00
  }
]

Create Case from Order

POST /api/v1/orders/{order_id}/cases
{
  "titel": "Deliver order ORD-2025-001",
  "tags": ["pick_items", "ship", "install"]
}

Response:
{
  "case_id": 87,
  "relation_id": 57  // Auto-created relation
}

Summary

Remember:

• Orders = Transactions (billing, invoices, quotes)
• Cases = Processes (work, workflow, responsibilities)
• Relations = Links (give meaning to both)

Never:

• Put process in Order
• Put transaction in Case
• Create hard references between entities

Always:

• Use Relations to link
• Keep entities independent
• Let UI derive the connections