recommends Bkper.
data entry. tax calculations. currency conversions. 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 build your own solutions in the shape of Apps and/or Bots to customize and extent your business workflows on Bkper.

Bots are triggered by events in your books giving you the power to greatly reduce the labour of repetive low value and fault sensitive tasks whereas Apps empower collaboration from simple enhancements to sophisticated business understanding.

Under constant evolution, you can keep up with new releases and deprecations on our changelog and check for the platform status at anytime.

Apps apps

Apps can be as simple as opening a url in the book’s 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.

Listing

All Bkper Apps are listed on the Automations Portal accessed at app.bkper.com > Automations > Apps menu.

Each App has its own page, logo, site and additional details, like bellow:

Bkper Apps Listing

The App listing and settings are managed using the Bkper GitHub App

Context Menu

Apps can add context menus items on the Transactions page More menu in your Books. This allows for you, to open dynamically build urls with reference to expressions of a Book’s context.

Once you install an App with a menu configurations, a new menu item will appear in your Book:

Bkper App Menu Item

The popup that opens carries the particular context of that book at that moment:

Bkper App Menu Popup

On selecting the new option from the more menu the url can be composed dynamically, by replacing expressions ${xxxx} with 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.

Agents

Each App can define an Agent for acting on behalf of the user, and its activities and transactions are identified by its logo and name on Bkper:

Bkper App Agents

The App agent is identified by the API Key when calling the API.

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 and readme, then all changes will be automatically sync upon push to the GitHub repo by the GitHub App.

Additional settings, such the App logo url is set in the bkper.yaml

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.

Check out Tax Bot or Exchange Bot examples to learn more.

The Event object

All bot triggers function, such as onTransactionChecked(event), receive an Event object in the following format:

    {
        /** The id of the Book associated to the Event */
        bookId?: string;
              
        /** The user in charge of the Event */ 
        user?: {

            /** The user public avatar url */
            avatarUrl?: string;

            /** The user display name */
            name?: string;

            /** The Bkper username of the user */
            username?: string;
        };

        /** The Event agent, such as the App, Bot or Bank institution */ 
        agent?: {

            /** The agent id */
            id?: string;

            /** The agent logo. Public url or Base64 encoded */
            logo?: string;

            /** The agent name */
            name?: string;
        };

        /** The creation timestamp, in milliseconds */
        createdAt?: string;

        /** The event data */
        data?:{
            
            /** 
             * The object payload. It will depend on the event type. 
             * 
             * For example, an ACCOUNT_CREATED type will receive an Account payload.
             */
            object?: Any;

            /** The object previous attributes when updated */
            previousAttributes?: {
                [name: string]: string;
            };
        };

        /** The unique id that identifies the Event */
        id?: string;

        /** The resource associated to the Event */
        resource?: string;

        /** The type of the Event */
        type?: "FILE_CREATED" | "TRANSACTION_CREATED" | "TRANSACTION_UPDATED" | "TRANSACTION_DELETED" | "TRANSACTION_POSTED" | "TRANSACTION_CHECKED" | "TRANSACTION_UNCHECKED" | "TRANSACTION_RESTORED" | "ACCOUNT_CREATED" | "ACCOUNT_UPDATED" | "ACCOUNT_DELETED" | "QUERY_CREATED" | "QUERY_UPDATED" | "QUERY_DELETED" | "GROUP_CREATED" | "GROUP_UPDATED" | "GROUP_DELETED" | "COMMENT_CREATED" | "COMMENT_DELETED" | "COLLABORATOR_ADDED" | "COLLABORATOR_UPDATED" | "COLLABORATOR_REMOVED" | "BOOK_UPDATED" | "BOOK_DELETED";
    }

The Event payload is the same exposed in the REST API and, if your are using Typescript, you can add the bkper-api-types package to your project and set the bkper.Event type on your trigger functions, like bellow:

function onTransactionChecked(event: bkper.Event)

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 Deployment 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 listing:

App

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: v3 # The version of the payload. Default to v3. Legacy v2.

#################### 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
    onTransactionUpdated
    onTransactionDeleted
    onTransactionRestored
    onAccountCreated
    onAccountUpdated
    onAccountDeleted
    onGroupCreated
    onGroupUpdated
    onGroupDeleted

# The properties scheme used by the App/Bot. The scheme is used to set properties autocomplete and simplify the setup.
bookProperties: > 
    key_a
    key_b
groupProperties: > 
    key_a
    key_b
accountProperties: > 
    key_a
    key_b  
transactionProperties: > 
    key_a
    key_b            

