Firefly Setup

This requires Firefly III to be set up and running. Please follow https://docs.firefly-iii.org/how-to/firefly-iii/installation/docker for instructions. You will need a Personal Access Token. In Firefly go to Options > Profile > OAuth > Create New Token Please save this token for later.

Please set up your Asset Accounts, Liabilities (optional), and Categories (if using ChatGPT, or transactionBypass. Emoji's are supported) before continuing. Please make a backup of your Firefly instance (including the database) before attempting to use this importer (just in case).

SimpleFIN Setup

You will need to have an Access URL from SimpleFIN and your banks set up in SimpleFIN. If you do not have SimpleFIN set up please follow https://beta-bridge.simplefin.org/info/developers for generating an access URL. You will also need to add your banks / financial institutions to SimpleFIN if you have not already done so.

Once you've got a SimpleFIN Access URL, make an HTTP GET Request to retrieve your account details curl "${ACCESS_URL}/accounts". You will need the account IDs (Accounts --> ID) for each account you wish to pull data from [See https://www.simplefin.org/protocol.html#get-data for an example response]. My account IDs start with 'ACT-' yours may just contain numbers.

ChatGPT Setup

This is optional, but without it categorization (This will use existing categories from Firefly) will not work and 'Destination Account' will default to (no name). This uses openai.GPT3Dot5TurboInstruct (gpt-3.5-turbo-instruct). You may be required to deposit $10 to access ChatGPT API Features.

Set up an account and get an API key from https://openai.com/api/ If you're using ChatGPT make sure to set up billing limits! https://platform.openai.com/settings/organization/limits

Importer Setup

Once you have Firefly, SimpleFIN, and ChatGPT (optional) set up, we can now move onto this importer. You can either compile this code yourself using the Makefile, or run it in a docker container (Recommended). I use Docker Compose

docker-compose.yml Example

Please see .env.sample for all the environment variables and their descriptions

You must build the image yourself using: docker compose build Once I feel more confident that there's no big bugs, I will add to github docker registry.

services:     
  simplefinbridgeexporter:
    build: https://github.com/helpcomp/firefly-iii-simplefin-importer.git
    # env_file: .env  # You may either use environment, or env_File
    environment:
      - FIREFLY_TOKEN=
      - SIMPLEFIN_ACCESS_URL=
      - FIREFLY_URL=http://firefly:8080
      - OPENAI_API_KEY=
    volumes:
      - ./config.yml:/config.yml
    ports:
      - 9717:9717
    restart: always

config.yml Setup

config.yml is required if the account names on SimpleFIN do not match those on Firefly, OR if you wish to use Liabilities - as Liability accounts only work with reconciliation. If your financial institution does not provide transactional data (Reconciliation Only) config.yml is also required.

non_asset_accounts (optional) - This allows you to set up how non-standard accounts are handled (such as Liabilities, or accounts that do not have transactional data). For Liabilities I use withdrawal. While this does say non_asset_accounts, you can put asset account IDs in here (such as 401k) if you wish.
ID: TYPE <reconciliation, withdrawal>

transactionBypass (optional) - This allows you to customize transactions (all fields are optional). These transactions will not be processed through ChatGPT.

- NAME OF TRANSACTION:                   # Name of the transaction coming from SimpleFIN
    company: "GitHub"                # This is the 'Destination Account'
    category: "Credit Card Payment"  # Category
    source_account: "1"              # Source Account ID (optional)
    destination_account: "25"        # Destination Account ID (optional)
    type: "deposit"                  # Transaction Type (deposit, transfer, withdrawal) (optional)
    skip: false                      # Should transaction be skipped (aka not added to Firefly) (optional)

accounts - This is where you link your SimpleFIN accounts to your FireFly accounts
ACT-*****: 1 # SimpleFIN Account ID: Firefly Account ID

config.yml Example

---
  non_asset_accounts:
    100: reconciliation
    101: withdrawal
  # Manually categorizes transactions, and bypasses OpenAI Auto-Categorization
  transactionBypass:
    - ONLINE PURCHASE:
        company: "GitHub"
        category: "Shopping"
        source_account: "1"
        destination_account: "25"
        type: "transfer"
    - MONEY TRANSFER:
          skip: true
  # Accounts: Simplefin Account ID: Firefly Asset ID
  accounts:
    ACT-00000-0000-0000-0000-0000000000: 1