Mosaic Sync Manager Best Practices

Suggest Edits

Best Practices

  • Follow good maintenance on your QuickBooks Company File:
  • Keep the machine that you installed the Mosaic Sync Manager turned on, and have a Windows user logged in at all times
  • If using QuickBooks 22:
    • Ensure QuickBooks 22 is updated to at least version R3
  • Choose the "Do not show this message again" option for QuickBooks prompts to update/upgrade that you do not wish to pursue

Multi User Mode

  • You must be in Multi User Mode for the Mosaic Sync Manager to interact with your company file
  • You may switch to Single User Mode, but be aware that no data will sync between QuickBooks Desktop and Mosaic until you switch back to Multi User Mode

Switching into Single User mode in QuickBooks Desktop should not cause significant interruption to syncing data into or from Mosaic.
There is a small chance that if you switch into Single User Mode while the Mosaic Sync Manager it may cause a request to fail since the QuickBooks user that the Mosaic Sync Manager uses to connect to the Company File will lose its access. The failed request will be retried by our system the next time that the Mosaic Sync Manager has access to the Company File.

When the Sync Manager Will Be Unable to Sync

  • Mosaic Sync Manager cannot sync records that are currently open in an "editing" mode. Be sure to save and exit editing screens when you are finished with them.
  • Mosaic Sync Manager my be unable to sync data and give a time out error if QuickBooks is generating reports for a long period and the machine does not have enough resources to handle the sync and report happening at the same time
  • Mosaic Sync Manager cannot sync any data while there is a modal or dialogue box open in QuickBooks Desktop (on the same machine as you have the Mosaic Sync Manager installed.

Use a Secure Password for your QuickBooks Company File

  • Mosaic Sync Manager cannot access sensitive information like Employee details if you do not have a secure password set.

Getting Through a Strict Firewall

The Mosaic Sync Manager requires the following to be whitelisted:

  • ws://ws.pusherapp.com on port 80
  • wss://ws.pusherapp.com on port 443
  • api.pusherapp.com on port 80
  • api.pusherapp.com on port 443

Storing your Company File

The Mosaic Sync Manager logs the location of the QuickBooks Company file that it is integrating with when we set up your integration. If you move the company file, please reach out to your Customer Success Manager to re-initialize the integration, or move the company file back to its previous location (Mosaic can provide the location if needed)

Re-Integrating After Starting a New Company File

Since the integration is specific to a particular Company File, if you start a new Company File or get a new Company File after being locked out of your previous Company File you will need to start over with a new integration into Mosaic. Please reach out to your Customer Success Manager as soon as you are aware that you will be using a new Company File so we may minimize your time without your integration.

Mitigating Errors

QuickBooks Cannot Be Started

This is currently a common issue with QuickBooks 22. We've had success solving these issues with the following steps:

  • Ensure QuickBooks 22 is updated to at least version R3
  • Hard reboot of server/machine where QuickBooks 22 is installed to insure all QuickBooks processes and services have been reset.
  • Uninstall any other versions of QuickBooks from the machine that are not in use.
  • Reinstall QuickBooks 22 and the qbfc13 driver to ensure it's components have been correctly installed: https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/older-versions-of-the-desktop-sdk
  • Reset the QuickBooks permissions certificate if one already exists. Please talk to your Customer Success Manager for assistance completing this step.

QuickBooks is simply known to be finicky and suddenly drop connections. Usually the first, and easiest step is to reset the permissions certificate. Other times, a full restart of the machine where QuickBooks is running can clear up any issues.

No Response from Agent

When users receive this error, the Agent couldn't be reached, most likely because it isn't running, it's not logged in, or the computer is off or logged out.

Please make sure:

  • Your machine with the Mosaic Sync Manager and Company File is turned on.
  • The Mosaic Sync Manager is running on your machine.
  • The Mosaic Sync Manager has the correct Agent Token and shows "Connected".

Updated 2 months ago