deploymentId: # The Google Apps Script API Deployment ID

REST API settings_ethernet

The Bkper REST API is the interface for Apps and Bots to interact with the Bkper Books having users sercurely authenticated under OAuth2 protocol.

Note: The REST API is the underlying connection interface behind the BkperApp library.

The API is built on Swagger OpenAPI and Google API Discovery specifications:

You can use these specification documents to generate client libraries using open source tools such as OpenAPI generator or Google APIs code generator, in the language of your choice.

To call the API directly from the browser, you can use the discovery document with the gapi.

If you are using Typescript, we keep an updated type definitions package on npm you can easily add to your projects for autocomplete and contextual documentation:

Endpoints Portal

We provide a REST API Developer portal at api.bkper.com so you can check out the endpoints paths and payload formats, and try the API live:

REST API Deeveloper portal

To see the API in the portal, you must join Bkper on Google groups.

Once you join the group, you can access api.bkper.com and the API app.bkper.com will be available for you.

Enabling the REST API

A Google Cloud Project project is required in order to use the Bkper REST API. Follow the steps to get started with the Bkper REST API:

Bkper API key

NOTE: Do not store the API Key on your code to avoid leaks, potentialy leading to quota theft. See securing an API key best practices.

For Google Apps Script, you can use the Script Properties. To store it, open the online editor, File > Project properties > Script properties.

Authentication

The Bkper REST API uses OAuth 2.0 protocol with the email scope to authenticate users.

You should send a valid OAuth2 Bearer token in the Authentication header of the API http requests.

Server side Google Apps Script example

For Google Apps Script you can use the built in ScriptApp.getOAuthToken() in your code to access the OAuth2 access token the script has acquired and pass it in the Authorization header of a UrlFetchApp.fetch() call, like bellow:

function listBooks() {
  var options = {
    headers: {
       Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
     }
  };
  Session.getActiveUser().getEmail() // Ensure email scope used
  var url = 'https://app.bkper.com/_ah/api/bkper/v3/books?key=' + PropertiesService.getScriptProperties().getProperty('API_KEY'); // Store the key on File > Project properties > Script properties
  var content = UrlFetchApp.fetch(url, options).getContentText();
  Logger.log(content)
}

The ScriptApp.getOAuthToken() should work on most cases, but, if you work on some restricted environment, such as Google Sheets custom functions, you can manage the tokens with the OAuth2 for Apps Script library. See the bkper-sheets Authorizer for a detailed example.

Client side javascript example

For client side javascript, you should configure the OAuth consent screen and use the google-api-javascript-client initializing with our discovery document, your API key, Client ID and the email scope, like bellow:

<html>
  <head>
    <script src="https://apis.google.com/js/api.js"></script>
    <script>
      function start() {
        // Initializes the client with the API key and the Bkper API.
        gapi.client.init({
          discoveryDocs: ['https://app.bkper.com/_ah/api/discovery/v1/apis/bkper/v3/rest'],
          apiKey: 'YOUR_API_KEY',
          clientId: 'YOUR_CLIENT_ID',
          scope:'email'
        }).then(function() {
          // Executes an API request, and returns a Promise.
          // The method name `bkper.books.list` comes from the API discovery.
          return gapi.client.bkper.books.list();
        }).then(function(response) {
          var books = response.result.items;
          document.getElementById('results').innerText = JSON.stringify(books, null, 4);
        }, function(reason) {
          console.log('Error: ' + reason.result);
        });
      };
      // Loads the JavaScript client library and invokes `start` afterwards.
      gapi.load('client', start);
    </script>
  </head>
  <body>
    <div id="results"></div>
  </body>
</html>

NOTE: Don’t forguet to restrict your key only to http referers your project will run

Metrics

Once you enable and start using the API, you can check out detailed metrics on the GCP Console, of the API calls for your project:

REST API Deeveloper portal

The metrics dashboard provides you with information about endpoint calls, latency and errors, giving a good overview of the project integration health.

Quota

The quotas dashboard provides details of the current default and quota exceeded errors.

The current default quota 180 requests per minute, per project. If you need to increase the quota, please get in touch so we discuss your case.

Examples

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

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

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

Exchange Bot - Bot to convert transaction amounts between Books based on updated exchange rates, and calculate gains & losses.

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

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

Libraries

Those are the Google Apps Script libraries we use to build our own Apps and Bots. It’s a set of well tested and documented libraries you can use on 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.

Publishing

By default, the App or Bot you create is visible only for you or your company, in case of G Suite domains.

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