QuickBooks Desktop guide

Software Setup

To acquire your own Quickbooks Desktop instance, you must purchase a Quickbooks Desktop license, download the software, and install it on a Windows computer.

If you do not own a Windows computer, we recommend creating a Windows virtual machine on a cloud hosting provider like Microsoft Azure and then using a remote desktop application to access the Windows machine.

To get realistic data, you can open a Quickbooks Desktop sample company file, which comes installed together with Quickbooks Desktop.

Rutter does not provide a Quickbooks Desktop instance or Windows virtual machine.

Developer Account Setup

No additional developer account setup is needed.

Rutter Link

The Rutter Link authentication flow consists of a few steps, which are outlined below. These steps must be followed correctly by your customer after you have turned on the integration to successfully connect a new instance through Rutter Link.

Step 1: Input QuickBooks Desktop Options

Make sure you are using a desktop computer or laptop with QuickBooks Desktop installed and running. You will need access to your QuickBooks files to complete the setup process.

Enter both the company name as well as the Company File Path, if available. The Company File Path is important, as saving that will ensure that data is synced even when Quickbooks Desktop is not running.

Step 2: Download and Run the QuickBooks Desktop Web Connector

Follow the steps to download the QBD Web Connector. Alternatively, it can also be downloaded here.
Open your QuickBooks Desktop application. Navigate to File -> App Management -> Update web services.
This will launch the QBD Web Connector.

Step 3: Add the Web Connector to QuickBooks Desktop

Double click the "quickbooks.qwc" file you downloaded to open it in the Web Connector. Click OK.
When the authorization prompt is shown, select the final option “Yes, always allow access even if QuickBooks isn’t running”.
Please leave the box to allow access to personal data unchecked.
Select Continue and Confirm

Step 4: Start the Sync

Confirm the subsequent prompts.
In your Web Connector, you will see a new application. Click the checkbox on the left and click "Update Selected".
Copy the password provided by Rutter Link and paste this into Quickbooks Desktop to run the sync. The password is the Base 64-encoded version of the connection ID. You can manually Base 64 encode the connection ID to recover the password if lost.

Note: This password is critical as connection syncs will not function correctly unless the end user is able to add this password into QuickBooks Desktop.

Finally, once the password is saved, the connection will be verified, and you can select 'Next' to complete the Rutter Link flow.

Reference

Naming Conventions

Accounting platforms can refer to Rutter objects by different names internally.

Expenses

Expenses are represented in QuickBooks Desktop as Credit Card Charges and Checks.

Troubleshooting FAQ

Which versions of QBD are supported?

The QuickBooks Web Connector 2.1.0.30 and older versions can be used with any QuickBooks desktop product supported by the QuickBooks SDK or the QBPOS SDK, including:

*U.S. editions of QuickBooks Financial Software products *QuickBooks Enterprise Solutions *QuickBooks Premier (2013 or later) *QuickBooks Pro (2013 or later) *QuickBooks Simple Start (2013 or later) *Canadian editions of QuickBooks Pro, Premier or Enterprise (2013 or later) *UK editions of QuickBooks Pro or Accountant Edition (2013 or later) *QuickBooks Point of Sale (v4.0 or later) - QBWC 2.1.0.30 or earlier

QuickBooks Web Connector 2.1.0.30 and older versions only support up to TLS 1.0.

QuickBooks Web Connector 2.2.0.34 and newer versions will only work with the following versions of QuickBooks:

*U.S. editions of QuickBooks Financial Software products *QuickBooks Enterprise Solutions (2013 or later) *QuickBooks Premier (2013 or later) *QuickBooks Pro (2013 or later) *Canadian editions of QuickBooks (2013 or later) *UK editions of QuickBooks (2013 or later)

My customer has encountered an issue where QuickBooks Desktop is unable to establish a connection. How can I solve this?

For common connection errors and their resolutions, please refer to the following documentation: QuickBooksDesktop Error Code Reference Guide

What happens if the sync is frozen?

Sync might look frozen and stuck at 30/60% but it is usually still running in the background. Due to technical difficulties, we cannot calculate the precise progress of the sync. You can look at more detailed logs in the Rutter dashboard's connection page. If you still think there is an issue, please contact us with Zendesk ticket.

What steps should I take if I get the “application requested to abort” error when attempting to start QuickBooks Desktop?

Ensure the only one QuickBooks instance is open and running.
Ensure that the QuickBooks instance is logged into the company file that the user set the connector up for.
If autorun is not enabled, re-initiate the sync. Check the last connected time on the dashboard to make sure the sync was re-initiated.
Ensure that the third party application you are using has access to your Company File. You can check this by going to Edit -> Preferences -> Integrated Applications -> Company Preferences and ensuring that the application is listed, as well as has access.
If the issue continues to persist, please reach out to Rutter with the QBXML and QBWC logs. You can refer to Quickbooks Desktop Logging and Quickbooks Web Connector Logging for assistance on generating the log files.

