SmartERP Documentation An Ashewa Technology Solutions Platform

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.

Module map showing dependencies between SmartERP Supply Chain Core, Tenders, Store Vouchers, Landed Costs, and WMS.
SmartERP Supply Chain and Sourcing architectural module map.

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#

  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. 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 CodeDisplay NameContent Modifiable?Key System Events & Triggers
draftDraftYesDrafter prepares subject, body, recipients, attachments. Temporary draft_number assigned (e.g., DRF-2026-00012).
submittedSubmittedNo (except drafter recall)Drafter clicks Submit for Review. Reviewers and approvers notified via SmartERP Mail.
under_reviewUnder ReviewComments onlyAssigned reviewers evaluate letter content, verify legal attachments, and submit endorsements or objections.
revision_requestedRevision RequestedYes (by drafter)Approver or reviewer sends back letter with mandatory revision_reason. Letter returns to drafter for corrections.
approvedApprovedStrictly Read-OnlyDesignated authority approves letter. Self-approval is strictly blocked by business logic. Approval timestamp and approver recorded.
registeredRegisteredStrictly Read-OnlyRegistry officer assigns official permanent reference_number using PostgreSQL row-level locks. Letter gains legal standing.
dispatchedDispatchedStrictly Read-OnlyPhysical letter dispatched via courier/postal service or digital letter sent via email/portal. Dispatch date, tracking number, and manifest generated.
acknowledgedDelivered / AcknowledgedStrictly Read-OnlyRecipient signs return receipt (የመቀበያ ደረሰኝ) or digital delivery confirmation logged.
closedClosedStrictly Read-OnlyRequired action items completed or incoming reply received and linked.
archivedArchivedStrictly Read-OnlyLetter 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:

  1. 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.").
  2. Quorum & Multi-Tier Approvals: High-value or legally binding correspondence types can require multiple consecutive approvals (e.g., Legal Officer -> Finance Director -> CEO).
  3. 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).
  4. Optimistic Concurrency Protection: Each letter maintains an optimistic_version counter. 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 slips
    • Letters: 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 / ExceptionProbable Root CauseCorrective Action / Resolution
Signature Block: Missing executive stamp clearanceLetter cannot be dispatched without authorized cryptographic stamp.Submit letter to Executive Office for digital signing.
Calendar Error: Invalid Ethiopian date conversionSpecified 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 TINExternal institutional recipient lacks complete corporate profile.Create or update recipient partner master record before dispatching.
Last updated: 2026-11-15