Changeset - a4a10fc7b0ac
[Not reviewed]
0 4 0
Bradley Kuhn (bkuhn) - 11 years ago 2013-04-29 23:55:07
bkuhn@ebb.org
Initial documentation of the Program: tag.
Includes introduction of the section about making use of these tags.
4 files changed with 45 insertions and 1 deletions:
0 comments (0 inline, 0 general)
accounts/config/config-accounts.ledger
Show inline comments
...
 
@@ -32,25 +32,25 @@ account Liabilities:Credit Card:Visa
 
; Organizational accrual accounts
 

	
 
account Accrued:Accounts Receivable:Main Org
 
    note Accrued receivables for Main Org
 
    assert commodity == "$"
 

	
 
; Organizational Expense Accounts
 

	
 
; NOTE: the payee =~ test is *not* included herein and must be cut-and-pasted
 
;       to the assert in ever Expense account because of the following bug:
 
;               http://bugs.ledger-cli.org/show_bug.cgi?id=953
 

	
 
define expenseChecker() = (tag("Receipt") !~ /^\s*$/ or tag("Invoice") !~ /^\s*$/ or tag("Statement") !~ /^\s*$/)
 
define expenseChecker() = (tag("Receipt") !~ /^\s*$/ or tag("Invoice") !~ /^\s*$/ or tag("Statement") !~ /^\s*$/) and tag("Program") !~ /^\s*$/
 
; or payee =~ /NEVER CHARGED/
 

	
 
account Expense:Main Org:Office Supplies
 
    assert expenseChecker() or payee =~ /NEVER CHARGED/
 
    note Main Organization's Office Supplies and Sundries
 

	
 
account Expense:Main Org:Payroll:Salary
 
    assert expenseChecker() or payee =~ /NEVER CHARGED/
 
    note Main Organization's Staff Salaries
 

	
 
account Expense:Main Org:Payroll:Benefits
 
    assert expenseChecker() or payee =~ /NEVER CHARGED/
accounts/config/config-tags.ledger
Show inline comments
...
 
@@ -30,12 +30,20 @@ tag Receipt
 
    check value =~ /[^\/][^ ]+(\/[^ ])+/
 

	
 
tag Invoice
 
    assert value =~ /[^\/].+/
 
    check value =~ /[^\/][^ ]+(\/[^ ])+/
 

	
 
; IncomeType refers to the types of income a non-profit can receive.  In this
 
; example, it's for the categorizations on the USA Form 990.  This could be
 
; changed to accomodate other jurisdictions around the world.
 

	
 
tag IncomeType
 
    assert value =~ /^(Donations|RBI|UBTI)$/
 

	
 
; Program tag must match the general format of a ledger account as an
 
; assertion, but we at least check known names of programs, so that warnings
 
; are produced if a new program never seen before is encountered.
 

	
 
tag Program
 
    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/
 
    check  value =~ /^(Main Org:(Overhead|Direct Fundraising))$/
accounts/org/main-org.ledger
Show inline comments
 
; -*- ledger -*-
 
; -*- coding: utf-8 -*-
 

	
 
!include ../config/config-npo.ledger
 

	
 
2012-02-05 Office Supply Galore - Online Order
 
        ;Receipt: accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt
 
    Expense:Main Org:Office Supplies          $35.00
 
        ;Program: Main Org:Overhead
 
    Liabilities:Credit Card:Visa             -$35.00
 

	
 
2011/05/28 My Bad Billing Hosting - NEVER CHARGED
 
    Liabilities:Credit Card:Visa            $-100.00
 
    Expense:Main Org:Hosting                 $100.00
 
        ;Program: Main Org:Overhead
 

	
 
2012/01/01 My Bad Billing Hosting - REVERSAL - NEVER CHARGED
 
    Liabilities:Credit Card:Visa             $100.00
 
    Expense:Main Org:Hosting                $-100.00
 
        ;Program: Main Org:Overhead
 

	
 
