Update: I’ve posted new versions of these shortcuts for iOS13 and Firefly III 4.8: www.jessedyck.me/2019/12/updated-firefly-iii-shortcuts-for-ios-13/
I built a couple of iOS shortcuts for Firefly III (a self-hosted personal finance web app) to let me add transactions on the go. I’ve shared some more details and iCloud links to the shortcuts below.
The first Shortcut is more or less a function that returns a list of accounts. That list is used in the second shortcut to submit the new transaction to Firefly. I wanted to keep the process as quick as possible, so that shortcut requests the least information possible to submit the transaction.
I’ve only just recently switched to using Firefly III; prior to that I had been using Mint for about 8 years. I’ve been increasingly uncomfortable with giving up that much data – and my bank credentials – for a number of years, so I’d been on the lookout for a replacement for quite a while. I’ve probably tried them all, but for one reason or another I couldn’t find an app that fit my requirements.
Firefly is a bit of a change in workflow over Mint, but I’ve found that it’s encouraging me to take a more active role in managing my finances. In part because it doesn’t recommend auto-importing transactions. All-in-all though, it’s working quite well so far.
There are a few places where I’d do things differently in Firefly, but part of the appeal (for me at least) is that it’s built on PHP (Laravel, to be specific) so I could feasibly contribute to it, or at least modify my own fork. It also has a nice REST API and great documentation to go with it, which of course is what these shortcuts are using.
I knew I wanted the ability to add transactions on the go, but logging into the web app is a bit too much friction while waiting in line for a $2 coffee. And let’s face it, if the transaction isn’t added immediately I’ll probably forget about it. So that’s what I’ve solved with these shortcuts.
- Your Firefly III instance must be accessible over the internet (I would not do this without using HTTPS)
- The API supports using a Personal Access Token rather than OAuth, which must be created in Firefly > Options > Profile
- The Firefly URL and token must be added to both shortcuts
Shortcut can’t find an account?
If no accounts are returned, it’s most likely that the Personal Access Token was denied; either the token was incorrect or, as is common after a Firefly update, the Personal Access Token was essentially deactivated. I often have to delete and recreate it after updates.
I’ve shared these via iCloud Drive. Load up this post and download the links on an iOS device. Plug your Personal Access Token and the URL to your Firefly III instance into both shortcuts, then test out the Accounts shortcut. It should return a list the asset accounts in Firefly III, along with the current balances.
If you’re not on an iOS device, here’s the what the two shortcuts look like—warning, they’re long:
I’m hosting Fathom on my domain at /fathom. It runs its own web server, so I’ve done this using a reverse proxy that makes the Fathom server accessible at that virtual directory. Their self-hosting instructions do have an example configuration for using Fathom with a reverse proxy through NGINX, but not Apache.
Fortunately the idea’s the same, so adapting it for Apache doesn’t involve too much. It does mean modifying the httpd.conf (or appropriate site-specific config file), and enabling a few additional Apache modules.
The Apache modules needed are mod_proxy, mod_proxy_http and mod_substitute. These can be enabled using
a2enmod and restarting Apache:
sudo a2enmod proxy proxy_http substitute && sudo service apache2 restart
Now to enable the reverse proxy, I’ve added a new
Location directive the
VirtualHost in my site’s config file:
A little more on what each of those directives are doing:
Creates an entry point at the URL in the
Locationdirective (the first line, in this case it’s /fathom), which in turn forwards those requests on to the Fathom server defined in this
Replaces redirects sent from Fathom (in the
Locationheader) with the location that the client browser can access. In other words, when Fathom tries to redirect to an internal Login page (127.0.0.1:8999/login), this directive tells Apache to replace that with an externally-accessible URL (/fathom/login).
Fathom’s example NGINX configuration explicitly passes on the Host header from the proxy to the upstream server (Fathom), so it’s safe to assume we should too.
ProxyHTMLURLMap ^(.*)$ /fathom/$1 [R]
These next few directives replace URLs in various HTML elements before sending them back to the browser. For example,
<script>tags will need to be updated to point to the virtual directory (subfolder). Including the
proxy_html.conffile imports a default mapping of attributes to elements so that Apache knows which attributes on which elements to update.
Substituteuses a sed-like syntax for replacing text.