recommends Bkper.
data entry. tax calculations. financial reports. any bookkeeping workflow.

Automate

Customize with Apps and Bots to help you on the hard work.

Overview

This Documentation includes guides, tutorials and references for you to get start building your custom solutions.

Bkper is in constant evolution, so you can check the changelog for new releases and deprecations and you can also check the platform status anytime.

Apps apps

Apps can be as simple as opening a url in the book context or as complex as a complete Add-on with business logics.

They are interactive solutions that can run independently and integrate to third party solutions.

Apps can also run upon events in the Books, acting as Bots working on behalf of users who installed it.

Menu

Apps can add a menu option on your Bkper Book, more precisely on Transactions page, so you can insert external links on the Book, to open any url on the Book context.

Once you install the application of type menu-app, a new menu item will appear in your Book:

Bkper App Menu Item

The app opens in a popup in the context of the book:

Bkper App Menu Popup

The url can dynamically be composed at the time user open the menu, by replacing the expressions ${xxxx} with the contextual information of the Book. Example:

menuUrl: https://my.link.com/bookId=${book.id}&query=${query}

Once user click the More menu button, the menu url will become:

https://my.link.com/bookId=xxx&query=yyy

Where xxx is the current Book id and yyy is the current query being executed.

For reference of the accepted expressions see comments in bkper.yaml.

Creating a new App

  1. On the app.bkper.com > Automations > Apps menu, click add to create a new App:

    Creating a new app

  2. If not done yet, install the Bkper Developer Github App.

  3. Insert a Repository name, Description (optional) and choose a repository visibility. Then click Create repository from template:

    Repository visibility

  4. Your app will appear on the Apps Menu:

    App

  5. Once your app is live, you can go to GitHub to edit its name, the description, logo, menurl, etc.

    App

Bots adb

Bots are a specialized kind of App that react to events from your Books.

Bkper Bots

A Bkper Bot can, for example, calculate taxes on transaction posting, convert currencies on transaction checked or post a message to Slack on comment created.

Bot agents

Bots run on behalf of the user who installed it, and the agents are identified in the transactions and activities list:

Bkper Bot Agents

Bot responses

The bot responses are registered in the activity which started the bot call and can be viewed and replayed by clicking on the response at the bottom of the activity:

Bkper Bot Responses

A Bkper Bot is authenticated via OAuth2, requiring a standard Cloud Platform project

GAS Bot

The standard Bkper Bot runs on Google Apps Script infrastructure, making authenticated calls to remote Google Apps Script functions upon events on the Bkper Books, on behalf of the user who installed the bot.

You can start building your own GAS bot by installing the Bkper Developer GitHub App and using the Bkper Bot Template repository.

GCP setup

GAS setup

Bot development

The Bot runs in Development Mode when executed by the developer of the app, so the last saved code version of the script is executed when running by the developer.

Any trigger function return or error will be shown as the Bot response:

Bkper Bots Errors

You can click the bot response to replay failed executions.

If you return an html snippet, with a link for example, it will be rendered in the response popup.

If you want to avoid recording the reponse, simply return false from your trigger function.

Learn more about development on Apps Script on BkperApp development

Bot deployment

Once the bot is developed, it should be released to users in a stable version, and make sure this version does not break when working on the code after the bot is already running for users.

To do so, Google Apps Script platform provides a mechanism called Deployments.

Bot installations use the Deployment ID especified in the bkper.yaml.

You can find the sDeployment ID in the Apps Script console:

Apps Script Deploy from Manifest

Apps Script Deployment ID

Copy and paste the ID into deploymentId property in bkper.yaml to specify which Deployment to use.

A same Deployment can run different versions of the script, so:

  • Non breakable changes to code should be released in the same Deployment, rolling out to all user who already installed the Bot.

  • Breakable changes to code should be released in another Deployment to make sure not to break the execution for users who already installed the Bot.

GitHub App build

The Bkper Developer GitHub App helps you create and manage Apps and Bots.

It works by synchronizing your GitHub repositories with the Bkper Automations portal, creating one App or Bot from each repository containing the bkper.yaml in the root folder:

Bkper Developer GitHub App

It reads the repository Name, Description, Website and README to build your Apps and Bots.

Bkper Developer Installation

  1. On the app.bkper.com > Automations > Apps menu, click add for the first time:

    Creating a new app

  2. Choose your Github account.

    Github account

  3. Select All repositories so the Bkper Developer Github App will watch all repositories looking for the bkper.yaml configuration file.

    Repository

  4. After installed, and on all next clicks on the add button from automations portal, you will be redirected directly to the create your first Bkper App flow.

