Index

BkperApp GSTests status

BkperApp is a Google Apps Script library for bkper.

It works the same way your favorite Google Apps Script library works, like CalendarApp, DocumentApp, SpreadsheetApp etc, and it is safely authorized using OAuth2 protocol:

BkperApp overview

The Sheets, Forms and Docs Add-ons were built on top of the BkperApp library.

Authorization

To authorize the library, you just need to run the OAuth2 flow only once per account. This can be easily done when you install any Add-ons, or by clicking and running this authorization script

Setup

This library is already published as an Apps Script, making it easy to include in your project. To add it to your script, do the following in the Apps Script code editor:

  1. Click on the menu item "Resources > Libraries..."
  2. In the "Find a Library" text box, enter the project key "My8jgp9C1MEeWVxuYNppyFgoOxUd2qb-3" and click the "Select" button.
  3. Choose a version in the dropdown box (usually best to pick the latest version).
  4. Click the "Save" button.

Open a book

To start interacting with bkper, you should open a book by calling openById function, passing the id of the Book. This is the same parameter found on the URL accessed on bkper.com:

bookId

Create Accounts

To create an account you need to call the method createAccount with a name and optionally a group and description:

function createAccount() {

  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgPLoqb8KDA");

  book.createAccount("Some Customer", "Receivables", "A description");

}

The type of account will be determined by the type of others Accounts in same group. If not specified, the type ASSET will be set.

If all other accounts in same group is in another group, the account will also be added to the other group.

Record Transactions

You can record a Transaction by a simple text, the same way you record on main web interface:

function recordTransaction() {

  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  book.record("#gas 63.23");

}

When run recordTransaction function you should see the record appearing on the bkper screen:

Recording

You can also record transactions in batch by passing an Array of strings as the record method parameter:

function batchRecordTransactions() {

  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  var transactions = new Array();

  transactions.push("#breakfast 15.40");
  transactions.push("#lunch 27.45");
  transactions.push("#dinner 35.86");

  book.record(transactions);

}

The above code will send all records in a bulk. Very useful for importing large amount of data without the risk of reaching script limits.

Query Transactions

Each book is a large database and every interaction is done in terms of queries. Everytime you "select" an Account by clicking on left menu at bkper.com, you are actually filtering transactions by that Account.

Every query is shown in the search box on top of the page:

Query

When you search transactions, the search method returns an TransactionIterator to let you handle potentially large datasets:

function queryTransactions() {

  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgKCtg6MLDA");

  //Search returns an interator to deal with potencial large datasets
  var transactionIterator = book.search("acc:'Bank' after:01/04/2014");

  while (transactionIterator.hasNext()) {
    var transaction = transactionIterator.next();
    Logger.log(transaction.getDescription());
  }

}

Run the queryTransactions function, exchanging your bookId, with the same query, check the log output and you will see the same descriptions:

Search log

List Accounts Balances

You can access all Account objects, and query its balances, in a way similar to the left sidebar:

function listAccountBalances() {
  //Open the book
  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  var accounts = book.getAccounts();
  for (var i=0; i < accounts.length; i++) {
    var account = accounts[i];
    if (account.isPermanent() && account.isActive()) {
      Logger.log(account.getName() + ": " + account.getBalance());
    }
  }
}

Query Balances over time

it is very easy to query balances of Accounts and #hashtags over time, getting period and cumulative balances. Balance queries are used in bkper.com to generate chart reports:

Balance Queries

You can easily run balance queries on your script, by calling the function getBalanceReport, like the example bellow:

/**
Deploy as web app to get the generated Charts
*/
function doGet() {

  //Open the book
  var book = BkperApp.openById("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgKCtg6MLDA");

  //Query for balances
  var report = book.getBalanceReport("= group:'Expenses' group:'Incomes' after:01/2014 before:02/2014");

  //Create data table builder
  var dataTableBuilder = report.createDataTable().setBalanceType(BkperApp.BalanceType.TOTAL);

  //Create chart
  var chartsDataTable = dataTableBuilder.buildChartDataTable();
  var pieChart = Charts.newPieChart().setDataTable(chartsDataTable).build();
  var tableChart = Charts.newTableChart().setDataTable(chartsDataTable).build();

  //Add to UI
  var ui = UiApp.createApplication();
  ui.add(pieChart);
  ui.add(tableChart);

  return ui;

}

Exchange the book id and the query, deploy and run the script as a web app, and you will get a report like this live example.

Samples