Technical Architecture, API & Security Guide
Complete developer reference for SmartERP 19 BSC V3 — 20 data models, security groups, multi-company rules, XML-RPC APIs, and automated test suites.
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.
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 Interface#
- Log into your SmartERP instance at
https://smarterp.et/odoo. - Open the main App Switcher (grid icon in the top-left corner).
- Navigate to Balanced Scorecard → Strategic Dashboard.

Step 2: Operational Data Parameters & Controls#
Ensure all mandatory parameters comply with enterprise operational standards:
- Authorized Operator: Action executed under assigned RBAC permissions (Chief Executive Officer, Corporate Planning Director, Strategy Lead).
- Relational Integrity: Linked to upstream master records, approval requests, or transactional ledgers.
- Statutory & Quality Controls: Verified against Ethiopian statutory regulations and corporate governance standards.
Step 3: Operational Execution & State Progression#
- State Progression Gate: Advance record from Draft through Audited to Confirmed / Certified.
- Integrated System Impact: Automatically updates real-time operational states and posts financial/inventory journal moves.
- Audit Verification: System registers tamper-evident audit records logging user ID, timestamp, and cryptographic transaction digests.
Complete Data Model Architecture#
SmartERP BSC V3 operates across 20 unified models:
| Model Identifier | Database Table | Description & Relationships |
|---|---|---|
bsc.strategic.plan | bsc_strategic_plan | Strategic command center. One2many to versions, milestones, AOPs, analyses, scorecards, risks, scenarios, reviews. |
bsc.plan.version | bsc_plan_version | Immutable baseline snapshot. Stores changelog, approval metadata, and target benchmarks. |
bsc.plan.milestone | bsc_plan_milestone | Operational deliverables. Self-referential Many2many for predecessors with DFS cycle validation. |
bsc.analysis | bsc_analysis | Multi-framework diagnostic session (SWOT, PESTLE, Porter, VRIO, General). |
bsc.analysis.factor | bsc_analysis_factor | Granular analytical factor with Impact $\times$ Probability scoring and 1-click conversion links. |
bsc.analysis.assumption | bsc_analysis_assumption | Strategic hypotheses with validation status, sensitivity ratings, and review schedules. |
bsc.evidence.source | bsc_evidence_source | Verifiable empirical proof sources with reliability ratings and reference URLs. |
bsc.stakeholder | bsc_stakeholder | Mendelow Power vs. Interest matrix with engagement strategy classifications. |
bsc.competitor | bsc_competitor | Competitive profiling with tiers, market share %, and moats. |
bsc.annual.plan | bsc_annual_plan | Fiscal execution bridge with Capex/Opex budget envelopes and initiative linkages. |
bsc.initiative | bsc_initiative | Strategic programs with Capex/Opex allocations, actual costs, and ROI %. |
bsc.risk | bsc_risk | Strategic Risk Registry with $5 \times 5$ Inherent vs. Residual severity scoring and KRI links. |
bsc.scenario | bsc_scenario | Macro scenario models (Bull, Bear, Stress, Disruption) with revenue/cost variance percentages. |
bsc.strategy.review | bsc_strategy_review | Executive review sessions with discussion logs, approved pivots, and decision governance. |
bsc.scorecard | bsc_scorecard | Multi-tier scorecard (Corporate, Department, Team, Individual) tracking 4 perspectives. |
bsc.scorecard.perspective | bsc_scorecard_perspective | Perspective container enforcing mathematical 100% weight balance across child KPIs. |
bsc.objective | bsc_objective | Qualitative strategic goals linked to perspectives and parent-child cause-and-effect trees. |
bsc.kpi | bsc_kpi | Quantitative performance metric with directional scoring modes and ERP connectors. |
bsc.kpi.period | bsc_kpi_period | Time-slice period records (Monthly, Quarterly, Annual) storing target, actual, and score. |
bsc.theme | bsc_theme | Cross-cutting strategic themes (e.g., Digital Innovation, Customer Centricity). |
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:
test_bsc_engine.py(8 Tests): Verifies P0 defect remediations, Odoo 19_read_groupaggregation mechanics, future-period zero guards, and escalation cron behavior.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.test_bsc_analysis_intelligence.py(4 Tests): Exercises SWOT/PESTLE priority calculations, Mendelow matrix assignments, and 1-click factor conversions to objectives and risks.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 scoresBSC: 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#
| Error Symptom / Exception | Probable Root Cause | Corrective Action / Resolution |
|---|---|---|
Weighting Error: Perspective weights do not equal 100% | Total weights assigned to objectives within perspective fail to sum to 100.00%. | Adjust individual objective weightings so the perspective total equals exactly 100%. |
Data Feed Error: Automated KPI metric returned null | Underlying model query failed or target database view has no records. | Verify connected model name and filter domain in the KPI automated calculation parameters. |
Lockout Error: Period results locked for executive review | Current appraisal quarter has been locked by the Strategy Director. | Obtain written authorization and request temporary unlock from the Strategy Director. |