Firefly III Plugin System aka Developer quick start

[dreitakter]

Support guidelines

• I've read the support guidelines
• My request is not listed as a very good idea, but unfortunately...
• I've used the search and this has not been requested before.

Description

First of all I am very new to Firefly III and I am really impressed by you and the work you have done.
I have started two weeks ago to use Firefly and feel much more comfortable about my fincances now.
Thank you really much for this great tool!

I have written tons of rules to automate as much as possible but there are a few things that wont work with the Rule-Engine or Recurring-Transactions.

Here are some things I want to do in future:

1. automatic Split-Transaction with values from transaction description
   In germany we can withdraw money from a store if we pay with bank-card. The cash-amount from the withdraw is in the transaction description. Now I want to do a split into cashaccount and storeaccount. Manually this works perfectly fine.
   OR
   In the transaction description of a liability is the amount of interest charges and redemption but these values are different every month because the amount is fixed but the redemption grows... Now I want to do a split into liabilityaccount (redemption) and commerzbank (interest charges). Manually this work perfectly fine.

2. automatic transaction check based on the receipt of the store
   If I pay with my bank-card in a store I get an receipt but the corresponding transaction in my bank-account will appear 2-7 days later. As soon as the transaction appears I have to search for the corresponding receipt and in my case I manually delete the tag "check receipt" which was added with a rule. Now I want to take an image from the receipt with scanbot, upload it to my nextcloud into a specific folder with a unique name for example "2023-11-30-EDEKA-23.44.pdf". At creation of the transaction a webhook is fired and if the description contains "2023-11-30" and "EDEKA" and amount = "23.44" then the tag "check receipt" will be removed and the file will be uploaded into the transaction.

After reading very much posts of you I think I have now a good understanding what you want to do and what you dont want to implement in Firefly III. What is perfectly fine for me, because you cannot cover every crazy idea of every user out there :)

Solution

I think the webhooks in combination with the API is the perfect way of communication between Firefly III and a "Plugin".
I am a software developer myself and want to contribute to this great project without using PHP (sorry, not my favorit language).
What I want to achieve is that a developer like me can almost instantly start to write a new "Plugin" for Firefly III without setting up all the necessary stuff like a develop-environment, wrapper for api-calls, listeners for webhooks, ...

My first idea is a "template-docker-container" with includes the following things:

• Ready to use develop-environment ideally within the browser
• Service-Class for API-Calls (already defined types ...)
• Service-Class for Webhook-Listeners (already defined types ...)
• Example-Class with usage-examples

Do you think this is possible? Do you have a better idea for this? What programming-language will be best to use? I thougt python could be a good starting point.

What are alternatives?

No response

Additional context

I dont have a ready to use solution. Its only an idea which I want to discuss.

[JC5]

Hey, thanks for the compliments!

That's a great idea, and it could work in any language. For your interest, I am using webhooks myself to solve a similar problem with my mortgage: the original transaction is deleted and a new split transaction is submitted to Firefly III. But this script is indeed in PHP 😉 and part of a number of webhooks I'm already hosting myself.

When it comes to development tools / frameworks, I would suggest to start with a webhook (or multiple) that works for you, and then start working on a development framework.

As far as development frameworks are concerned, it may even be possible to do this using standard Python libraries and some glue. A standard Python Docker container may already be enough!

[dreitakter]

Hey, thanks for the compliments!

That's a great idea, and it could work in any language. For your interest, I am using webhooks myself to solve a similar problem with my mortgage: the original transaction is deleted and a new split transaction is submitted to Firefly III. But this script is indeed in PHP 😉 and part of a number of webhooks I'm already hosting myself.

Is your Script hosted in a different Container or is it in the firefly III Container?
Could this be an easier way to provide a Plugin system?
A new folder "/Plugins" for PHP Scripts. Is a single PHP File enough to listen on a webhook and call the API?
Can you Share your PHP solution for the transaction Split usecase?

When it comes to development tools / frameworks, I would suggest to start with a webhook (or multiple) that works for you, and then start working on a development framework.

I think you are right. One step at a time 😉

As far as development frameworks are concerned, it may even be possible to do this using standard Python libraries and some glue. A standard Python Docker container may already be enough!

As a first step I set up a local Python + Docker develop Environment with VS Code.

[JC5]

My script is not hosted in a Docker container, but it could be. You can check out an example here.

You'll have to set something up similar. You can use GitHub actions, pipedream, or a VPS somewhere, there are many solutions available to host this.

For security reasons, there will not be a folder for plugins or scripts, or whatever. Firefly III offers the API and the webhooks, you'll have to provide your own space to talk to those.