Accounting API - quandis/qbo3-Documentation GitHub Wiki

The Accounting module manages accounting information. While not a full-blown accounting system, the module's Ledger classes can easily be used to track accounting data, and can be configured by power users to do some pretty powerful things.

Real-world use cases include:

  • Tracking borrower financials for a collections or loss mitigation system
  • Tracking vendor fees and costs
  • Tracking data costs associated with execution of a business process (e.g. ordering credit reports, etc.)
  • Tracking total debt associated with a mortgage

Classes

Class Description
Ledger A ledger represents an invoice or similar financial statement
LedgerItem A ledger item represents a line item within a ledger
LedgerTemplate Template that determines the behavior of a Ledger.
LedgerTemplateItem Determines the behavior of a Ledger Item.

Templates

In addition to supporting extranet and repeatability, LedgerTemplates also support the following:

  • Expandable: Allows for the ability to add items on the fly or leave the ledger locked down to the items supplied with the template.
  • Locked: Locks the amount values supplied when the ledger is created.
  • RefreshOnInsert: Pre-populates the ledger items with mapped values (or default values) when a ledger is created.
  • CalculateMethod: Method signature that is used to populate the ledger item values.
  • ProjectMethod: Method signature that is used to project the ledger item values.
  • CustomTypes: a power user defined enumeration used to populate the Type drop down when editing a Ledger
  • CustomStatuses: a power user defined enumeration used to populate the Status drop down when editing a Ledger
  • ItemTypes: a power user defined enumeration used to populate the Type drop down when editing a Ledger Items
  • ItemStatuses: a power user defined enumeration used to populate the Status drop down when editing a Ledger Items
  • InvoiceTemplate: an Attachment Template used to generate an invoice document (usually a PDF) for a ledger
  • InvoiceMatrix: a matrix that includes an Attachment Template output to soft-code the invoice document template to use

LedgerItemTemplates additionally support the following:

  • UseInProjections: Can the item be used in future projections.
  • ManualInsert: Determines if the item should always be included with the ledger.
  • IsDebit: Default value is Credit.
  • IsTotaled: Used to determine if the item should be included in the ledger total.
  • IsLocked: Locks the amount values supplied when the ledger is created.
  • CanExclude: Allows the item to be excluded on the fly.
  • CanRefresh: Allows the item to be updated with the calculated values.

There are three key ways billing ledgers can be supported:

  1. Ledgers with item amounts populated by the user.
  2. Ledgers with item amounts populated by {Parent}/Summary.
  3. Ledgers with items that are child ledgers.

Automated Calculations

The Ledger/Calculate method iterates through each item in a ledger, calling calculate on each item, and storing the sum of each item in the Ledger.Balance column. There are three scenarios that are considered when calculating an item:

Scenario 1: Simple Items

With a "simple" item in a ledger, the item's amount is added to the ledger's balance (a straight forward sum). For example, assume we have:

Item Amount IsTotaled Notes
Item 1 125.00 Yes
Item 2 100.00 Yes
Item 3 50.00 No
Balance 275.00 This is the simple SUM of all items
Adjusted Balance 225.00 Item 3 is ignored

Scenario 2: Nested Items

A ledger item may point to a nested (child) ledger, in which case, calling calculate will call calculate on the nested ledger (recursively). For example, assume we have:

Item Amount IsTotaled Notes
Attorney Fees and Costs 2157.55 Yes This may comprise another entire ledger, the items of which detail each fee or cost incurred.
Hard Costs 1200.00 Yes This may comprise another ledger, the items of which detail each hard cost incurred.
Late Fee 150.00 Yes
Balance 275.00 This is the simple SUM of all items
Adjusted Balance 225.00 Item 3 is ignored.

Scenario 3: Matrix-based Items

In many use cases, there are complex rules that drive the calculation of a ledger item. In such a scenario, a power user may define a Matrix to determine the amount to populate into the ledger item.