Introducing Hooks 🪝

[nielsmaerten]

Customize ynab-buddy with Our New Beta Feature

Hey everyone,

I'm excited to introduce the powerful new Hooks 🪝 feature in ynab-buddy. The Hooks feature, now in beta, helps you work around quirks in your bank's transaction format by customizing ynab-buddy's behavior using your own code.

Why Hooks?

Bank transaction formats come in a huge variety. Adding rules and exceptions for every bank isn't sustainable. That's where Hooks come in! They offer:

• Flexibility to handle different bank formats
• Customization using your own code
• A sustainable solution for a generic tool like ynab-buddy

How Hooks Work

Hooks let you tap into the import process at various points, such as parsing, validation, and sending data to YNAB. For example, my own bank fills the 'memo' field with loads of semi-structured data. There's useful information in there, but also lots of junk. So: I wrote a hook to clean up the memo field before it gets sent to YNAB, keeping my account's history nice and tidy 🧹.

Getting Started with Hooks

1. Download the latest version of ynab-buddy:
   • Run npm i -g ynab-buddy@latest if you're using npm
   • Or, download it from the releases page on GitHub
2. Find the example hooks file here
3. Customize the example hooks file to your needs
4. Copy the customized hooks file to the same folder as your config file

Give Hooks a try and let us know your experiences and questions in this thread!

Happy budgeting! 🎉

[sprucas]

@ Niels
can i use the Hooks file to duplicate a column in my source CSV to two columns in my YNAB CSV?
eg a column has memo field and I want to use the contents for the Payee and the Memo field at the same time
sprucas

[nielsmaerten]

Hi spucas,
Yes, that should be possible. You probably want to use the onTransaction hook for this:
https://github.com/nielsmaerten/ynab-buddy/blob/main/assets/config/hooks.js#L98

This function runs for every transaction that's about to be sent to YNAB.
Something like this should do the trick:

function onTransaction(transaction, record) {
  transaction.memo = record.columnWithTheMemo;
  transaction.payee_name = transaction.memo; 
  return transaction;
}

[sprucas]

Thanks Niels
Does the hooks apply to all files being processed, or only certain files?
Luke

[nielsmaerten]

Hooks apply to all files that pass through ynab-buddy. There's currently no way of selectively applying hooks to only certain files.
But you might be able to determine what kind of file you're working with by inspecting the record object. For example:

function onTransaction(transaction, record) {
  // If the record has a column named "Account #", then it's an amex file:
  if (record["Account #"] !== undefined) {
    // These changes should only be applied for amex files:
    transaction.memo = record.columnWithTheMemo;
    transaction.payee_name = transaction.memo; 
  }
  return transaction;
}

[sprucas]

I'm playing around with hooks.js and trying to refer to a column in the record. Noticed something
In the parser for a bank file I make this configuration

columns: [date, amount, account-number, skip, transaction-type, memo, skip, skip, payee]

When I look at the console.log with hooks enabled, it looks like columns are

columns: [
    'date',  'amount',
    '__2',   '__3',
    '__4',   'memo',
    '__6',   '__7',
    'payee'
  ]

Am I allowed to use custom labels in the config.yaml?
I'd like to be able to say where record[account-number] = 12345678, then do something

Would be cool if my custom labelling of the columns in the csv parser came through automatically
Luke

[sprucas]

hacked my way around it and got the output i want - hooks is pretty powerful > thank you!!

[nielsmaerten]

It's been a few years since I worked on that code, but if I remember correctly it does the numbering thing because some of the more exotic bank-formats would trip up code downstream. (https://github.com/nielsmaerten/ynab-buddy/blob/main/src/lib/parser.ts#L126) 😄

Hence why it's only keeping a few reserved column names, and renames the others. That said: the name is always two underscores followed by the column index (starting at 0).
So as long as you know the number of the column the data you need is in, you should be able to get it out ;)

[sprucas]

yeah thats what i did in the end. thank you