2012-05-03 Sir Moneybags
 
        ;Entity: Sir-Moneybags
 
        ;Invoice: accounts/documentation/org/invoices/2012-05-30_moneybags-invoice_as-sent.txt
 
    Accrued:Accounts Receivable:Main Org  $100,000.00
 
    Income:Main Org:Donations            $-100,000.00
 
        ;IncomeType: Donations
 
        ;Program: Main Org:Direct Fundraising
npo-ledger-cli-tutorial.md
Show inline comments
...
 
@@ -252,24 +252,36 @@ USA Form 990, the following `IncomeType` values are supported:
 

	
 
* `RBI`, which refers to "related business income".
 

	
 
* `UBTI`, which refers to "unrelated business taxable income.
 

	
 
Not that donor-advised funds and government grants don't currently have their
 
own `IncomeType`.  It's possible this might be necessary; the authors aren't
 
familiar with how to handle those items on the Form 990.  It would be a
 
relatively simple change to `config-tags.ledger`, though, to support other
 
income types, or to change it entirely to handle use-cases other than USA
 
Form 990 filing.
 

	
 
#### Program Tag
 

	
 
The `Program` tag is used primarily to track program activity for `Income:`
 
and `Expense:` accounts.  This allows for knowing what particular initiative
 
initiated the income (e.g., a specific fundraising campaign) and/or what
 
particular program activity an expense is toward (e.g., funding travel to
 
some specific conference).
 

	
 
The Program tag is always a string with the same format as a Ledger CLI
 
account (primarily for use with Ledger CLI's `--pivot` and `--group-by`,
 
[as described later](#testing-program-success).
 

	
 
### Expense Account Documentation
 

	
 
Each Expense account entries need to be tagged with an
 
[`Invoice`](#invoice-tag), [`Receipt`](#receipt-tag), or
 
[`Statement`](#statement-tag) tag.  The value of the tag is a relative path
 
name of a file elsewhere in the same repository that documents the specific
 
expense.  For example, an entry like this:
 

	
 
     2012-02-05 Office Supply Galore - Online Order
 
         Expense:Main Org:Office Supplies      $35.00
 
             ;Receipt: accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt
 
         Liabilities:Credit Card:Visa         -$35.00
...
 
@@ -303,24 +315,44 @@ it like this:
 
        Liabilities:Credit Card:Visa            $-100.00
 
        Expenses:Conservancy:Hosting             $100.00
 

	
 
    2012/01/01 My Bad Billing Hosting - REVERSAL - NEVER CHARGED
 
        Liabilities:Credit Card:Visa             $100.00
 
        Expenses:Conservancy:Hosting            $-100.00
 

	
 
However, going forward, you'd likely never enter anything the ledger
 
**until** you had real proof via an Invoice, Receipt or Statement that showed
 
the Expense did/should occur.  This use of `NEVER CHARGED` in the payee is
 
thus deprecated.
 

	
 
Analysis of the Data
 
--------------------
 

	
 
If this methodology is followed, Ledger can be used to analyze the financial
 
data for the organization.
 

	
 
### Testing Program Success
 

	
 
If you use the [`Program`](#program-tag) tag effectively, you can easily test
 
the successes of various fundraising programs with a command like this:
 

	
 
    $ ledger -f accounts/books.ledger --pivot Program bal '/^Income/'
 

	
 
Meanwhile, using the  [`Program`](#program-tag) tag for Expenses can help
 
track what programs are costing with commands like hese:
 

	
 
    $ ledger -f accounts/books.ledger --group-by 'tag("Program")' reg '/^Expense/'
 

	
 
FIXME: example output
 

	
 
Copyright and License of This File
 
----------------------------------
 

	
 
This specific document, the README.md file for npo-ledger-cli, is copyrighted:
 
  Copyright © 2013, Bradley M. Kuhn
 

	
 
This document's license gives you freedom; you can copy, modify, convey,
 
propagate, and/or redistribute this software under the terms of either:
 

	
 
    * The GNU General Public License as published by the Free Software
 
      Foundation, Inc.; either version 3 of the License, or (at your option)
 
      any later version (aka GPLv3-or-later).
0 comments (0 inline, 0 general)