Identification

App Owner

The App owner is the user who installed the GitHub App. To properly identify the App ower, the GitHub App installation flow must be initiating through the add to create a new App, like previously explained.

All Apps and Bots created by a given installation will have its owner set by the one who installed the GitHub App.

App Developers

GitHub allows developers to collaborate to projects, other than the one that installed the GitHub App.

If you are the App owner, you already have access to the App and do NOT need to be identified as developer.

In case you collaborate in a GitHub project and you are not the App owner, Bkper uses the commit email address to identify a developer of the App.

  • The commit email address should be the same email you use to login on Bkper.
  • The last identified developer to commit will be set as the current developer of the App/Bot.
  • The vpn_key button to set App/Bot secrets will appear only for the developer or owner of the App/Bot.

To allow GitHub to use your email address when performing web-based Git operations, access the Emails settings page and unselect the option Keep my email addresses private:

Github account

To set your commit email address on command line Git operations, please follow the GitHub help article.

bkper.yaml

The Bkper Developer GitHub App watch your repositories looking for the /bkper.yaml file in the root folder and use it to configure your Apps and Bots.

Reference:


name: # The name of the app or bot. If none set, the GitHub repository name will be used.
logo: # Set your logo url from public host. Best fit 200x200 px. Use https:// 

# By default the App will be available to your user, or all users of your G Suite domain.
# Additionally you can yhitelist users you want this app to show up:
whitelist: >
    someemail@somedomain.com
    anotheremail@somedomain.com



# Your app menu url. Accepted expressions:
               # ${book.id} - the current book id
               # ${book.properties.xxxxx} - any property value from the current book
               # ${transactions.query} - the current query being executed on transactions list
               # ${transactions.ids} - the ids of selected transactions, splitted by comma
               # ${account.id} - the current account being filterd
               # ${account.properties.xxxxx} - any property value from the current account being filtered
# Example:
menuUrl: https://app.bkper.com/b/#transactions:bookId=${book.id}
menuText: # The context menu call to action. If none set, the repository name will be used.
menuPopupWidth: 500 #width in pixels. If none set, the popup width will be 80% of screen width.
menuPopupHeight: 300 #height in pixels. If none set, the popup height will be 90% of screen height.

#################### BOT ####################
apiVersion: v2 # The version of the payload. Only v2 available for now.

#################### Bot Aut ####################

clientId: # The Client ID from GCP project Web Application OAuth Credential

# The OAuth scopes used by the Google Apps Script - found at File > Project Properties > Scopes
scopes: >
    https://www.googleapis.com/auth/userinfo.email
    https://www.googleapis.com/auth/script.external_request


#################### GAS Bot ####################

scriptId: # The Google Apps Script ID

# The Google Apps Script trigger functions
triggers: >
    onTransactionPosted
    onTransactionChecked
    onTransactionUnchecked

deploymentId: # The Google Apps Script API Deployment ID

Examples

Bkper App Template - Template repository for creating new Bkper Apps.

Bkper Bot Template - Template repository for creating new Bkper Bots.

Sales Tax Bot - Bot to calculate VAT, GST and other sales taxes based on the transaction amount.

Bkper Add-on for Google Sheets - Google Sheets Add-on to extend Bkper features, import/export data and run custom formulas.

Publishing

If you are interested in publishing your App or Bot to all users, please contact us at support@bkper.com

Libraries

Those are the Google Apps Script libraries we use to build our own Apps and Bots. Its a set of well tested and documented libs you can use own your own projects:

  • BkperApp - The Google Apps Script library to access the Bkper API in a secure and simple way.

  • HttpRequestApp - Fluent interface for Google Apps Script Url Fetch Service, to simplify HttpRequest building and 3rd party API integrations.

  • ExchangeApp - Google Apps Script library to exchange currencies based on updated rates.

Altough you can work on the Online editor really quickly, we strongly recommend clasp to develop locally with Typescript on VS Code editor, which is really powerfull and free, so you get:

  • Code Autocomplete
  • Contextual documentation
  • Compile time error checking
  • Code navigation - really helpful!
  • Calling hierarchy searching
  • Use of new javascript features such as classes, interfaces, arrow functions etc
  • Easier code redability
  • Automatic refactoring