How to configure the data importer

The Data Importer communicates with Firefly III over the API.

On this page you will read how to:

1. Configure access to the Firefly III API.
2. Configure GoCardless (optional)
3. Configure Spectre (optional)

Please also refer to the following guides.

• How to install the data importer using Docker
• How to install the data importer on your own server
• General introduction to the data importer
• Explanation about GoCardless and Salt Edge Spectre
• How to get a personal access token

Access to Firefly III

First, you must tell the data importer where to reach Firefly III.

Firefly III can be reached over two URLs at the same time. In most cases this URL is always the same. For Docker installations, these URLs are often different.

The FIREFLY_III_URL is the URL that the data importer uses to reach Firefly III. The VANITY_URL is the URL that you use to reach Firefly III.

In case of Docker installations, the FIREFLY_III_URL is an "internal" URL, often in the form you see below, http://app:8080. Because you cannot browse to that URL, there is a second variable, the VANITY_URL, which is the URL you use to reach Firefly III. Most often, this is http://localhost.

If you are not using Docker, both URLs are the same and you can safely set FIREFLY_III_URL only.

If you use Docker, remember that the FIREFLY_III_URL is a reference to Firefly III from inside the data importer container. Therefore, in most cases, the URL is http://app:8080, as you can see in the examples above. This happens because Docker containers can use the container name to refer to each other.

If you do not use Docker, the FIREFLY_III_URL is probably your localhost or the location of your existing Firefly III installation.

The VANITY_URL is rarely used outside of Docker containers. It contains the URL of Firefly III as you see it in your address bar. This is often not the same as the FIREFLY_III_URL.

The FIREFLY_III_URL is optional. If you don't set it, the data importer will ask for the URL. If you do not set it, the VANITY_URL will be ignored.

Authenticate to Firefly III

Second, to authenticate with Firefly III you must set ONE of the following variables:

1. Set a Personal Access Token in the FIREFLY_III_ACCESS_TOKEN environment variable.
2. OR set a Client ID in the FIREFLY_III_CLIENT_ID environment variable.

You can get these variables by reading how to talk to the API.

These variables are mutually exclusive. If you set both, the data importer will use the Personal Access Token. If you set neither, the data importer will ask for the client ID.

Configure GoCardless

If you wish to use GoCardless, please read about GoCardless first. Then, set the following variables. This is necessary if you wish to connect to your bank through GoCardless.

• NORDIGEN_ID is your GoCardless Client ID
• NORDIGEN_KEY is your GoCardless Client Secret
• If you set NORDIGEN_SANDBOX to true the data importer will only connect to the GoCardless sandbox.

If you do not set these, the data importer will ask for them.

Configure Spectre

Third, optionally, if you wish to use Spectre, please read about Spectre first. Then, set the following variables. This is necessary if you wish to connect to your bank through Spectre.

• SPECTRE_APP_ID is your Spectre / Salt Edge Client ID
• SPECTRE_SECRET is your Spectre / Salt Edge Client secret

If you do not set these, the data importer will ask for them.

Where to set the configuration?

All the configuration values mentioned on this page are stored in environment variables:

• FIREFLY_III_URL
• FIREFLY_III_ACCESS_TOKEN
• FIREFLY_III_CLIENT_ID
• NORDIGEN_ID and NORDIGEN_KEY (for GoCardless)
• SPECTRE_APP_ID and SPECTRE_SECRET

You can use the .env file to store them, use Docker's -e flag to set them or use your operating system to set these values. This depends on your installation method, Docker or self-managed.