From af19c9d23965c96033efb21ecce059ba86b53658 Mon Sep 17 00:00:00 2001 From: Jonathan Fang <76038959+Jonathan-Fang@users.noreply.github.com> Date: Thu, 3 Oct 2024 10:12:23 -0700 Subject: [PATCH] Reorganizing documentation since SimpleFIN will be officially released #2 (#459) - removed simplefin from experimental tab - added mention of simplefin in bank-sync - split bank-sync into gocardless and simplefin - created dropdown for bank-sync - proofreaded punctuation & image alignment in gocardless and simplefin guides Fixes https://github.com/actualbudget/docs/issues/452, https://github.com/actualbudget/docs/pull/453 and fixes https://github.com/actualbudget/docs/issues/454 I'm not sure why https://github.com/actualbudget/docs/issues/458 got closed, so I'm making a new one here. --------- Co-authored-by: youngcw Co-authored-by: Matt Fiddaman --- docs-sidebar.js | 14 +- docs/advanced/bank-sync.md | 144 +----------------- docs/advanced/bank-sync/gocardless.md | 131 ++++++++++++++++ .../bank-sync/simplefin.md} | 48 +++--- 4 files changed, 171 insertions(+), 166 deletions(-) create mode 100644 docs/advanced/bank-sync/gocardless.md rename docs/{experimental/simplefin-sync.md => advanced/bank-sync/simplefin.md} (66%) diff --git a/docs-sidebar.js b/docs-sidebar.js index 8adf908c1..1642167dd 100644 --- a/docs-sidebar.js +++ b/docs-sidebar.js @@ -180,7 +180,18 @@ const sidebars = { 'accounts/reconciliation', 'transactions/payees', 'transactions/bulk-editing', - 'advanced/bank-sync', + { + type: 'category', + label: 'Connecting Your Bank', + link: { + type: 'doc', + id: 'advanced/bank-sync', + }, + items: [ + 'advanced/bank-sync/gocardless', + 'advanced/bank-sync/simplefin', + ], + }, 'advanced/scripts/modify-transfers', ], }, @@ -216,7 +227,6 @@ const sidebars = { 'experimental/goal-templates', 'experimental/monthly-cleanup', 'experimental/tracking-budget', - 'experimental/simplefin-sync', ], }, 'getting-started/tips-tricks', diff --git a/docs/advanced/bank-sync.md b/docs/advanced/bank-sync.md index 5c89bc77f..a6a0a0b5f 100644 --- a/docs/advanced/bank-sync.md +++ b/docs/advanced/bank-sync.md @@ -1,151 +1,17 @@ # Connecting Your Bank -:::note -Client Version 23.7.0 and -Server Version 23.7.0 or higher are required for this feature. -::: - -We are excited to offer this optional bank integration in Actual. +We are excited to offer optional bank integration in Actual. Here are a couple of considerations to know about before making the decision to use bank sync in your installation of Actual Budget. - This integration relies on you providing your own API credentials that you will need to get by signing up with the service provider and Generate Keys and Secrets that will be used in Actual. -- The integration only works if you are using actual-server +- The integration only works if you are using actual-server. - The Secrets and Keys are stored in your Actual installed version so it is highly recommended to turn on End to End encryption and create a strong passphrase to encrypt your files. -- You will need to add a config file to your installation +- You will need to add a config file to your installation. ## Supported Providers -* GoCardless - -:::note -[Experimental support for SimpleFIN](../experimental/simplefin-sync.md) (North American banks) is also available. -::: - -## GoCardless Setup - -### Create SECRET and KEY for Actual - -1. Create an account with GoCardless - https://bankaccountdata.gocardless.com/overview/ -2. Log into your account dashboard at the same URL and select **Developers->User secrets** from the left side menu - -![Screenshot of GoCardless developer portal](/static/img/connecting-your-bank/connecting-your-bank-gocardless-01.png) - - -3. Click on the '+ create new' button at the bottom left. - - Make sure you download your secrets file since the **key** will not be available to you again in the account dashboard - - These secrets will be used in Actual to make the bank sync connection - -![Screenshot of GoCardless page for creating API secrets](/static/img/connecting-your-bank/connecting-your-bank-gocardless-02.png) - - -4. Enter a name for your secrets and click Create. - _This is only for you to easily identify them in the GoCardless User secrets overview_ - -![Screenshot of GoCardless form for creating new API secret](/static/img/connecting-your-bank/connecting-your-bank-gocardless-03.png) - - -5. Download this file and keep it on your computer. - -![Screenshot of GoCardless API secret after successful creation](/static/img/connecting-your-bank/connecting-your-bank-gocardless-04.png) - - - -6. Back in Actual, click on “+ Add account” at the bottom of the sidebar. - -![Actual sidebar with accounts](/static/img/connecting-your-bank/connecting-your-bank-02.png) - - - -7. Click “Set-up GoCardless for bank-sync.” - -![Add account dialog](/static/img/connecting-your-bank/connecting-your-bank-gocardless-05.png) - -8. You will be asked to enter your GoCardless secret ID and secret key. These values will be saved on the server, so you will only need to enter them once. - -![Set-up GoCardless dialoag](/static/img/connecting-your-bank/connecting-your-bank-gocardless-06.png) - - -### Link Accounts with GoCardless - -1. Add the link to your accounts in actual (Existing or New) - - - **_For an existing account, click on that account, select the ... (kebab menu) in the top right, and choose Link Account_** - -![Linking an existing account to GoCardless](/static/img/connecting-your-bank/connecting-your-bank-01.png) - - - **_To create a new account with bank syncing click on the '+ Add account' link in the left menu at the bottom_** - -![Actual sidebar with accounts](/static/img/connecting-your-bank/connecting-your-bank-02.png) - -2. Select the Link your bank account button - -![Add account dialog](/static/img/connecting-your-bank/connecting-your-bank-03.png) - -3. Select your country and bank from the list and click the Link bank in browser button - -![Link your bank dialog](/static/img/connecting-your-bank/connecting-your-bank-04.png) - -4. Clicking Link bank in browser will redirect you to a new tab to grant access to your bank for GoCardless - -![Link you bank feedback](/static/img/connecting-your-bank/connecting-your-bank-05.png) - -5. Select **I agree** to continue with setting up the connection - -![Dialog to approve that GoCardless will be accessing your payment account information](/static/img/connecting-your-bank/connecting-your-bank-gocardless-07.png) - -6. If your connection was a success, you will be able to click on the continue button which allows GoCardless to connect - -![Feedback for successful linking to your bank](/static/img/connecting-your-bank/connecting-your-bank-07.png) - -7. A progress indicator will display while GoCardless connects to your bank to get a list of your accounts - -![Dialog saying please wait while we finish linking your account(s).](/static/img/connecting-your-bank/connecting-your-bank-08.png) - -8. Once the connection has been made, there will be a list of your accounts that you can choose from - -![Select bank account you want to link](/static/img/connecting-your-bank/connecting-your-bank-09.png) - -9. The final step is to select the account you want to sync and click Link account - -![Dialog for linking accounts you want to sync](/static/img/connecting-your-bank/connecting-your-bank-10.png) - -### Frequently Asked Questions - -**Does Actual sync automatically with your Bank?** - -At this moment, it is not yet possible for Actual to automatically sync with your bank. You need to do this manually by going to "All Accounts" and pressing "Sync". - -![Image showing where in the GUI you can sync your bank accounts](/static/img/connecting-your-bank/syncing-with-your-bank.png) - -**The best way to start from scratch in Actual with GoCardless?** - -If you are setting up Actual for the first time, it is much easier not to try to pull in historic data. This has caused some users a lot of headaches with subsequent reconciliation. The following process may be more helpful: -1. Set up your account in Actual specifying a correct opening account balance at a recent date. -2. Link the account to GoCardless as above -3. Sync the account with GoCardless. You should find that only transactions subsequent to the opening account balance entry are imported, making reconciliation easy. - - -**How many times can I sync with GoCardless?** -In the free tier, you can sync 50 times per month. If you sync to two different banks (with three accounts in each bank), that is counted as two connections. -For more information, see the [Bank Account Data API Usage](https://bankaccountdata.zendesk.com/hc/en-gb/articles/11528933493916-Bank-Account-Data-API-Usage-how-is-your-usage-number-calculated) -topic in the GoCardless FAQ. - -**What if my bank only supports 90 days of historical data?** -If your bank limits the amount of historical data you can fetch, you need to add your bank to the list of such banks in the Actual server code. - -To achieve this: - -1. Read the instructions about integrating with GoCardless: https://github.com/actualbudget/actual-server/blob/master/src/app-gocardless/README.md -2. Toward the top is a link to the Google Docs containing data points for the GoCardless integration. Locate your bank's ID in the document. -3. Fork the Actual server repository: https://github.com/actualbudget/actual-server/fork -4. Edit the file `src/app-gocardless/bank-factory.js`. -5. Add your bank's ID (from the Google Docs) to the `BANKS_WITH_LIMITED_HISTORY` list. -6. Commit your changes and push to your fork. -7. Create a pull request to the main Actual server repository. -8. Add a release note in `upcoming-release-notes/` describing your change (see [writing good release notes](/docs/contributing/#writing-good-release-notes)). -9. Commit your changes and push to your fork. - -Once reviewed, the maintainers will comment on the pull request and merge it if acceptable. The change would then be available in the next release of the software. +* GoCardless (European Banks) +* SimpleFIN Bridge (North American Banks) diff --git a/docs/advanced/bank-sync/gocardless.md b/docs/advanced/bank-sync/gocardless.md new file mode 100644 index 000000000..7301b8c68 --- /dev/null +++ b/docs/advanced/bank-sync/gocardless.md @@ -0,0 +1,131 @@ +# GoCardless Setup + +:::note +Client Version 23.7.0 and +Server Version 23.7.0 or higher are required for this feature. +::: + +### Create SECRET and KEY for Actual + +1. Create an account with GoCardless - https://bankaccountdata.gocardless.com/overview/. +2. Log into your account dashboard at the same URL and select **Developers->User secrets** from the left side menu. + + ![Screenshot of GoCardless developer portal](/static/img/connecting-your-bank/connecting-your-bank-gocardless-01.png) + + +3. Click on the '+ create new' button at the bottom left. + - Make sure you download your secrets file since the **key** will not be available to you again in the account dashboard + - These secrets will be used in Actual to make the bank sync connection + + ![Screenshot of GoCardless page for creating API secrets](/static/img/connecting-your-bank/connecting-your-bank-gocardless-02.png) + + +4. Enter a name for your secrets and click Create. + _This is only for you to easily identify them in the GoCardless User secrets overview_ + + ![Screenshot of GoCardless form for creating new API secret](/static/img/connecting-your-bank/connecting-your-bank-gocardless-03.png) + + +5. Download this file and keep it on your computer. + + ![Screenshot of GoCardless API secret after successful creation](/static/img/connecting-your-bank/connecting-your-bank-gocardless-04.png) + + + +6. Back in Actual, click on “+ Add account” at the bottom of the sidebar. + + ![Actual sidebar with accounts](/static/img/connecting-your-bank/connecting-your-bank-02.png) + + + +7. Click “Set-up GoCardless for bank-sync.” + + ![Add account dialog](/static/img/connecting-your-bank/connecting-your-bank-gocardless-05.png) + +8. You will be asked to enter your GoCardless secret ID and secret key. These values will be saved on the server, so you will only need to enter them once. + + ![Set-up GoCardless dialoag](/static/img/connecting-your-bank/connecting-your-bank-gocardless-06.png) + + +### Link Accounts with GoCardless + +1. Add the link to your accounts in actual (Existing or New). + + - **_For an existing account, click on that account, select the ... (kebab menu) in the top right, and choose Link Account_** + + ![Linking an existing account to GoCardless](/static/img/connecting-your-bank/connecting-your-bank-01.png) + + - **_To create a new account with bank syncing click on the '+ Add account' link in the left menu at the bottom_** + + ![Actual sidebar with accounts](/static/img/connecting-your-bank/connecting-your-bank-02.png) + +2. Select the Link your bank account button. + + ![Add account dialog](/static/img/connecting-your-bank/connecting-your-bank-03.png) + +3. Select your country and bank from the list and click the Link bank in browser button. + + ![Link your bank dialog](/static/img/connecting-your-bank/connecting-your-bank-04.png) + +4. Clicking Link bank in browser will redirect you to a new tab to grant access to your bank for GoCardless. + + ![Link you bank feedback](/static/img/connecting-your-bank/connecting-your-bank-05.png) + +5. Select **I agree** to continue with setting up the connection. + + ![Dialog to approve that GoCardless will be accessing your payment account information](/static/img/connecting-your-bank/connecting-your-bank-gocardless-07.png) + +6. If your connection was a success, you will be able to click on the continue button which allows GoCardless to connect. + + ![Feedback for successful linking to your bank](/static/img/connecting-your-bank/connecting-your-bank-07.png) + +7. A progress indicator will display while GoCardless connects to your bank to get a list of your accounts. + + ![Dialog saying please wait while we finish linking your account(s).](/static/img/connecting-your-bank/connecting-your-bank-08.png) + +8. Once the connection has been made, there will be a list of your accounts that you can choose from. + + ![Select bank account you want to link](/static/img/connecting-your-bank/connecting-your-bank-09.png) + +9. The final step is to select the account you want to sync and click Link account. + + ![Dialog for linking accounts you want to sync](/static/img/connecting-your-bank/connecting-your-bank-10.png) + +### Frequently Asked Questions + +**Does Actual sync automatically with your Bank?** + +At this moment, it is not yet possible for Actual to automatically sync with your bank. You need to do this manually by going to "All Accounts" and pressing "Sync". + +![Image showing where in the GUI you can sync your bank accounts](/static/img/connecting-your-bank/syncing-with-your-bank.png) + +**The best way to start from scratch in Actual with GoCardless?** + +If you are setting up Actual for the first time, it is much easier not to try to pull in historic data. This has caused some users a lot of headaches with subsequent reconciliation. The following process may be more helpful: +1. Set up your account in Actual specifying a correct opening account balance at a recent date. +2. Link the account to GoCardless as above +3. Sync the account with GoCardless. You should find that only transactions subsequent to the opening account balance entry are imported, making reconciliation easy. + + +**How many times can I sync with GoCardless?** +In the free tier, you can sync 50 times per month. If you sync to two different banks (with three accounts in each bank), that is counted as two connections. +For more information, see the [Bank Account Data API Usage](https://bankaccountdata.zendesk.com/hc/en-gb/articles/11528933493916-Bank-Account-Data-API-Usage-how-is-your-usage-number-calculated) +topic in the GoCardless FAQ. + +**What if my bank only supports 90 days of historical data?** +If your bank limits the amount of historical data you can fetch, you need to add your bank to the list of such banks in the Actual server code. + +To achieve this: + +1. Read the instructions about integrating with GoCardless: https://github.com/actualbudget/actual-server/blob/master/src/app-gocardless/README.md +2. Toward the top is a link to the Google Docs containing data points for the GoCardless integration. Locate your bank's ID in the document. +3. Fork the Actual server repository: https://github.com/actualbudget/actual-server/fork +4. Edit the file `src/app-gocardless/bank-factory.js`. +5. Add your bank's ID (from the Google Docs) to the `BANKS_WITH_LIMITED_HISTORY` list. +6. Commit your changes and push to your fork. +7. Create a pull request to the main Actual server repository. +8. Add a release note in `upcoming-release-notes/` describing your change (see [writing good release notes](/docs/contributing/#writing-good-release-notes)). +9. Commit your changes and push to your fork. + +Once reviewed, the maintainers will comment on the pull request and merge it if acceptable. The change would then be available in the next release of the software. + diff --git a/docs/experimental/simplefin-sync.md b/docs/advanced/bank-sync/simplefin.md similarity index 66% rename from docs/experimental/simplefin-sync.md rename to docs/advanced/bank-sync/simplefin.md index 1543f42f8..71187bcf4 100644 --- a/docs/experimental/simplefin-sync.md +++ b/docs/advanced/bank-sync/simplefin.md @@ -1,24 +1,20 @@ -# SimpleFIN Bank Sync +# SimpleFIN Setup -:::warning -This is an **experimental feature**. That means we’re still working on finishing it. There may be bugs, missing functionality or incomplete documentation, and we may decide to remove the feature in a future release. If you have any feedback, please [open an issue](https://github.com/actualbudget/actual/issues) or post a message in the Discord. +:::note +Client Version 24.10.0 and +Server Version 24.10.0 or higher are required for this feature. ::: -:::warning -All functionality described here may not be available in the latest stable release. Use the `edge` images for the latest implementation. -::: - -### SimpleFIN Setup -**Generate Setup Token for Actual** +### Generate Setup Token for Actual 1. Create an account with SimpleFIN Bridge - https://beta-bridge.simplefin.org/ , by clicking "Get Started" and entering your email address. -![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-01.png) + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-01.png) 2. You will receive an email with the login link, after a few minutes. Click this link to log into your account dashboard. -![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-02.png) + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-02.png) 3. Accept the terms, on first login, and then you will be taken to "My Account". @@ -28,39 +24,40 @@ All functionality described here may not be available in the latest stable relea - You will need to subscribe before your first can be added. Current rates are $1.50 / mo, or $15 / year. 5. From the "My Accounts" page, under "Apps", click on "New Connection". Give your connection a name, and click "Create Setup Token" - _This is only for you to easily identify it in the SimpleFIN connections overview_ -![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-03.png) + _This is only for you to easily identify it in the SimpleFIN connections overview._ -5. Save the generated Setup Token someplace safe (one-time use only). + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-03.png) -![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-04.png) +6. Save the generated Setup Token someplace safe (one-time use only). -6. Back in Actual, click on “+ Add account” at the bottom of the sidebar. + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-04.png) - ![](/static/img/connecting-your-bank/connecting-your-bank-02.png) +7. Back in Actual, click on “+ Add account” at the bottom of the sidebar. -7. Click “Link bank account with SimpleFIN .” + ![](/static/img/connecting-your-bank/connecting-your-bank-02.png) - ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-05.png) +8. Click “Link bank account with SimpleFIN”. -8. You will be asked to enter your SimpleFIN setup token. The keys from this value will be saved on the server, so you will only need to enter it once. + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-05.png) - ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-06.png) +9. You will be asked to enter your SimpleFIN setup token. The keys from this value will be saved on the server, so you will only need to enter it once. + + ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-06.png) ### Link Accounts with SimpleFIN -1. Add the link to your accounts in actual (Existing or New) +1. Add the link to your accounts in actual (Existing or New). - **_For an existing account, click on that account, select the ... (kebab menu) in the top right, and choose Link Account_** - ![](/static/img/connecting-your-bank/connecting-your-bank-01.png) + ![](/static/img/connecting-your-bank/connecting-your-bank-01.png) - **_To create a new account with bank syncing click on the '+ Add account' link in the left menu at the bottom_** - ![](/static/img/connecting-your-bank/connecting-your-bank-02.png) + ![](/static/img/connecting-your-bank/connecting-your-bank-02.png) -2. Select the Link bank account with SimpleFIN button +2. Select the Link bank account with SimpleFIN button. ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-07.png) @@ -103,3 +100,4 @@ To reset your SimpleFIN setup token: 3. Click "Reset SimpleFIN credentials". You will then need to obtain a new setup token from SimpleFIN and enter it into Actual. +