Client Invoicing & Reminders

Business perspective: Client Invoicing & Reminders

1. Business Summary

Generates client invoices from POs/jobs/tasks, applies brand-specific PDF templates, dispatches emails, manages reminders, syncs to SAP, and tracks payment status.

2. Business Value

Bills customers and tracks AR; primary revenue stream control.

3. Users / Stakeholders

Finance, AMs, clients, executives.

4. Workflows

  • Aggregate jobs/tasks under PO into ClientInvoice.
  • Compute totals (price/discount/tax/extra fees) via EngineFunctions.
  • Generate brand PDF; email to ClientInvoicesContact.
  • Submit to SAP via sapClientInvoiceSync(); mark sap_posted.
  • Manage reminders via crons.
  • Reconcile payments via SAP receive endpoints.

5. Sub-Features

  • ClientInvoicesJob (line items), ClientInvoicesContact (recipients), ClientInvoicesMail (mail logs).
  • Brand-specific templates.
  • Reminder scheduling and pause/resume.

6. Business Rules

  • Invoice issue date ≥ '2018-01-01' for SAP sync.
  • submitted=1 and sap_posted!=1 required to sync.
  • Currency conversion to main currency for reporting.
  • Min-price applied when configured.

7. Data Entities

ClientInvoice, ClientInvoicesJob, ClientInvoicesContact, ClientInvoicesMail, InvoicingStatus, PaymentStatus.

8. Entry Points

  • finance/clientInvoices, finance/clientInvoicesJobs, finance/clientInvoicesContacts.
  • Internal submitClientInvoice (CommonController).
  • SAP sync via SapController::sapClientInvoiceSync.

9. Inputs & Outputs

  • Inputs: PO/jobs/tasks, account, currency, contacts, dates.
  • Outputs: invoice record, PDF, emails, SAP records.

10. Integrations

  • SAP, brand templates, email (CakeEmail), PhpExcel for exports.

11. Calculations / Logic

  • getJobTaxAmount, getJobGrossProfit, getJobTotalPrice, getTotalPriceMainCurrency, setInvoiceAmount.

12. Status Lifecycle

  • draft → submitted → sap_posted → paid (via PaymentStatus).

13. Permissions

  • Finance role, brand-scoped.

14. Reports & KPIs

  • AR aging, days-to-pay, invoice volume, gross profit.

15. Risks & Observations

  • Brand-template fragmentation increases maintenance.
  • Hard-coded SAP cutoff date.
  • SAP Currency = "##" defaults could be rejected.
  • Reminder pause/resume stored as flags — easy to misconfigure.

16. Source Code Evidence

  • app/Plugin/finance/Model/ClientInvoice.php, ClientInvoicesContact.php, ClientInvoicesJob.php, ClientInvoicesMail.php.
  • app/Plugin/finance/Controller/ClientInvoicesController.php, ClientInvoicesContactsController.php, ClientInvoicesJobsController.php.
  • app/Controller/SapController.php :: sapClientInvoiceSync (~line 822), reconciliation logic.
  • app/Controller/ExportInvoicesController.php :: invoice calc & export.
  • app/Controller/CommonController.php :: submitClientInvoice (~line 1076).

← Deep dives index