Usage Guide

This is general usage guide for tackler.

See especially Quickstart and also Installation Manual how to setup minimal journal setup.

Use tackler new to create a functional template journal:

tackler new journal
tackler --config journal/conf/tackler.toml

Command Line Interface

See tackler.toml, accounts.toml, commodities.toml and tags.toml for full configuration options.

Tackler journal contains configuration settings for that particular accounting setup, and accounting transactions. The journal configuration has settings for default reports (for that setup), and default reports can be generated by just running tackler with that configuration.

Tackler invocation with default setup and with configured reports

tackler --config journal/conf/tackler.toml

This setup can have overlay configuration options by CLI arguments, and it’s possible to run reports with different parameters.

See Command Line Reference for full list of all available CLI options.

Tackler Journal

There are few different ways to provide transaction data to Tackler.

Input can be based on:

Filesystem storage (Filesystem Storage Guide)
- Journal in single file
- Journal data is in multiple files inside directory structure
Git storage (Git SCM Storage Guide)
- Journal is in single file inside directory structure
- Journal data is in multiple files inside directory structure

Storage selector

If there are valid configurations for filesystem and git storage, then used storage system can be switched from command line:

--input.storage: Valid options are fs or git.

This is good way to run trial reports with working copy data, before committing transactions into repository, if reports are normally run directly from GIT Storage (git).

Or vice versa, when filesystem storage (fs) is configured as default storage, but when official reports are run from Git Storage.

The default minimal setup is already configured out-of-the-box for this kind of setup, and Git SCM Primer has description how to initialize Git SCM journal.

Journal in single file

Single file input can be defined only by command line switch:

--input.file: This is a path to journal file, which will be used for input. The path can be absolute or relative path based on current working directory.

If you like to use single journal file mode and define it in configuration, then this is done by putting the journal file into dedicated directory and to define journal to be that directory (Filesystem Storage Guide).

Journal data in multiple transaction files

Typically journal is stored in multiple transaction files, and journal is diced into multiple shards by business case relevant logic.

--input.fs.dir: Option can be used from CLI to define the used transaction data (shard). This is very handy when tackler is integrated with scripts.

See Journal Sharding for discussion of possible sharding schemes. Also the Production Setup has ideas how to setup journal.

Git storage

Tackler journal data can be read directly from git. The git repository could be part of working copy or it can be a bare repository (that’s repository without working copy).

See Git SCM Storage Guide for full documentation.

Addition to the storage configuration, Git Storage options can be set by CLI options:

--input.git.ref <reference>: Use reference for git reference. This could be e.g. tag or branch name. When the reference is branch, the HEAD of that branch is be used automatically. This can not be specified at the same time with --input.git.commit.
--input.git.commit <commit-id>: Use single commit-id and tree defined by it. This can not be specified at the same time with --input.git.ref.
--input.git.dir <txns-directory>: journal transaction directory inside the git repository. All files inside this directory tree with correct file extension will be used as journal data.

These options are mutually exclusive with filesystem storage arguments (input.fs.*).

See Journal Sharding for discussion of possible sharding schemes.

Transaction Filters

Tackler has an option to filter transactions based on attributes of single transaction.

If transaction is filtered away by txn filter, it will disappear from all calculations and statistics. The effect is same as if transaction didn’t exist in the first place. Transactions can be filtered based on various attributes of single transaction, and different filters can be combined logically together.

For full list of available filters and their syntax, see Transaction Filters document.

Transaction filter can be defined by providing filter definition as JSON with --api-filter-def option, and it can be plain JSON or encoded as base64 string. Base64 encoding will make it easy to use filters with shell scripts.

Belows is an example of filter to find all transactions where there is "ice-cream" on transaction’s description field.

--api-filter-def '{ "txnFilter": { "TxnFilterTxnDescription": { "regex": ".*ice-cream.*" } } }'

Same filter defined as base64 string (with base64 --wrap=0):

--api-filter-def base64:eyAidHhuRmlsdGVyIjogeyAiVHhuRmlsdGVyVHhuRGVzY3JpcHRpb24iOiB7ICJyZWdleCI6ICIuKmljZS1jcmVhbS4qIiB9IH0gfQo=

If txn filter is defined as base64 string, then there must be base64: at the begin of string (see Using txn filters with shell).

Second example is more complex combination of filters to find all transactions which have code as starting "#" and description starts as "txn-".

--api-filter-def '{ "txnFilter": { "TxnFilterAND" : { "txnFilters" : [ { "TxnFilterTxnCode": { "regex": "#.*" } },  { "TxnFilterTxnDescription": { "regex": "txn-.*" } } ] } } }'

See Transaction Filters for list of all available filters and their syntax.

Using Transaction Filters with shell scripting

Transaction filters can be easily combined and created by shell scripts. Filter definitions can be easily handled with shell scripts in base64 ascii armor format.

By combining these two features, it’s easy to extend Tackler’s functionality with simple and powerful constructs.

Filter for time span

