Audience: ERP Admin and Accounting Manager
Accounting System: QuickBooks Desktop
Summary: This guide will review best practices for before, during, and after your QuickBooks Desktop sync.
Topics covered:
The QuickBooks Desktop Connector
QuickBooks Desktop is an accounting software that is not cloud-based. Instead it is what is considered “on-prem” or on premises. Each company file in QuickBooks Desktop will sync to its own MineralTree company.
Requirements:
Syncing MineralTree and QuickBooks Desktop requires the installation of the QuickBooks Connector application on a machine that has access to the QuickBooks Desktop Company file(s). The initial installation of the connector will happen during a meeting with your MineralTree Implementation Manager. In most circumstances, this will be installed on a user's profile on their own workstation, but it can also be installed on remote desktops or servers if required.
The connector sends encrypted data to Mineraltree using HTTPS (Port 443), so this port must be open on the company's firewall. In addition, Microsoft Framework 4.5 or higher needed to be installed.
System Scope:
The connector can be installed on more than one machine, or even multiple Windows user profiles on the same machine, and can manage multiple connections for the same QuickBooks Desktop company.
We recommend installing the connector on a minimum of two computers / users to ensure maximum uptime and increased redundancy (though it will work with just one). Additional connector applications can be installed at your discretion. This way, if one user doesn't have their connector running or is unavailable, the sync can be maintained by the other connector installation.
Before the Sync:
Check the Company File Size. If a single company file is over 700MB, a best practice is to use a computer/server you will not need to access until your initial and historical sync is complete. This helps avoid slowing down QuickBooks Desktop. Let your implementation manager know if you have company files of this size.
Single User Mode. Plan to be in this mode during the initial sync. This means all other users cannot be working in QuickBooks Desktop during this time. Note that this is not a requirement after the initial setup.
Last Restore Date. If you’ve restored any company files in the past year, share the dates with your implementation manager.
Microsoft .Net Framework. Your computer should have Microsoft .NET Framework version 4.5 or higher. Most Windows computers already have it. If not, we’ll install it during the sync.
Gather Your Team. You'll need:
- An Accounting Manager to access the Connector download area and generate the Connector key.
- A QuickBooks Desktop Administrator to allow access into QuickBooks Desktop. If the admin credentials are shared or used as a "daily driver" account by any user, we recommend that you create a new “Full Access” user just for this.
-
Someone with install permissions. If you are unable to download programs on your computer or server, you’ll need a Network Administrator to assist you. If your QuickBooks Desktop server is externally hosted or hosted by a Cloud Service Provider (CSP), reach out to your hosting provider for help.
Sync Steps:
Once your resources are gathered, your Implementation Manager will guide you through your sync.
-
Login to QuickBooks Desktop as an Admin in Single User Mode.
- NOTE: If these admin credentials are used by multiple people to log into QuickBooks Desktop, you should create another admin user for this purpose.
- Log into MineralTree as an Accounting Manager.
-
In MineralTree, select the corresponding MineralTree company from the drop down.
- You can skip this step if you will only be syncing one QuickBooks Desktop company file to one MineralTree company.
- Access the MineralTree Company Profile by clicking on your initials in the top right corner of the screen.
-
Download the MineralTree Connector on a Windows computer or the server where QuickBooks Desktop is installed. If located on a desktop instead of a server, it is recommended that the Connector be downloaded on 2+ computers containing QuickBooks Desktop in order to provide redundancy. If QuickBooks Desktop is hosted by a third party they may need to be involved in the setup process.
-
Run the downloaded file.
- A popup will flash
- Connector Key prompt will appear on your Desktop.
- Copy the Connector Key from the MineralTree Company Profile and paste it into the Connector Key prompt. Click Next.
- Critical: ensure you are connecting the correct QuickBooks Desktop company file to the corresponding MineralTree company.
- The popup may display an error message stating it cannot connect to QuickBooks Desktop. This is normal, please proceed to the next step.
- The QuickBooks Desktop Application will pop up with the below Certificate screen. Select the below options and then click Continue...:
-
For "Do you want to allow this application to read and modify this company file?"
- Set the radio button to your preferred option:
- “Yes, whenever the QuickBooks company file is open” (3rd option).
-
"Yes, always; allow access even if QuickBooks is not running" (4th option*).
*if you use the 4th option, it is recommended that you set the connector to not start-up automatically when Windows starts.
- Set the radio button to your preferred option:
-
For "Login as" (if you chose the 4th option above)
- Select "Admin"
-
For the checkbox labeled “Allow the application to access personal data…”
-
Check the box.
-
-
For "Do you want to allow this application to read and modify this company file?"
Select Done and/or Complete on the next pop-up.
-
Another certificate will pop-up. For this second certificate, always configure it as:
-
For "Do you want to allow this application to read and modify this company file?"
-
Set the radio button to "Yes, always; allow access even if QuickBooks is not running" (4th option**)
** On the second certificate, the 4th option is always mandatory even if you selected the 3rd option on the previous certificate. Selecting "No..." will block the connector from functioning at all.
-
-
For "Login as"
- Select "Admin"
-
For the checkbox labeled “Allow the application to access personal data…”
- Check the box.
-
For "Do you want to allow this application to read and modify this company file?"
Return to the Connector Key prompt and click Next twice.
The prompt will now ask you to confirm if you want to sync this MineralTree company with the QuickBooks Desktop company file. If everything looks correct, click Begin Sync. If it is incorrect, exit the Connector immediately.
The Connector should now be syncing your QuickBooks Desktop company file. This can take anywhere from 5 minutes to 2 hours, depending on the size of your file.
Important:
- Do not close the Connector while it is syncing.
- Make sure your computer does not shut down, go to sleep, or hibernate.
When the sync is done, the Connector status will update to "Connected to server" in the system tray in the bottom right corner of your screen. At that point, it’s safe to close the Connector and switch out of Single User Mode in QuickBooks Desktop.
If connecting multiple QuickBooks Desktop company files, please follow these steps again but skipping step 2 as you will not need to download the connector again. For every company file, you will also need a Connector Key which will be generated during this time.
Note: If you have multiple company files, the authorization process must be completed for each in single-user mode. You must enter a new token into QuickBooks Desktop for each company file. Repeat the above steps, logging into one company file at a time. If you are doing this for multiple company files, make absolutely certain that you are entering a Connector key generated by the MineralTree company you want the currently open QuickBooks Desktop company file to sync to.
Critical: Syncing the wrong QuickBooks company file to the wrong MineralTree company can potentially cause significant, irreparable data integrity problems in both QuickBooks Desktop and MineralTree which may require the creation of an entirely new MineralTree company to rectify the issue.
Ongoing Sync Behavior:
The Sync Interval between QuickBooks Desktop and MineralTree runs every 5 minutes. If needed, the Sync Interval can be slowed down to a cadence 10, 15, 20, 25, or 30 minutes, and so on, by the MineralTree Implementation Tech Manager by modifying the QuickBooks Desktop Connector executable configuration file. The connector program icon in the taskbar will show a status of "synchronizing" while data is being transmitted, and "connected to server" when the sync cycle has completed.
Note: During the "synchronizing" phase, users in the MineralTree application may see a status of "Not Connected" at the top of the page; this will show "Connected" as soon as the cycle has completed.
If you have two connectors running on two different computers, they will work in tandem to ensure that only one connector is syncing a particular company at any given time. For example, If Connector on Computer A is Syncing company "Acme", then Connector B will not sync that company at the same time.
In the above scenario, the person running Connector B will see a message reading "waiting for active session to expire" until 30 minutes have passed since Connector A attempted to sync the company that Connector B is attempting to sync.
There are two modes to the sync:
Online Mode:
Online mode is when the connector is running with the QuickBooks Desktop Application open. We will sync solely with the company that you have open in QuickBooks Desktop. The company you have open will sync every 5 minutes.
The connector makes and sync edits as the User that is signed into QuickBooks Desktop.
Offline Mode:
Offline Mode is when the connector is running with QuickBooks Desktop closed. If the connector is setup to sync multiple QuickBooks Desktop company files, the connector will cycle through syncing each of your companies (one company every 5 minutes).
The connector makes and sync edits as the QuickBooks Desktop Administrator User
Important: As we use the QuickBooks Desktop Administrator User to make and sync edits during offline mode, the connector won't be able to run if the Administrator is logging in from another computer (because it is as if you are already logged in via the Connector). If you frequently use the Admin user, there are two options:
1. We can associate a non-administrator user with the sync.
2. Primarily using the sync in Online Mode.
Using MineralTree with QuickBooks Desktop
Payment Accounts
Payment Account types “Bank” and “Credit Card” sync to MineralTree as potential pay from accounts.
Note: Selecting "Credit Card" as a pay from account is a manual payment type for record-keeping purposes only and does not initiate a credit card transaction. For Virtual Card payments from the MineralTree platform, please see our SilverPay program article.
Vendors
Vendors must be created in QuickBooks Desktop. All active vendors will sync into MineralTree. Post-sync deactivated vendors are viewable in MineralTree and can be removed from view by contacting MineralTree Support. Edits to vendor master data such as address and phone number will sync into QuickBooks Desktop with several exceptions: Vendor ACH details and Default Payment Type do not sync and must be managed in MineralTree on the vendor profile. For more information on the available fields on the vendor record, and what will sync to QuickBooks Desktop, see Vendor Details.
Bills
Creating Bills in QuickBooks Desktop:
Invoices (bills) created in QuickBooks Desktop will sync to MineralTree. Please note that document attachments in QuickBooks Desktop do not sync to MineralTree.
Creating Bills in MineralTree:
Users can utilize Invoice Capture to create bills in MineralTree. Or, users can enter new bills with or without an associated document. Both expenses and items are supported. Dropdown selections are populated with values from QuickBooks Desktop. First, bills are created in Draft status where they exist only in MineralTree. Then, bills can posted (or auto-posted) from MineralTree and will sync to QuickBooks Desktop as “Open” bills.
Terms
The standard terms (due dates and discount dates that are functions of the bill date that are supported in QuickBooks Desktop are also supported in MineralTree and will sync from QuickBooks Desktop to MineralTree and vice versa.
Closing Date
MineralTree will not allow posting or editing bills that are dated within a closed period. If the bill has not yet been posted to QuickBooks Desktop, the date can be modified in MineralTree. If the bill has been posted to MineralTree, it must be deleted and remade with a current date in QuickBooks Desktop or the closed period must be reopened and the date changed on the bill to be editable within MineralTree.
Documents
Documents attached to records in MineralTree do not sync to QuickBooks Desktop. Documents attached to records in QuickBooks Desktop do not sync to MineralTree. However, MineralTree offers an unlimited amount of document storage, so users may attach an unlimited number of supporting documents to any bill record in MineralTree. A mass file backup of bill document attachments and check images can be provided by contacting your MineralTree Customer Success Manager (service charges apply).
Supported Bill Fields
Header Level:
Vendor Name*
Invoice Number
Invoice Date*
Due Date*
AP Account*
Base Currency*
Transaction Currency*
Terms
Memo
Gross Amount
AP Account*
Discounts Available
Credits Available
Credits Applied
Discounts Applied
In Process Payments
Paid Amount
Remaining Amount
Invoice Notes (available in MineralTree only and do not sync to QuickBooks Desktop)
Expense Line Level:
Account*
Net Amount*
Description
Class
Job
Billable
Item Line Level:
Item*
Quantity*
Cost Per*
Net Amount*
Description
Class
Job
Billable
*Required for posting in MineralTree.
Bill Approval
Bills can be routed for approval from the Invoice Details page or automatically based on Vendor, Class, or GL Account coding. When default invoice approvers are set up for any of these attributes, the following hierarchy is used to decide who receives the approval request: Vendor > Class > GL Account. An individual Vendor's Invoice Approval rule can be prioritized over a Class or GL Account rule on the Vendor's profile.
Deletions
Bill deletions do not sync between QuickBooks Desktop and MineralTree. Posted bills must be deleted in both QuickBooks Desktop and MineralTree maintain reconciliation between both systems.
Voids
Payment voids made in QuickBooks Desktop do not sync to MineralTree. Payment voids made in MineralTree for MineralTree-originating payments will void the payment in QuickBooks Desktop. If you are uncertain, it is best practice to void payments in both QuickBooks Desktop and MineralTree.
Credits
All credits must be created and applied in QuickBooks Desktop. Once applied, the remaining balance of the bills they are applied to will update in MineralTree upon the next sync. Any credits applied in QuickBooks Desktop sync to MineralTree as credit payments against invoices. Applied credits appear on the email remittance and check stub. For detailed steps on on applying credits in QuickBooks Desktop to reflect correctly in MineralTree, see this article.
Discounts
MineralTree supports discounts with QuickBooks Desktop. Discounts applied appear in teh Discounts column of the remittance. For step by step instructions, please see Automatic Discount Application.
Please reach out to Customer Support with any questions:
- Phone: 855‑672‑9669
- Email: mtsupport@mineraltree.com