NGO Operations Troubleshooting & Humanitarian FAQ

1. Overview & Business Value#

This comprehensive operational guide details the architecture, business workflows, configuration parameters, and execution steps for NGO Operations Troubleshooting & Humanitarian FAQ within SmartERP.

Troubleshooting solutions for budget hard-stop blocks, donor reporting currency mismatches, Telebirr bulk cash fails, and ACSO ratio warnings.

{screenshot:troubleshooting-and-humanitarian-faq-overview-dashboard}

2. Prerequisites & Security Access Groups#

• Required Modules: smarterp_ngo_grants, smarterp_humanitarian, smarterp_fund_accounting
• Security Groups:
  • Grant Officer (Technical ID: smarterp_ngo.group_grant_user)
  • Finance Director (NGO) (Technical ID: smarterp_ngo.group_grant_manager)
  • Field Relief Distribution Officer (Technical ID: smarterp_ngo.group_field_officer)
• Master Data Dependencies: Donor profiles (USAID, EU, UN, FCDO), multi-currency grant agreements, restricted fund accounts, ACSO 80/20 cost allocation categories, and beneficiary rosters.

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 NGO & Grants app icon.
4. From the top navigation bar, open NGO & Grants → Grants & Projects → Donor Agreements / Budget Burn / Relief Distributions.

{screenshot:troubleshooting-and-humanitarian-faq-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:
   • Grant Agreement Reference (Mandatory): Official donor contract number and co-funding arrangement
   • Funding Currency & Budget (Mandatory): Donor currency (USD/EUR) and restricted ETB counterpart account
   • Start & End Dates (Mandatory): Contractual grant operational window and closeout timeline
   • ACSO Cost Ratio Classification (Mandatory): Operational program expenditure vs. administrative overhead allocation
3. Configure optional operational parameters and localized tags as required:
   • Co-Funding Share (Optional): Percentage split across multiple donors or institutional match
   • Target Beneficiary Woreda / Kebele (Optional): Geographic location of humanitarian intervention
   • Relief Item Voucher (Model 20) (Optional): Distribution schedule for emergency food or non-food items (NFI)
4. Click the Save icon in the control bar to commit the record.

{screenshot:troubleshooting-and-humanitarian-faq-record-creation-form}

Step 3: Validating and Processing Transactions#

• State Transitions: Execute operational state progression (Draft Agreement → Approved / Funded → Active Implementation → Budget Burn Monitored → Grant Closed).
• Ledger & System Impact: Expenditures debit grant-restricted project accounts and credit vendor payables/cash; foreign currency conversions record realized and unrealized FX variance.
• Audit Verification: Automated recording of author ID, timestamp, and immutable revision history.

{screenshot:troubleshooting-and-humanitarian-faq-transaction-processing-state}

Frequently Encountered Issues & Resolutions#

1. Purchase Requisition Blocked Due to "Budget Hard-Stop"#

• Symptoms: System prevents submitting a purchase requisition for urgently needed field supplies with error: "Budget Exceeded on Line 2.1".
• Root Cause: The requested amount exceeds available uncommitted budget for that specific activity line.
• Resolution:
  1. Open the project budget breakdown in NGO Grants > Projects > Budget Breakdown.
  2. Verify if savings exist on sibling budget lines.
  3. Submit an electronic Budget Virement Request (internal transfer between lines) within authorized donor thresholds (typically up to 10% without formal donor amendment).
  4. Once the Finance Director approves the virement, the requisition clears immediately.

2. Telebirr Bulk Cash Transfer Dispatches with Partial Failures#

• Symptoms: Out of 1,000 cash transfer recipients, 982 succeed but 18 report RECIPIENT_WALLET_INACTIVE.
• Resolution:
  1. Open NGO Grants > CVA > Cash Transfer Batches and select the failed transaction queue.
  2. The system isolates the 18 failed records without duplicating the 982 successful payments.
  3. Contact the field team to update beneficiary mobile numbers or issue manual cash counter vouchers.
  4. Click Retry Failed Payouts to re-dispatch the updated recipients.

3. ACSO 80/20 Dashboard Flags Warning: "Admin Ratio at 21.4%"#

• Symptoms: Mid-year compliance dashboard displays an orange warning indicating administrative expenses are trending above the 20% statutory cap.
• Root Cause: Central office overhead expenditures incurred early in the year while field program activity disbursements were delayed.
• Resolution:
  1. Convene an executive management review with program directors to accelerate planned field program activities.
  2. Verify that all field-related monitoring travel and project vehicle fuel were properly tagged as Program (80%) rather than mistakenly coded to administrative overhead.
  3. Reclassify miscoded direct project lines to restore compliance.

4. Advanced Configuration Points#

• Automated Actions & Scheduled Tasks (Crons):
  • NGO: Calculate ACSO 80/20 cost ratio compliance (smarterp_ngo.ir_cron_acso_ratio): Runs weekly to flag any operational overhead drift above 20% limit
  • Grants: Reconcile foreign currency funding variance (smarterp_ngo.ir_cron_fx_reconcile): Runs monthly to revalue restricted foreign currency bank accounts
• Custom Print Templates & Reports:
  • ACSO Statutory Annual Financial Statement (80/20 Rule)
  • Donor Financial Expenditure Report (Multi-Currency)
  • Beneficiary Relief Distribution Voucher (Model 20 SIV)
  • Time-and-Effort Personnel Timesheet Allocation 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#