Verified Commit 2152659a authored by 35V LG84's avatar 35V LG84

tep-1010: user docs (txn geo loc + filters)

Signed-off-by: 35V LG84's avatar35V LG84 <[email protected]>
parent cc2bccb9
......@@ -13,7 +13,10 @@ Current published release is:
New features and changes in this release:
* link:https://tackler.e257.fi/docs/journal/format/#value-pos[Closing position with total amount (`=` syntax)]
* Support for link:https://tackler.e257.fi/docs/gis/[Geographic Information System (GIS)]
** See link:https://tackler.e257.fi/docs/gis/txn-geo-location/[Transaction Geo Location]
** See link:https://tackler.e257.fi/docs/gis/txn-geo-filter/[Transaction Geo Filter]
* Add support for Value Position with link:https://tackler.e257.fi/docs/journal/format/#value-pos[total amount (`=` syntax)]
==== Fixes
......
......@@ -171,19 +171,19 @@ Changes to identity export
== Documentation
* [x] xref:./readme.adoc[]: Update TEP index
* [ ] xref:../../README.adoc[]: is it a new noteworthy feature?
* [ ] link:../../CHANGELOG[]: add new item
* [x] xref:../../README.adoc[]: is it a new noteworthy feature?
* [x] link:../../CHANGELOG[]: add new item
* [x] Does it warrant own T3DB file?
** [x] update xref:../../tests/tests.adoc[]
** [x] update xref:../../tests/check-tests.sh[]
** [x] Add new T3DB file xref:../../tests/tests-XXXX.yml[]
* [ ] User docs
** [ ] user manual
** [ ] examples
* [ ] Developer docs
** [ ] API changes
*** [ ] Server API changes
*** [ ] Client API changes
* [x] User docs
** [x] user manual
** [x] examples
* [x] Developer docs
** [x] API changes
*** [x] Server API changes
*** [x] Client API changes
=== Postponed (PP) features
......
......@@ -3,7 +3,7 @@ GEM
specs:
addressable (2.6.0)
public_suffix (>= 2.0.2, < 4.0)
asciidoctor (2.0.3)
asciidoctor (2.0.9)
colorator (1.1.0)
concurrent-ruby (1.1.5)
em-websocket (0.5.1)
......@@ -57,7 +57,7 @@ GEM
rouge (3.3.0)
ruby_dep (1.5.0)
safe_yaml (1.0.5)
sass (3.7.3)
sass (3.7.4)
sass-listen (~> 4.0.0)
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
......
......@@ -25,6 +25,9 @@
- link: /docs/txn-filters/
- link: /docs/commodities/
- link: /docs/currencies/
- link: /docs/gis/
- link: /docs/gis/txn-geo-location/
- link: /docs/gis/txn-geo-filters/
- link: /docs/auditing/
- link: /docs/reliability/
- link: /docs/performance/
......
= Plaintext accounting with GIS
:page-date: 2019-05-05 00:00:00 Z
:page-last_modified_at: 2019-05-05 00:00:00 Z
:page-permalink: /docs/gis/
Tackler supports recording geo location with accounting journal and it can use that GIS data
for generating accounting reports.
See xref:./gis/txn-geo-location.adoc[Transaction Geo Location] for how to store geographic location with
accounting transactions, and xref:./gis/txn-geo-filters.adoc[Transaction Geo Filter] how to select transactions based
on that geographic information. Together these two features make it possible to do
accounting and reporting based on area and place.
[[use-cases]]
== Use cases for GIS data with plaintext accounting
Tackler supports also xref:./journal/format.adoc#timestamps[real timestamps] and not just dates with transaction data.
Combining GIS data and timestamps with accounting transactions creates all kind of new possibilities
for plaintext accounting. It could be travel journals, tracking outdoor activities,
to account farming related information or record forestry data.
There is no need to account only monetary things, so possibilities are pretty much endless what to do with GIS data.
= Transaction Geo Filter
:page-date: 2019-05-05 00:00:00 Z
:page-last_modified_at: 2019-05-05 00:00:00 Z
Transaction Geo Filters selects transactions which geographic location is inside Bounding Box defined by the filter.
Using location based transaction filters makes it possible to generate reports for certain geographic areas.
Currently supported filter geometry is bounding box.
See xref:txn-geo-location.adoc[Transaction Geo Location] how to record location data.
== Bounding Box
Used Bounding Box (BBox) definition is Y, X (lat, lon) based, instead of X, Y (lon, lat).
This is compatible with OpenStreetMap's link:https://wiki.openstreetmap.org/wiki/Overpass_API[Overpass API]
First coordinate pair is lower-left (south-west) corner of bbox and second is top-right (north-east) corner of bbox.
=== 2D BBox (Latitude, Longitude)
[horizontal]
BBoxLatLon:: south, west; north, east;
South:: min latitude
West:: min longitude
Nort:: max latitude
East:: max longitude
2D BBoxLatLon will ignore altitude, e.g. it will select 3D transaction if it fits 2D BBox.
If transaction doesn't have location information, it will not be selected.
==== 2D BBox JSON syntax
----
{
"TxnFilterBBoxLatLon" : {
"south" : 59.667,
"west" : 18,
"north" : 70.19,
"east" : 31.6
}
}
----
=== 3D BBox (Latitude, Longitude, Altitude)
[horizontal]
BBoxLatLonAlt:: south, west, depth; north, east, height;
South:: min latitude
West:: min longitude
Depth:: min altitude
Nort:: max latitude
East:: max longitude
Height:: max altitude
3D BBoxLatLonAlt will select only 3D transactions with altitude, e.g. it will not select any 2D transaction,
even if it fits 2D BBox.
If transaction doesn't have location information, it will not be selected.
==== 3D BBox JSON syntax
----
{
"TxnFilterBBoxLatLonAlt" : {
"south" : 59.667,
"west" : 18,
"depth" : -1444,
"north" : 70.19,
"east" : 31.6,
"height" 1324
}
}
----
== 180th meridian
BBox over 180th meridian is also supported, in that case bbox:west is max longitude and bbox:east is min longitude.
However, this is corner case around certain parts of Pacific, and if you do not live in Fiji, then bbox:west is almost
always min longitude and bbox:east is max longitude.
= Transaction Geo Location
:page-date: 2019-05-05 00:00:00 Z
:page-last_modified_at: 2019-05-05 00:00:00 Z
Tackler supports `location` metadata with transaction data and this makes it possible to record
location data for that transaction. This location data could be used later to select transaction
for reports or plot transactions on map. link:/docs/gis/#use-cases[Plaintext accounting with GIS]
has ideas for some use cases.
See xref:txn-geo-filters.adoc[Transaction Geo Filters]
for information how to select transactions based on location data.
== Geo Location Syntax
Transaction location is recorded by using `location` metadata field, and actual location is provided by geo URI.
----
2019-05-01 'Ice cream at Helsinki's market square
# location: geo:60.167,24.955,5
Expenses:Ice_cream 2.50 €
Assets:Cash
----
Supported geo URI scheme is simplified version of link:https://tools.ietf.org/html/rfc5870[RFC 5870]:
* Only coordinates (lat, lon, and alt) are supported
* Only supported Coordinate Reference System is WGS84 (EPSG:4326).
* Any of `p` (parameters) part of
link:https://tools.ietf.org/html/rfc5870#section-3.3[geo URI scheme]
is not accepted at all, including `u`,
and none of these can be present with location field's value.
.Supported geo-uri syntax
[horizontal]
geo-uri:: `geo` `:` <lat> `,` <lon> [`,` <alt>]
lat:: latitude
lon:: longitude
alt:: altitude
latitude:: `[ '-' ] DIGIT+ [ '.' DIGIT+ ]` (valid values: -90 ... 90)
longitude:: `[ '-' ] DIGIT+ [ '.' DIGIT+ ]` (valid values: -180 ... 180)
altitude:: `[ '-' ] DIGIT+ [ '.' DIGIT+ ]` (in meters)
......@@ -70,7 +70,7 @@ If compatibility with other systems is needed, then two spaces should be used.
| Dates and Timestamps
|
| [[timestamps]]
----
YYYY-MM-DD
YYYY-MM-DDTHH:MM:SS[.SSS]
......@@ -88,7 +88,7 @@ e.g.
2016-12-31T13:01:01+02:00
2016-12-31T13:01:01.123456789+02:00
----
| These are link:https://en.wikipedia.org/wiki/ISO_8601[ISO-8601] dates and times with nanosecond resolution.
| These are link:https://en.wikipedia.org/wiki/ISO_8601[ISO-8601] dates and times with up to nanosecond resolution.
* If time part is missing then `00:00:00` is used.
* If Offset is missing then offset based on xref:../tackler-conf.adoc[configured] timezone/offset is used.
......@@ -240,7 +240,7 @@ Currently opening position is valid input, but it is not used.
This is planned feature. See xref:../currencies.adoc[Currencies]
| Transaction metadata
| Metadata: UUID
|
----
2017-01-01 'Txn with UUID
......@@ -261,6 +261,16 @@ and "distributed transaction producers"-safe sort order is needed
for xref:../report-register.adoc[register report]
or xref:../export-identity.adoc[identity export].
| Metadata: Location
|
----
2019-05-01 'Txn with Location
# location: geo:60.167,24.955,5
Expenses:Ice_cream 2.12
Assets:Cash
----
| Optional xref:../gis/txn-geo-location.adoc[Geo Location for Transaction]
| Comments
|
......
= Git Storage Guide
:page-date: 2019-03-29 00:00:00 Z
:page-last_modified_at: 2019-04-22 00:00:00 Z
:page-last_modified_at: 2019-05-05 00:00:00 Z
Tackler has integrated and native support for link:https://git-scm.com/[GIT] version control system.
Tackler has integrated support for git as storage backend. This means that Tackler can include version metadata
directly to the generated reports, and generated reports are always made out of well known state of accounting data.
This means that tackler will process accounting data directly from Git repository, which could be "bare".
Point of history for accounting data could be selected by all normal Git's way of references, and
version metadata will be included directly to the generated reports. This also means that generated reports
are always made out of well known and well defined state of accounting data.
This provides one key of the immutable audit trail of used accounting data. This audit trail can be printed e.g.
on paper or transferred directly to accountant or escrow agent. See xref:../auditing.adoc[Accounting Auditing]
......
......@@ -47,7 +47,7 @@ Regardless of used sharding scheme, it is possible to group txns by different
`group-by` operators with xref:../report-balance-group.adoc[Balance Group] report.
[[shard-filters]]
== Using shards to select subset of transaction data
Selecting subset of transactions can be by using
......
......@@ -18,9 +18,9 @@ logical test sets to ensure that all logical code paths are covered.
At the moment, Tackler test coverage is better than *99.7%*.
Tackler has *84* tracked features. For those 84 features, tackler has
over *270* test cases, tackler-cli is executed over *140* times by test setup,
and results are verified by over *380* reference reports.
Tackler has *99* tracked features. For those 99 features, tackler has
over *500* test cases, tackler-cli is executed over *160* times by test setup,
and results are verified by over *400* reference reports.
Accounting Journal with size of *one hundred thousand* (1E5) transactions
is used with *unit tests*
......@@ -39,4 +39,3 @@ possible of overlapping tests and prevent duplicate test cases.
T3DB also provides reverse mapping from a test case back to the feature,
which is validated by that test case.
......@@ -55,10 +55,17 @@ then that transaction is not is not printed / outputted at all.
== Example reports
Below are links to example register reports with full auditing metadata.
Register report with location data:
* {repolink}/tests/audit/ok/audit-1E2-04.ref.reg.txt/[Register report with audit metadata]
* {repolink}/tests/audit/ok/audit-1E2-04.ref.reg.json/[Register JSON report with audit metadata]
Below are links to example register reports:
* Register reports with link:/docs/gis/[geo location information]
** {repolink}/tests/location/ok/basic-01.ref.reg.txt[Register report with Geo Location]
** {repolink}/tests/location/ok/basic-01.ref.reg.json[Register JSON report with Geo Location]
* Register reports with xref:auditing.adoc[audit metadata]
** {repolink}/tests/audit/ok/audit-1E2-04.ref.reg.txt/[Register report with audit metadata]
** {repolink}/tests/audit/ok/audit-1E2-04.ref.reg.json/[Register JSON report with audit metadata]
=== Example output of register report
......
......@@ -14,21 +14,25 @@ See following documents to get up and speed with Tackler.
* xref:docs/installation.adoc[Installation Manual]
* xref:docs/usage.adoc[Usage Guide]
== Daily usage
* xref:docs/journal/git-storage.adoc[Git Storage Guide]
== Advanced topics
* xref:docs/usage.adoc[Usage Guide]
* xref:docs/journal/git-storage.adoc[Version Control Storage Guide]
* link:/docs/gis/[Accounting with Geo Location (GIS)]
* xref:docs/txn-filters.adoc[Transaction filters]
* xref:docs/currencies.adoc[Currencies, shares ...]
== Examples
* xref:docs/examples/trimix-filling-station.adoc[Trimix Filling Station]
== Embedding Tackler
* xref:docs/server-api.adoc[Server API]
......
= Transaction Filters
:page-date: 2019-03-29 00:00:00 Z
:page-last_modified_at: 2019-03-29 00:00:00 Z
:page-last_modified_at: 2019-05-06 00:00:00 Z
Transaction stream can be filtered to select which transactions are part of reports and calculations.
Transaction stream can be filtered based on several attributes of single transaction.
If transaction is not included into stream and it is filtered out,
then all data regarding that transaction will not be used with any calculation.
It is also possible to filter transactions based on xref:journal/sharding.adoc#shard-filters[sharding scheme].
Transaction filters can be combined with logical `AND`, `OR` and `NOT` operations and
it is possible to create filter trees by combining logical filters and filters
......@@ -39,6 +40,7 @@ properties and attributes.
** Code
** Description
** UUID
** Geo Location
** Txn Comments
* Postings
** Account
......@@ -182,6 +184,46 @@ Txn UUID filter selects transactions which UUID is same as specified.
},
----
===== Geo Location
Transaction Geo Filters selects transactions which geographic location is inside Bounding Box defined by the filter.
See xref:gis/txn-geo-filters.adoc[Transaction Geo Filters] documentation for how these filters selects transactions.
.2D Bounding Box (Latitude, Longitude)
[source,json]
----
# BBoxLatLon will ignore altitude,
# e.g. it will select 3D transaction if it fits 2D BBox.
{
"TxnFilterBBoxLatLon" : {
"south" : <number: min latitude>,
"west" : <number: min longitude>,
"north" : <number: max latitude>,
"east" : <number: max longitude>
}
}
----
.3D Bounding Box (Latitude, Longitude, Altitude)
[source,json]
----
# BBoxLatLonAlt will select only 3D transactions with altitude,
# e.g. it will not select any 2D txn.
{
"TxnFilterBBoxLatLonAlt" : {
"south" : <number: min latitude>,
"west" : <number: min longitude>,
"depth" : <number: min altitude>,
"north" : <number: max latitude>,
"east" : <number: max longitude>,
"height" : <number: max altitude>
}
}
----
===== Txn Comments
Txn Description filter selects transactions which have a comment which matches specified regular expression.
......
......@@ -7,7 +7,7 @@ echo "<html><body></body></html>" > repo/tests/index.html
grep \
'{repolink}/' \
pages/features.adoc _docs/licenses.adoc _docs/auditing.adoc _docs/examples/trimix-filling-station.adoc _docs/json.adoc | \
pages/features.adoc _docs/licenses.adoc _docs/auditing.adoc _docs/examples/trimix-filling-station.adoc _docs/json.adoc _docs/report-*.adoc | \
sed -E '[email protected]*\{repolink\}/(.*)\[.*@\[email protected]' | \
while read f;
do
......
= Features
:page-date: 2019-03-29 00:00:00 Z
:page-last_modified_at: 2019-03-29 00:00:00 Z
:page-last_modified_at: 2019-05-05 00:00:00 Z
:page-permalink: /features/
* Tackler's xref:docs/reliability.adoc[all features are extensively tested]
* Native support for xref:docs/journal/git-storage.adoc[GIT based journal storage]
* Support for xref:docs/auditing.adoc[Accounting Auditing and Assurance]
* Support for xref:docs/commodities.adoc[Commodities] and xref:docs/currencies.adoc[Currencies]
* Support for link:/docs/gis/[Accounting with Geo Location (GIS)]
* Strict xref:docs/accounts-conf.adoc[account and commodity name validation] with Chart of Accounts
* Clean and simple xref:docs/journal/format.adoc[journal format]
* Multiple report and export types:
** xref:docs/report-balance.adoc[Balance], xref:docs/report-balance-group.adoc[Balance Groups] and xref:docs/report-register.adoc[Register] Reports
** xref:docs/export-equity.adoc[Equity] and xref:docs/export-identity.adoc[Identity] Exports
* Support for xref:docs/txn-filters.adoc[Transaction Filters]
* Supports UTF-8 characters in transaction data (
{repolink}/tests/parser/ok/par-02.ref.identity.txn/[descriptions],
{repolink}/tests/parser/ok/par-02.ref.reg.txt/[comments],
{repolink}/tests/parser/ok/id-chars-01.ref.identity.txn/[account names])
* Supports ISO 8601 timestamps with {repolink}/tests/core/ok/time-dst-01.ref.identity.txn/[timezones]
and {repolink}/tests/core/ok/time-nano-01.ref.identity.txn/[nanosecond] resolution
* Supports xref:docs/journal/charsets.adoc[wide range of UTF-8 characters, scripts and languages]
* Supports ISO 8601 xref:docs/journal/format.adoc#timestamps[timestamps with timezones and nanosecond] resolution
* Text and xref:docs/json.adoc[JSON] output formats for reports
** xref:docs/server-api.adoc[Server API] for embedding Tackler core
** xref:docs/client-api.adoc[Client API] for JVM and JS environments
* Has good performance with xref:docs/performance.adoc[large transaction set]
** Tackler is {gitlink}/perf/results/perf-hw00.adoc[tested up to one million (1E6)] transactions
** Tackler can parse and process {gitlink}/perf/results/readme.adoc[56000 txn/s] on Quad Core system
* link:../docs/[Extensive documentation]
* link:/docs/[Extensive documentation]
......@@ -31,7 +31,7 @@ permalink: /
<p>
<ul>
<li>Journals with millions of records</li>
<li>1:3 features to tests ratio</li>
<li>1:5 features to tests ratio</li>
<li>Test coverage &gt;99.7%</li>
</ul>
</p>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment