Technical Architecture, API & Security Guide

1. Overview & Business Value#

This comprehensive operational guide details the architecture, business workflows, configuration parameters, and execution steps for Technical Architecture, API & Security Guide within SmartERP.

This section provides technical reference documentation for systems architects, backend developers, and database administrators integrating SmartERP Balanced Scorecard with corporate data warehouses, external BI tools, or custom Odoo addons.

{screenshot:technical-architecture-and-governance-overview-dashboard}

2. Prerequisites & Security Access Groups#

• Required Modules: smarterp_balanced_scorecard, smarterp_strategy
• Security Groups:
  • Strategy Officer (Technical ID: smarterp_balanced_scorecard.group_bsc_user)
  • Strategy Director (Technical ID: smarterp_balanced_scorecard.group_bsc_manager)
  • Executive Committee Member (Technical ID: smarterp_balanced_scorecard.group_bsc_executive)
• Master Data Dependencies: Strategic themes, 4 BSC perspectives (Financial, Customer, Internal Process, Learning & Growth), corporate KPIs, and quarterly appraisal periods.

3. Step-by-Step Configuration & Execution#

Step 1: Navigating to the Module Interface#

1. Log into your SmartERP instance at https://smarterp.et/odoo.
2. Open the main App Switcher (grid icon in the top-left corner).
3. Select the Strategic Execution app icon.
4. From the top navigation bar, open Strategic Execution → Perspectives → Strategic Objectives / KPIs / Action Plans.

{screenshot:technical-architecture-and-governance-app-switcher-navigation}

Step 2: Creating and Parameterizing Records#

1. Click the New button in the top-left control panel.
2. Complete the mandatory fields in the record form:
   • Objective / KPI Name (Mandatory): Precise strategic outcome statement
   • Perspective (Mandatory): One of the 4 balanced perspectives with mandated weighting
   • Weight (%) (Mandatory): Percentage allocation contributing to overall perspective score
   • Target Value & Baseline (Mandatory): Quantifiable numerical goal and historical starting point
3. Configure optional operational parameters and localized tags as required:
   • Calculation Formula (Optional): Automated SQL query or module model metric extraction
   • Initiative Champion (Optional): Department head or senior manager accountable for result
   • Review Frequency (Optional): Monthly, quarterly, or annual appraisal cadence
4. Click the Save icon in the control bar to commit the record.

{screenshot:technical-architecture-and-governance-record-creation-form}

Step 3: Validating and Processing Transactions#

• State Transitions: Execute operational state progression (Draft → Active Target → Mid-Term Review → Final Appraisal → Locked).
• Ledger & System Impact: Financial perspective KPIs dynamically read General Ledger balances, revenue growth metrics, and cost ratios directly from the accounting engine.
• Audit Verification: Automated recording of author ID, timestamp, and immutable revision history.

{screenshot:technical-architecture-and-governance-transaction-processing-state}

Complete Data Model Architecture#

SmartERP BSC V3 operates across 20 unified models:

Security Groups & Multi-Company Isolation#

1. User Security Groups (security/bsc_security.xml)#

• BSC User (group_bsc_user):
  • Read access across corporate and departmental scorecards.
  • Read/Write access on individual scorecards and assigned milestone tasks.
• BSC Manager (group_bsc_manager):
  • Full administrative rights: Create and approve Strategic Plans, generate version baselines, configure AOP budget envelopes, manage the Risk Registry, and configure ERP query connectors.

2. Multi-Company Record Rules#

To prevent data leaks in multi-tenant holding companies, 7 multi-company record rules enforce strict tenant separation:

<record id="rule_bsc_strategic_plan_company" model="ir.rule">
    <field name="name">BSC Strategic Plan Multi-Company</field>
    <field name="model_id" ref="model_bsc_strategic_plan"/>
    <field name="domain_force">['|', ('company_id', '=', False), ('company_id', 'in', company_ids)]</field>
</record>

Applies uniformly across bsc.strategic.plan, bsc.annual.plan, bsc.analysis, bsc.risk, bsc.scorecard, bsc.objective, and bsc.kpi.

External API Integration (Python XML-RPC)#

External BI platforms (Tableau, PowerBI, Metabase, custom microservices) query and update BSC V3 metrics via Odoo's native XML-RPC or JSON-RPC endpoints:

import xmlrpc.client

url = "https://smarterp.et"
common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate("dev", "api_user", "api_key_or_password", {})
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

# 1. Fetch Executive Corporate Health Score
plans = models.execute_kw(
    "dev", uid, "api_key",
    "bsc.strategic.plan", "search_read",
    [[["state", "=", "approved"]]],
    {"fields": ["name", "code", "horizon", "current_version", "milestone_progress"]}
)
print("Active Strategic Plan:", plans[0])

# 2. Query High-Priority Strategic Risks (Score >= 16)
risks = models.execute_kw(
    "dev", uid, "api_key",
    "bsc.risk", "search_read",
    [[["inherent_score", ">=", 16]]],
    {"fields": ["name", "category", "inherent_score", "residual_score", "risk_treatment"]}
)
for r in risks:
    print(f"Alert: {r['name']} — Residual: {r['residual_score']}")

Automated Test Suites#

The module ships with 22 unit and regression tests across 4 test suites:

1. test_bsc_engine.py (8 Tests): Verifies P0 defect remediations, Odoo 19 _read_group aggregation mechanics, future-period zero guards, and escalation cron behavior.
2. test_bsc_strategic_plan.py (6 Tests): Validates horizon date calculation, approved version immutability locks, code uniqueness constraints, and DFS milestone circular dependency cycle rejection.
3. test_bsc_analysis_intelligence.py (4 Tests): Exercises SWOT/PESTLE priority calculations, Mendelow matrix assignments, and 1-click factor conversions to objectives and risks.
4. test_bsc_annual_plan_and_risk.py (4 Tests): Tests AOP Capex/Opex budget summation, initiative ROI percentage computations, and $5 \times 5$ Risk Heatmap Inherent vs. Residual scoring.

To run the complete test suite:

odoo --test-enable -i smarterp_bsc -d test_bsc_db --stop-after-init

4. Advanced Configuration Points#

• Automated Actions & Scheduled Tasks (Crons):
  • BSC: Calculate quarterly KPI achievements (smarterp_bsc.ir_cron_compute_kpi): Runs quarterly on the 5th to compute composite achievement scores
  • BSC: Issue appraisal cascade reminders (smarterp_bsc.ir_cron_appraisal_alert): Runs monthly to remind objective champions to update progress
• Custom Print Templates & Reports:
  • Institutional Balanced Scorecard Executive Dashboard
  • Departmental Strategic Cascade Matrix
  • KPI Performance Variance & Trend Analysis
  • Corporate Strategy Execution Summary
• Multi-Company Rules: Record-level security isolation under Company 1 (Ashewa Technology Solutions S.C.), preventing cross-company ledger leakage across parent and subsidiary legal entities.

5. Comprehensive Troubleshooting Matrix#