NPO-Accounting/npo-ledger-cli Changeset - f0ea3f31bf6f

Changeset - f0ea3f31bf6f

Parent rev.

Child rev.

[Not reviewed]

0 2 0

Bradley Kuhn (bkuhn) - 11 years ago 2013-04-30 18:42:54
bkuhn@ebb.org

First documentation for the Entity: tag.

Included also is a ledger command to get the list of all tag values.

2 files changed with 34 insertions and 0 deletions:

accounts/config/config-tags.ledger

npo-ledger-cli-tutorial.md

0 comments (0 inline, 0 general)

accounts/config/config-tags.ledger

➞

Show inline comments

@@ ... / @@ -26,24 +26,31 @@ tag Statement @@
     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\-]+)*/
     check  value =~ /^(Main Org:(Overhead|Direct Fundraising))$/
 ; 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\-]+)*/

npo-ledger-cli-tutorial.md

➞

Show inline comments

@@ ... @@
 insight, or other information about the transaction.  The value of the
 `Statement:` tag is always a valid pathname in the repository to the
 document, [as described above](#documentation-tags).
 Some examples of appropriate uses of the `Statement:` tag are:
 * bank statements, as received from the banking institution.
 * written reports of travel.
 * blog posts made by a contractor documenting their work.
 * written organizational policies about the expense.
 * just about anything that is clearly not an [invoice](#invoice-tag) nor a
   [receipt](#receipt-tag), but definitely is valid backup documentation for
   the transaction.
 ### Information Tags
 In contrast to documentation tags, information tags can more traditionally be
 considered pure "meta-data" for a ledger entry.
 #### Entity Tag
 The `Entity:` tag is required for many types of ledger entries.  The value of
 the `Entity:` tag is a unique moniker that identifies the organization,
 company, person, or legal entity that is the external party for the
 transaction.
 Note that there is no database of these monikers, so typos can cause
 trouble.  However, you could implement checks in
 `accounts/config/config-tags.ledger` using a regular expression to verify no
 typos have occurred.  This would be somewhat cumbersome, since Ledger CLI
 would likely require that the monikers be encoded into a regular expression.
 Barring that, the
 [integrity of your data should be periodically checked](checking-integrity-of-tag).
 #### IncomeType Tag
 The `IncomeType:` tag is used for all `Income:` accounts.  This refers to the
 type of income.  The value of the `IncomeType:` tag is always a string.
 Since this particular system is designed for USA non-profit entities who file
 USA Form 990, the following `IncomeType` values are supported:
 * `Donations`, which refers to standard charitable donations.
 * `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
@@ ... @@
 **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
 ### 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 &copy; 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)
 In addition, when you convey, distribute, and/or propagate this document
 and/or modified versions thereof, you may also preserve this notice so that
 recipients of such distributions will also have both licensing options
 described above.
 A copy of GPLv3 and CC-By-SA-3.0-USA can be found in the same repository as
 this file under the filenames GPLv3.txt and CC-By-SA-3.0-USA.txt.  If this
 document has been separated from the repository, a

0 comments (0 inline, 0 general)