Below is an example of bash-based shell function which creates transaction filter for time span :

time_span_filter () {
    local begin=$1
    local end=$2

    flt=$(cat << EOF | base64 --wrap=0
{
    "txnFilter" : {
        "TxnFilterAND" : {
            "txnFilters" : [
                {
                    "TxnFilterTxnTSBegin" : {
                        "begin" : "$begin"
                    }
                },
                {
                    "TxnFilterTxnTSEnd" : {
                        "end" : "$end"
                    }
                }
            ]
        }
    }
}
EOF
)
    echo "base64:$flt"
}

Examples

Get reports for all transactions between 2019-01-15 10:00 and 15:30 on TZ=02:00

tackler --config journal/conf/tackler.toml --api-filter-def \
   $(time_span_filter 2019-01-15TT10:00:00+02:00  2019-01-15T15:30:00+02:00)

Filter:
  AND
    Txn TS: begin 2019-01-15T10:00:00+02:00
    Txn TS: end   2019-01-15T15:30:00+02:00

Filter for time window

Below is definition of time based windowing filter using above time_span_filter. This utilizes natural language support of date-command and above defined time_span_filter.

time_window_filter () {
    local ts1=$(TZ=Z date --date=$1 --iso-8601=s)
    local ts2=$(TZ=Z date --date="$ts1 $2" --iso-8601=s)

    local begin=$(echo -e "$ts1\n$ts2" | sort -n | head -n1)
    local end=$(echo   -e "$ts1\n$ts2" | sort -n | tail -n1)

    time_span_filter "$begin" "$end"
}

Examples

Transaction data from last 5 years:

tackler --config journal/conf/tackler.toml --api-filter-def \
   $(get_window_filter "2019-01-01" "-5 years")

Filter:
  AND
    Txn TS: begin 2014-01-01T00:00:00Z
    Txn TS: end   2019-01-01T00:00:00Z
...

Transaction data from last 30 days:

tackler --config journal/conf/tackler.toml --api-filter-def \
   $(get_window_filter "2019-01-15" "-30 days")

Filter:
  AND
    Txn TS: begin 2018-12-16T00:00:00Z
    Txn TS: end   2019-01-15T00:00:00Z
...

Transaction data for Q1/2018:

tackler --config journal/conf/tackler.toml --api-filter-def \
   $(get_window_filter "2018-01-01" "+3 months")

Filter:
  AND
    Txn TS: begin 2018-01-01T00:00:00Z
    Txn TS: end   2018-04-01T00:00:00Z
...

Reporting

Ordering of transaction is done by comparing time, code, description or uuid, in that order.

If uuid is not provided and ordering is not clear by other fields, then transaction ordering is undefined for that journal.

When truly stable reporting output is needed (especially for Register and Identity reports), then either transactions must have either uuid or unique time, code or description.

Selecting reports and exports

Produced reports can be selected either by configuration or CLI options:

--reports report1 report2 …: Valid options are: balance, balance-group, register

Produced exports can be selected either by configuration or CLI options:

--exports export1 export2: valid options are equity and identity

Configuring used output scale of reports

Report output scale (e.g. count of decimals) can be set globally. When values are truncated based on max scale setting, used rounding mode is HALF_UP.

Example of scale settings:

[report]
scale = { min = 2, max = 4 }

See tackler.toml full documentation.

Selecting accounts for reports

Accounts can be selected for reports either by setting global report.accounts (conf-setting and command line) setting or with report specific selector.

Default selection for reports is "all accounts" and it can be done with empty setting.

See Balance and Balance Group for details how account selectors affects reports.

Command line example:

--accounts "Assets(:.*)?" "Expenses(:.*)?"

All accounts:

--reporting.accounts ""

Configuration example:

[report]
  accounts = [ "Assets(:.*)?", "Expenses(:.*)?" ]

All accounts

[report]
  accounts = [ ]

If There are no accounts matched for report then report’s sub-section is not printed / outputted at all (balance Group, register report).

Balance Group Report and GroupBy

Balance Group report is like Balance report, but it will produce several sub-reports for group of transactions. Typical examples are Balance report over month and Balance Group report by weeks, or Balance report for week and Balance Group report based on iso-week-date or plain date.

Criteria could be: year, month, date, iso-week, iso-week-date

GroupBy is set by configuration (tackler.toml).

Output

--output.dir <directory>: will print reports to separate files, which are located in speficided directory.
--output.prefix <filename-prefix>: prefix to be used for individual report files..

Actual file names will be:

For reports:

<directory>/<prefix>.bal.txt: Balance report
<directory>/<prefix>.balgrp.txt: Balance Groups report
<directory>/<prefix>.reg.txt: Registry report

For exports:

<directory>/<prefix>.equity.txn: Equity report
<directory>/<prefix>.identity.txn: Identity report

Exports are special reports, which are valid input for Tackler.

Accounting Auditing and Assurance

See document Accounting Auditing and Assurance for information how Tackler reports could support accounting auditing and assurance actions.