Server API

This document explains how to embedded Tackler core and use it as a library in other systems.

Tackler operates on stream of immutable transactions and over this transaction stream (or sub-selection of it) it generates different reports.

Transaction stream is immutable and thread safe, and it is possible to make multiple reports over same set of txn data. Currently all transactions are held in memory.

Dependency settings for SBT are:

libraryDependencies += "fi.e257" %%  "tackler-core" % "version-number"

This is released on Maven Central Repository.

Reading transactions

Transactions can be read from three different sources

• From filesystem fs-storage (conf: tackler.core.input.fs)

• From Git git-storage (conf: tackler.core.input.git)

• Internally directly from string

All of these inputs produce transaction stream and metadata of that stream. This transaction set (txnData) can then be fed to different reports. See core → main → parser → TacklerTxns and it’s companion object’s helpers.

Filtering transactions

There is an option to filter transactions based on attributes of single transaction. See Transaction Filters for general information about these filters.

Transaction filter models are defined at api → TxnFilter. Actual filtering implementation is located in package: core → filter.

Filters are typically used via core → model → TxnData.filter method. See core → test → filter for examples of how to define and use transaction filters.

JSON decoding of transaction filters

Server API provides JSON decoding of transaction filters via Circe.

Below is an example of how filter can be created from JSON string:

import io.circe.parser.decode
import fi.e257.tackler.api.TxnFilterDefinition

val filterJsonStr = """{ "txnFilter": { "TxnFilterTxnCode" : { "regex" : "#123" } } }"""

val txnFilterDef = decode[TxnFilterDefinition](filterJsonStr)

// txnFilterDef: Either[io.circe.Error,fi.e257.tackler.api.TxnFilterDefinition] = Right(TxnFilterDefinition(TxnFilterTxnCode(#123)))

See core → test → filter → TxnFilterJsonTest for more examples of JSON decoding and encoding.

Generating reports

Reports are done in three steps:

1. Make settings for report (BalanceSettings)

2. Instantiate report maker (BalanceReporter)

3. Generate actual report (balRpt.jsonReport(txnData))

Consuming reports

See Client API how to use generated reports on client side.

Example of usage of Server API

There is test for server reporting api, which could be used as an example. With this test transactions are read internally from string, and then that txns stream is used to produce various reports.

Tackler’s CLI contains examples (git2Txns and paths2Txns) how to use FS or Git storage: cli → main → TacklerCli

Test cases for GIT input are located here: core → it → parser → TacklerTxnsGitTest

Complete test cases for Report API are located here: core → test → report → ReportApiTest