bmc_hub/docs/ECONOMIC_WRITE_MODE.md

e-conomic Write Mode Guide

Overview

Time Tracking modulet kan eksportere godkendte tidsregistreringer til e-conomic som draft orders.

Safety-first approach: Der er TWO lag af sikkerhedsflag for at beskytte mod utilsigtede ændringer.

Safety Flags

Layer 1: Read-Only Mode (BLOCKING)

TIMETRACKING_ECONOMIC_READ_ONLY=true  # Bloker ALLE skrivninger

Når READ_ONLY=true:

• Alle write operationer blokeres 100%
• Logger: 🚫 BLOCKED: Export order X to e-conomic - READ_ONLY mode enabled
• API returnerer fejl med instruktion om at disable flag

Layer 2: Dry-Run Mode (SIMULATION)

TIMETRACKING_ECONOMIC_DRY_RUN=true  # Log men send ikke

Når DRY_RUN=true:

• Write operationer simuleres
• Logger detaljeret payload der VILLE blive sendt
• API returnerer success men med dry_run: true flag
• INGEN data sendes til e-conomic

Production Mode (LIVE WRITES)

TIMETRACKING_ECONOMIC_READ_ONLY=false
TIMETRACKING_ECONOMIC_DRY_RUN=false

Når BEGGE flags er false:

• ⚠️ REELLE skrivninger til e-conomic
• Logger: ⚠️ EXECUTING WRITE OPERATION: Export order X
• Kræver også gyldig economic_customer_number på kunde

Activation Steps

1. Verify e-conomic Credentials

# In .env file
ECONOMIC_API_URL=https://restapi.e-conomic.com
ECONOMIC_APP_SECRET_TOKEN=<your_token>
ECONOMIC_AGREEMENT_GRANT_TOKEN=<your_token>

Test connection:

curl http://localhost:8001/api/v1/timetracking/economic/test

Expected response:

{
  "status": "connected",
  "read_only": true,
  "dry_run": true
}

2. Ensure Customers Have e-conomic Numbers

Alle kunder SKAL have economic_customer_number for at kunne eksporteres:

-- Check customers without e-conomic number
SELECT id, name, vtiger_id 
FROM tmodule_customers 
WHERE economic_customer_number IS NULL;

e-conomic customer number synces automatisk fra vTiger cf_854 felt.

Fix missing numbers:

1. Opdater vTiger med e-conomic customer number i cf_854 felt
2. Kør sync: POST /api/v1/timetracking/sync/customers
3. Verify: GET /api/v1/timetracking/customers

3. Test with Dry-Run Mode

Step 3.1: Disable READ_ONLY (men behold DRY_RUN)

# In .env
TIMETRACKING_ECONOMIC_READ_ONLY=false  # ⚠️ Allow operations
TIMETRACKING_ECONOMIC_DRY_RUN=true     # ✅ Still safe - no real writes

Restart API:

docker-compose restart api

Step 3.2: Generate test order

# Get approved entries for a customer
curl http://localhost:8001/api/v1/timetracking/wizard/next

# Approve entry
curl -X POST http://localhost:8001/api/v1/timetracking/wizard/approve/123

# Generate order
curl -X POST http://localhost:8001/api/v1/timetracking/orders/generate \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 1}'

Step 3.3: Test export (dry-run)

curl -X POST http://localhost:8001/api/v1/timetracking/orders/1/export \
  -H "Content-Type: application/json" \
  -d '{}'

Expected response:

{
  "success": true,
  "dry_run": true,
  "order_id": 1,
  "economic_draft_id": null,
  "message": "DRY-RUN: Would export order ORD-2024-001 to e-conomic",
  "details": {
    "order_number": "ORD-2024-001",
    "customer_name": "Test Customer",
    "total_amount": 425.0,
    "line_count": 1,
    "read_only": false,
    "dry_run": true
  }
}

Check logs for payload details:

docker-compose logs api | grep "📤 Sending to e-conomic"

4. Enable Production Mode (LIVE WRITES)

⚠️ CRITICAL: Only proceed if dry-run tests succeeded!

Step 4.1: Disable DRY_RUN

# In .env
TIMETRACKING_ECONOMIC_READ_ONLY=false  # ⚠️ Writes enabled
TIMETRACKING_ECONOMIC_DRY_RUN=false    # ⚠️⚠️ REAL WRITES TO PRODUCTION!

Step 4.2: Restart API

docker-compose restart api

Step 4.3: Export ONE test order

curl -X POST http://localhost:8001/api/v1/timetracking/orders/1/export \
  -H "Content-Type: application/json" \
  -d '{}'

Expected response (success):

{
  "success": true,
  "dry_run": false,
  "order_id": 1,
  "economic_draft_id": 12345,
  "economic_order_number": "12345",
  "message": "Successfully exported to e-conomic draft 12345",
  "details": {
    "draftOrderNumber": 12345,
    ...
  }
}

Step 4.4: Verify in e-conomic

• Login to e-conomic
• Go to Sales → Draft Orders
• Find order number 12345
• Verify customer, lines, amounts

Error Handling

Missing Customer Number

{
  "status_code": 400,
  "detail": "Customer ABC has no e-conomic customer number"
}

Fix: Sync customer data from vTiger (ensure cf_854 is populated).

e-conomic API Error

{
  "status_code": 400,
  "detail": "e-conomic API error: customer.customerNumber: Customer not found"
}

Fix: Verify customer exists in e-conomic with correct number.

Network/Timeout Error

{
  "status_code": 500,
  "detail": "Internal error: Timeout connecting to e-conomic"
}

Fix: Check network, verify ECONOMIC_API_URL is correct.

Audit Trail

All export operations are logged to tmodule_sync_log:

SELECT * FROM tmodule_sync_log 
WHERE event_type = 'export_completed' 
ORDER BY created_at DESC 
LIMIT 10;

Fields tracked:

• order_id - Which order was exported
• economic_draft_id - Draft order number in e-conomic
• economic_order_number - Order number in e-conomic
• dry_run - Whether it was a simulation
• created_by - User ID who triggered export
• created_at - Timestamp

Rollback Plan

If issues occur in production:

Step 1: Immediately re-enable safety flags

TIMETRACKING_ECONOMIC_READ_ONLY=true
TIMETRACKING_ECONOMIC_DRY_RUN=true
docker-compose restart api

Step 2: Review audit log

SELECT * FROM tmodule_sync_log 
WHERE event_type LIKE 'export_%' 
  AND created_at > NOW() - INTERVAL '1 hour';

Step 3: Manual cleanup in e-conomic

• Go to Sales → Draft Orders
• Filter by date (today)
• Review and delete erroneous drafts
• Draft orders can be deleted without impact

Best Practices

1. Always test with dry-run first
2. Export ONE order to production before bulk operations
3. Verify in e-conomic after first export
4. Monitor audit logs regularly
5. Re-enable safety flags when not actively exporting
6. Keep EXPORT_TYPE=draft - never book automatically

Configuration Reference

# Safety Flags (default: SAFE)
TIMETRACKING_ECONOMIC_READ_ONLY=true   # Block all writes
TIMETRACKING_ECONOMIC_DRY_RUN=true     # Simulate writes

# Export Settings
TIMETRACKING_EXPORT_TYPE=draft         # draft|booked (ALWAYS use draft)

# e-conomic Credentials
ECONOMIC_API_URL=https://restapi.e-conomic.com
ECONOMIC_APP_SECRET_TOKEN=<token>
ECONOMIC_AGREEMENT_GRANT_TOKEN=<token>

Support

If export fails consistently:

1. Check docker-compose logs api | grep ERROR
2. Verify customer has economic_customer_number
3. Test e-conomic connection: GET /timetracking/economic/test
4. Review payload in dry-run logs
5. Contact e-conomic support if API errors persist