Lifecycle and approval workflows
Comprehensive state transitions, multi-stage approval workflows, quorum voting, delegation, dispatch management, and return receipts.
1. Overview & Business Value#
This comprehensive operational guide details the architecture, business workflows, configuration parameters, and execution steps for Lifecycle and approval workflows within SmartERP.

SmartERP Letter & Correspondence Management enforces a rigorous, stateful lifecycle designed to eliminate accidental dispatch, ensure managerial oversight, and maintain an immutable historical record. Once a letter reaches the approved stage, its core content fields become read-only and protected by database-level constraints.
2. Prerequisites & Security Access Groups#
- Required Modules:
smarterp_letter, smarterp_correspondence - Security Groups:
Letter Registry Clerk(Technical ID:smarterp_letter.group_letter_clerk)Executive Reviewer(Technical ID:smarterp_letter.group_letter_reviewer)Director General(Technical ID:smarterp_letter.group_letter_executive)
- Master Data Dependencies: Dual calendar templates (Ethiopian & Gregorian), official stamp repository, letter reference numbering formats, and departmental dispatch routes.
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 Settings → Technical.
Step 2: Operational Data Parameters & Controls#
Ensure all mandatory parameters comply with enterprise operational standards:
- Authorized Operator: Action executed under assigned RBAC permissions (System Administrator, Certified Specialist).
- 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.
Correspondence lifecycle state machine#
The standard journey of an official letter progresses through distinct phases:
flowchart TD
D[Draft / ዝግጅት] -->|Submit| SUB[Submitted / የቀረበ]
SUB -->|Assign Reviewers| REV[Under Review / በግምገማ ላይ]
REV -->|Request Changes| RR[Revision Requested / ማሻሻያ የተጠየቀ]
RR -->|Update & Resubmit| SUB
REV -->|Approve| APP[Approved / የጸደቀ]
APP -->|Allocate Official Number| REG[Registered / የተመዘገበ]
REG -->|Dispatch / Send| DISP[Dispatched / የተላከ]
DISP -->|Confirm Delivery| ACK[Delivered / ደረሰኝ የተረጋገጠ]
ACK -->|Complete Action| CLS[Closed / የተጠናቀቀ]
CLS -->|Retention Policy| ARC[Archived / ማህደር የገባ]
SUB -.->|Reject| REJ[Rejected / ውድቅ የተደረገ]
REV -.->|Reject| REJ
D -.->|Cancel| CANC[Cancelled / የተሰረዘ]
State descriptions#
| State Code | Display Name | Content Modifiable? | Key System Events & Triggers |
|---|---|---|---|
draft | Draft | Yes | Drafter prepares subject, body, recipients, attachments. Temporary draft_number assigned (e.g., DRF-2026-00012). |
submitted | Submitted | No (except drafter recall) | Drafter clicks Submit for Review. Reviewers and approvers notified via SmartERP Mail. |
under_review | Under Review | Comments only | Assigned reviewers evaluate letter content, verify legal attachments, and submit endorsements or objections. |
revision_requested | Revision Requested | Yes (by drafter) | Approver or reviewer sends back letter with mandatory revision_reason. Letter returns to drafter for corrections. |
approved | Approved | Strictly Read-Only | Designated authority approves letter. Self-approval is strictly blocked by business logic. Approval timestamp and approver recorded. |
registered | Registered | Strictly Read-Only | Registry officer assigns official permanent reference_number using PostgreSQL row-level locks. Letter gains legal standing. |
dispatched | Dispatched | Strictly Read-Only | Physical letter dispatched via courier/postal service or digital letter sent via email/portal. Dispatch date, tracking number, and manifest generated. |
acknowledged | Delivered / Acknowledged | Strictly Read-Only | Recipient signs return receipt (የመቀበያ ደረሰኝ) or digital delivery confirmation logged. |
closed | Closed | Strictly Read-Only | Required action items completed or incoming reply received and linked. |
archived | Archived | Strictly Read-Only | Letter transferred to long-term digital repository under statutory retention schedule. |
End-to-end approval and dispatch sequence#
The following sequence illustrates the interaction between Drafter, Approver, Registry Officer, and external recipient:
sequenceDiagram
autonumber
actor Drafter as Action Officer (Drafter)
actor Approver as Department Head (Approver)
actor Registry as Registry / Dispatch Officer
participant Letters as SmartERP Letters
participant DMS as SmartERP Documents (DMS)
actor Recipient as External Organization
Drafter->>Letters: Create draft letter & select template
Letters->>DMS: Create draft document in DMS workspace
Drafter->>Letters: Submit for review
Letters->>Approver: Send approval activity notification
Approver->>Letters: Review content & click Approve
Letters->>Letters: Lock content & increment optimistic_version
Registry->>Letters: Allocate official reference number
Letters->>Letters: Assign permanent reference (e.g. ATS/CORP/OUT/2026/00142)
Registry->>Letters: Affix organizational stamp & sign PDF
Letters->>DMS: Generate final signed PDF with SHA-256 digest
Registry->>Recipient: Dispatch letter via courier or email
Registry->>Letters: Mark Dispatched (record dispatch mode & tracking)
Recipient-->>Registry: Return signed acknowledgment receipt
Registry->>Letters: Upload signed return receipt & mark Delivered
Approval governance rules#
SmartERP Letter Management integrates with smarterp_approval to enforce four strict governance rules:
- Self-Approval Prohibition: A user cannot approve a letter that they drafted or for which they are the responsible officer. Attempting to approve one's own letter raises a
UserError("Self-approval is strictly prohibited for official correspondence."). - Quorum & Multi-Tier Approvals: High-value or legally binding correspondence types can require multiple consecutive approvals (e.g., Legal Officer -> Finance Director -> CEO).
- Delegation with Audit Trail: An approver may delegate their approval authority during leave. The system records both the delegated actor and the delegating officer in the immutable audit log (
smarterp.letter.audit.log). - Optimistic Concurrency Protection: Each letter maintains an
optimistic_versioncounter. If two officers attempt to modify or approve the letter simultaneously, the second transaction is safely rolled back to prevent race conditions.
4. Advanced Configuration Points#
- Automated Actions & Scheduled Tasks (Crons):
Letters: Check dispatch delivery receipt status(smarterp_letter.ir_cron_dispatch_check): Runs daily to verify courier delivery confirmation slipsLetters: Follow-up on pending memorandum actions(smarterp_letter.ir_cron_followup): Runs weekly to alert assigned officers of pending correspondence replies
- Custom Print Templates & Reports:
- Official Letterhead Dispatch Copy with QR Verification
- Institutional Letter Inward/Outward Registry Ledger
- 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 |
|---|---|---|
Signature Block: Missing executive stamp clearance | Letter cannot be dispatched without authorized cryptographic stamp. | Submit letter to Executive Office for digital signing. |
Calendar Error: Invalid Ethiopian date conversion | Specified Ethiopian calendar date does not match leap year rules (Pagume 5/6). | Use the automated calendar picker to ensure synchronized EC/GC conversion. |
Unregistered Recipient: Partner profile missing TIN | External institutional recipient lacks complete corporate profile. | Create or update recipient partner master record before dispatching. |