💵 Biyete 🏦

Perrito Limpio con Signo de Dinero

++++

A simple Google Apps Script to parse Gmail messages related to Bank Notifications, Payment Bills, Deposits and other related areas. Then save those data to a Google Spreadsheet that you could use to track your finances.

https://ninjas.cl[image:https://img.shields.io/badge/Ninjas-CL-green.svg?style=flat-square[Ninjas.cl]] https://choosealicense.com/licenses/gpl-3.0/[image:https://img.shields.io/github/license/biyete/biyete.svg?style=flat-square[GPL v3]] http://commitizen.github.io/cz-cli/[image:https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square[Commitizen Friendly]] https://standardjs.com[image:https://img.shields.io/badge/code_style-semistandard-brightgreen.svg?style=flat-square[StandardJS]]

toc::[]

🚀 Environment setup

Requirements

https://script.google.com/home[Google Apps Script].
https://gmail.com[Gmail].
https://docs.google.com/spreadsheets[Google Spreadsheets].

Quick Installation

Step 1 - Configure Gmail

. Configure your Gmail https://support.google.com/mail/answer/6579?hl=en[inbox with filters] for each Parser, that would assign specific labels. . Ensure that you have some unread emails with the assigned label.

Each parser will have a designated label that you must configure first in your Gmail account This is the way to determine which Parser will be used to extract the data.

It's recommended to use a parent label named biyete to organize better your emails and labels related to biyete. Labels must follow specific format in order to work.

See each parser Labels.js file to know how to name your labels.

image:assets/screenshots/gmail.png[Gmail Labels]

Important: Be sure to create a good filter. Unwanted email may cause clutter.

Pro Tip

If you want to create filters more easily you can use the plus sign + to create an unique email address for each entity.

For example if you got a Netflix account, you can use example+netflix@gmail.com as your account email address. Its the same as writting example@gmail.com. Gmail ommits everything after the +. For Netflix it will be a valid and unique email address. For you, it means that now you can filter all emails that went to example+netflix@gmail.com they all will be from Netflix.

Step 2 - Create Spreadsheet

You can use the following link:assets/sheets/simple.xlsx{ext-relative}[Example Sheet].

. Clone it to your Google Drive. . Remove sample data. . Replace the url inside link:dist/biyete.gs{ext-relative}[biyete.gs]. ("sheetURL" constant).

Step 3 - Configure Google Apps Script

. Create a new project in https://script.google.com/home/my[Google Apps Script]. . Upload the (already configured) code inside link:dist/biyete.gs{ext-relative}[biyete.gs]. . Enable https://developers.google.com/apps-script/guides/services/advanced#enablingadvancedservices[Advanced Services] (Gmail and Spreadsheets). . Save and run (Need to give permissions first). . Configure a https://developers.google.com/apps-script/guides/triggers/installable[Time-driven trigger] to execute your custom script periodically.

(Optional) Script Config

. Configure parsers and actions (Select custom behaviours). . Compile a custom version. . Upload following step 3.

Selecting Parsers and Actions

For creating your custom selection of Parsers and Actions you just need to configure Parsers and Actions. import the ones you will need and recompile the script.

👩‍💻 Project explanation

This project was inspired by https://github.com/arecker/bennedetto[Bennedetto] and the lack of proper apps and technologies in Chilean banking systems. Also to automate financial tracking, and helping people organize their finances better.

Following https://bartwronski.com/2016/06/26/technical-weight/[Bart Wronski's advice] we look for simpler solutions and try to achieve the goals with the least technical weight. Normally a solution would be a huge app with lots of endpoints, https://en.wikipedia.org/wiki/Extract,transform,load[ETLs] and so on.

We tried to minimize using the available tools:

Banks normally do not have open endpoints to fetch data. But they send emails every time you purchase something or when you receive a deposit. These emails could be parsed with simple regex and sent to another place. Also other entities ("Netflix", "Spotify", etc) send a billing email that could also be parsed.

Gmail has Google Apps Scripts that let you read, program and control emails and interact with different services.

Google Spreadsheets is a wonderful place to store data and create custom dashboards. Also has Google Apps Scripts.

Finances need to be secure and transparent. So using Gmail and Spreadsheets we can have an easy to use, easy to configure, low cost and secure environment to execute this script and let you have total control over your personal data (No hidden nasties).

How does it work?

This script will fetch all the unread emails within a specific label. Will search for the special keywords and process their data. Then for every item found it will trigger actions. The default action is to store the results inside a specific SpreadSheet. Although you could configure new actions (Like sending the data to a REST API or similar). Finally the email will be marked as read.

Normally will process 30 threads of messages per execution. (Google Apps Scripts max time is 6 minutes).

image:https://user-images.githubusercontent.com/292738/87862933-70b26800-c923-11ea-9b0a-275ed636267a.png[Main Sequence Diagram]