; -*- ledger -*-

; -*- coding: utf-8 -*-

!include config/config-npo.ledger

!include org/main-org.ledger

; -*- ledger -*-

; -*- coding: utf-8 -*-

;

; config-tags.ledger: The Ledger CLI tag declarations for NPO use-case.

; Copyright © 2013, Bradley M. Kuhn.

;

; The copyright holders wish that this document could be placed into the

; public domain.  However, should such a public domain dedication not be

; possible, the copyright holders grant a waiver and/or license under the

; terms of CC0-1.0, as published by Creative Commons, Inc.  A copy of CC0-1.0

; can be found in the same repository as this README.md file under the

; filename CC0-1.0.txt.  If this document has been separated from the

; repository, a copy of CC0-1.0 can be found on Creative Commons' website at

; http://creativecommons.org/publicdomain/zero/1.0/legalcode

; ################################# TAGS ################################

; The Statement, Receipt, and Invoice tags' values should always a be a

; relative path names.  Note that we "check", but do not "assert" that the

; file name match a standard Unix-like path syntax, without spaces in the

; file name.

tag Statement

    assert value =~ /[^\/].+/

    check value =~ /[^\/][^ ]+(\/[^ ])+/

tag Receipt

    assert value =~ /[^\/].+/

    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\-]+)*/

; Entity tag is just a string, but shouldn't have spaces, just letters,

; numbers and dashes.

tag Entity

    assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/

tag TaxImplication

    assert value =~ /^W2|1099|Accountant-Advises-No-1099|Bank-Transfer|Foreign-Corporation|Foreign-Individual-Contractor|Payroll|Refund|Reimbursement|Tax-Payment|USA-501c3|USA-Corporation|USA-LLC-No-1099$/

; -*- 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

    Expenses: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

    Expenses: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

    Expenses:Main Org:Hosting               $-100.00

        ;Program: Main Org:Overhead

2012-05-03 Sir Moneybags

        ;Entity: Sir-Moneybags

        ;Program: Main Org:Direct Fundraising

        ;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

2012-07-05 J. Developer

        ;Entity: Developer-J

        ;Invoice: accounts/documentation/org/expenses/developer/2012-07-05_developer-invoice.txt

    Accrued:Accounts Payable:Main Org  $-5,000.00

    Expenses:Main Org:Development       $5,000.00

        ;Program: Main Org:Software:Internal

        ;Statement: accounts/documentation/org/expenses/developer/2012-07-05_developer-report.txt

2012-08-03 (1) J. Developer

        ;Entity: Developer-J

    Accrued:Accounts Payable:Main Org  $5,000.00

        ;Invoice: accounts/documentation/org/expenses/developer/2012-07-05_developer-invoice.txt

    Asset:Checking                    $-5,000.00

        ;TaxImplication: 1099

Changing the payee was a method for documenting the expense.  You might use

it like this:

    2011/05/28 My Bad Billing Hosting - NEVER CHARGED

        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.

#### Income Account Documentation

Each `Income:` account must have the following tags:

* One of: [`Invoice:`](#invoice-tag),

  [`PurchaseOrder:`](#purchase-order-tag),

  [`Statement:`](#statement-tag) or

  [`Contract`](#contract-tag).  Exceptions to this requirement are as follows:

     + the income generated from the transaction is less than $800, or

     + the `IncomeType` is `RBI` and the income is for a defined, public

       program (such as conference registration)

* An [`Entity:`](#entity-tag) tag, *iff.* the Income for the transaction is

  for more than $800.

* An [`IncomeType:`](#incometype-tag) tag.

* A [`Program:`](#program-tag) tag.

Reports For Various Situations

------------------------------

When data is well formed as specified herein, there are various quick reports

that can be used to verify certain conditions or issues with accounting.

Here are a few examples:

### Verifying That An Invoice Is Paid

Assume for this example that the shell variables `entity`, `program`, and

`invoice` are set as follows:

    $ entity=Sir-Moneybags; program='Main.*Org:.*Direct'; invoice=2012-05-30

If the invoice was paid, this ledger command will have two lines of output,

and the second line will be a transaction on the payment date.  If only one

line appears, it's the receivable accrual and we see the invoice is not paid.

    $ ledger -f accounts/books.ledger  -V --sort d --limit 'tag("Entity") =~ /'$entity'/ and tag("Program") =~ /'$program'/ and tag("Invoice") =~ /'$invoice'/' reg /Accrued/

Alternatively, the following command will only have output if the invoice is unpaid:

    $ ledger -f accounts/books.ledger  -V --limit 'tag("Entity") =~ /'$entity'/ and tag("Program") =~ /'$program'/ and tag("Invoice") =~ /'$invoice'/' bal /Accrued/

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 these:

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

FIXME: example output

### Checking Integrity of a Tag

[As mentioned](#entity-tag), the `Entity:` tag is one example among many

where the value is a wide range, but since Ledger CLI isn't backed by a more

complete ERP system, it's possible during data entry for typos to make a

serious problem.  One work around to this flaw is to periodically run a

command like:

    $ ledger -f accounts/books.ledger -F '%(tag("Entity"))\n' reg|sort|uniq|less

which will show all unique `Entity:` values currently in use.

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).

    * *or* the Creative Commons Attribution-ShareAlike 3.0 United States

      license, as published by Creative Commons, Inc. (aka CC-By-SA-USA-3.0)