How do I find the web connector password?

The password is the base64 encoded version of the connection ID. The connection ID should be visible in the dashboard. https://dashboard.rutterapi.com/connections/:connection_id/progress

How can I decrease sync interrupts?

Your customer’s workflow will be interrupted when a sync is in progress so decreasing the sync frequency will decrease the occurrence of interrupts. If your customer has auto-run enabled, encourage them to decrease the sync frequency to every 30 minutes.
Decreasing the batch size in your Data Sync Configuration will increase the speed of the Initial Sync for new connections. This will decrease the interruption time on the QBD user's end.

What should I do if I get the error “cannot communicate company file due to firewall”?

Try going through this QuickBooks support page: Quickbooks Suppport.
If you are attempting to sync with QBD closed, then ensure that the company file path is set in the rutter and proper permissions are given in the initial setup flow. Here is a video demonstrating how to set up syncs with QBD closed.
Otherwise, ensure that QBD is open in order for the syncs to work.

What should I do if I’m getting an error saying “the company file cannot be closed at this time because there is another application which is using it”?

You will likely need to restart QBD as it may be running somewhere in the background. Find the background process and close the web connector. Look into your computer application monitoring to confirm that QBD is closed. Then, restart QBD and open the web connector.
If QBD Web connector is not an open application on your computer, then it will not be open in a pop-up. You can double check that the connector is open by ensuring that there is a UI open with applications that are connected with their respective status.
On Windows, you should be able to press Ctrl + Shift + Esc to see if a process is still running.
Re-installing QBD:
- User needs admin permissions on the Windows computer to follow these steps (they will need to run the QuickBooks installation .exe as an administrator).
- User should uninstall both the QuickBooks installation and the web connector installation, which also requires Windows admin permissions.
- User should first uninstall from their end. After re-installing, the user should go through the instructions in the Rutter Link process again (installing the web connector application, granting permissions, saving the password, etc.). The user should use the specific URL that corresponds to the connection that they made in the past: https://link.rutterapi.com/connections/:connection_id.

What should I do if I the error “A QuickBooks company data file is already open and it is different from the one requested or there are multiple company files open.”?

Pause all connectors or third party connector syncs to the instance, close the QuickBooks instance and connector, then reboot it and ensure to log into only the company file for which the connector was set up. Login to the admin user account where the user set up the connector. Then, reattempt a sync for only the connector in question. In addition, you may need to get the updated file path and then update it via the dashboard under the connection's settings page:
https://dashboard.rutterapi.com/connections/:connection_id/settings
Try restarting (or killing from task manager) and sync again.

How do I find my company file path?

Steps: 1. Open QuickBooks Desktop 2. Open the Company File you wish to connect to QBD 3. Press F2 (or CTRL 1 on some systems) on your keyboard to open up the following window in QuickBooks Desktop titled 'Product Information'

How do I verify the company file path is accurate?

The company file path usually ends with the extension .qwb so if you see something different it could be the wrong file.

What should I do if I get the error “QuickBooks already has a company file open. If you want to open another company file, close this one first”?

Your web connector is trying to open another window because the company file that qbd is currently using is different from the one we want to sync with. Here are some steps to mitigate that: 1. Close QBD and and the web connector. 2. Open QBD with the same company file that you want to sync with (this needs to match the file path you placed in the dashboard). 3. Open web connector and try syncing again.

How can I move the QuickBooks web connector connection to Rutter to a different computer with a different installation of QuickBooks?

You should use that exact same Rutter link, and proceed with step 2. The first screen is shown just to ensure that it is what you expect to see (you will be unable to edit), and it is the same company name that is being linked on the original computer. The password is part of the Rutter link flow.
Use the same file and connection. Be sure to use the same .qwc file and start the web connector connection up again from the new computer.
Ensure that the QuickBooks company file is exactly the same running on a network share at exactly the same path.

Does the QuickBooks Desktop connector need to be running on all machines that interact with the QuickBooks account/file?

You just need one instance running that is syncing since we are writing/reading from the company file. Other instances reading from that company file should have that same synced information so they don't need to be open.

Can two computers run the web connector at the same time against the same file?

It is not possible to simultaneously run the web connector at the same time against the same file. However, it is possible to run them one right after another.

How do I know which version of the web connector a new connection will get?

In general, you can download the most recent version of the web connector. However if you are on an old QBD version, you may need to check which version is compatible by referring to this guide from Intuit.

What if I get the error saying “this application is unable to log into this QuickBooks company data file automatically”?

The QuickBooks administrator must grant certificate permissions correctly for an automatic login through the Integrated Application preferences. If such permission was already granted and you are still getting this error, the administrator must revoke permission, save preferences, then grant the permission again.

What should I do if I get the error saying “an application is already loaded with the same FileID”?

You should go through the auth flow again and download a new .qwc file; this error typically arises from trying to use the same .qwc file as before, which doesn't work.