Overview

QuickBooks is a line of business accounting software developed and marketed by Intuit. A free QuickBooks add-on, the Web Connector (QBWC), is a third-party application that allows data to export from one software vendor (like BriteCore) to QuickBooks. Newer versions of QuickBooks have the Web Connector application already installed.

Via the Web Connector, you may import Claim Payments, Return Premium Payments, and Agent Commission Payments from BriteCore to QuickBooks, which are then printed and mailed to the appropriate party.

As the Web Connector is not affiliated with BriteCore, troubleshooting can be difficult.


Vendor Contact

Contact any retail software vendor.


Getting Started

  1. Contact QuickBooks sales
  2. Complete their paperwork
  3. Determine how you will install QuickBooks at your office
    • 1 user, QuickBooks and Web Connector on local machine with the QB data file on the local machine
    • 1 user, QuickBooks and Web Connector on local machine with the QB data file on a centralized, shared server
    • Multiple users who share 1 QuickBooks and Web Connector program on a shared connection with the QB data file on the same server
    • Multiple users who share 1 QuickBooks & Web Connector program on a shared connection with the QB data file on a different server
    • Multiple users with their own QuickBooks & Web Connector programs with the QB data file on a centralized, shared server (most common)
  4. Contact a licensed QuickBooks provider to train your staff on installing and using QuickBooks. IWS does not provide any training on QuickBooks installation
  5. Complete the QuickBooks installation on a Windows-based server or computer
  6. Add the supported expense accounts (i.e., Claim Payments, Return Premium Payments, and Agent Commission Payments) in QuickBooks to which BriteCore will export transactions. Ensure the Checking Account Name is set up as a bank for its type
  7. Download the Web Connector Application if your QuickBooks version does not have it pre-installed
    • If you wish to run the Web Connector from the centralized server, install a copy of QuickBooks on the server
    • If you have a single client computer to manage the Web Connector, QuickBooks must only be installed on that client machine

BriteCore Setup

  1. Complete the QuickBooks installation above
  2. Contact IWS requesting an IWSWebSvc.qwc (IWS Web Service) file and provide a username and password you would like to use for BriteCore/QuickBooks transactions. Retain the username and password for your records
    • Implementing clients: email your project manager
    • Existing clients: submit a ticket
  3. Once received, add the IWSWebSvc.qwc file to the QuickBooks Web Connector
  4. Download the IWSWebSvc.qwc file to the desktop of the machine upon which the QuickBooks Web Connector is installed
  5. Open the QuickBooks application and ensure it points to the company file with which you want the IWS Web Service to interact
  6. Log into QuickBooks as the Administrator and set QuickBooks to Single User Mode (File > Single User Mode). Once the file is installed, set QuickBooks back to Multi User Mode if applicable
  7. In QuickBooks, click File > Update Web Services. This should open the Web Connector application
  8. From the Web Connector application, click the Add An Application button and browse to the IWSWebSvc.qwc file downloaded to your desktop from Step 4
  9. Click Open
  10. Click OK on the Authorize New Web Service page
  11. On the QuickBooks - Application Certificate page
    • Click Yes, always; allow access even if QuickBooks is not running for Do you want to allow this application to read and modify this company file?
    • Check the Allow this application to access personal data such as Social Security Numbers and customer credit card information. box
    • Click Continue
  12. Click Done on the Access Confirmation page
  13. On the QuickBooks Web Connector app, enter your password in the textbox
  14. Click Enter
  15. Click Yes to save the password
  16. Complete the vendor setup in Settings > Vendors > QuickBooks
    • Checking Account Name This is the exact name of the QuickBooks business checking account to which BriteCore payments export. Disregard any QuickBooks specific assigned numbers when entering the account name into BriteCore
      • If an account is a sub-account, please enter the primary account name, separated by colon, then the sub-account name. For example, enter Net Commissions:Agent Commission Payments where Net Commissions is the primary account and Agent Commission Payments is the subaccount
    • Company File Path Allows the Web Connector to exchange data with QuickBooks even if QuickBooks is not open
      • Locate your QuickBooks Company File Path
        • Open QuickBooks
        • The Splash Screen opens with a list of available company files
        • Just below the list is the Location file path of whatever company is highlighted in the box. This is your file path. Copy and paste the path into the BriteCore Company File Path textbox
        • Alternately,
          • Open Quickbooks
          • Click File > Open or Restore Company...> Open a company file (Next)
          • Highlight or right click your QuickBooks company file
          • Choose Properties
          • Click on the QuickBooks tab
          • The full path will be in the Filename: textbox
    • Agent Commission Payments Check the checkbox if you want Agent Commission transactions entered into BriteCore to flow to QuickBooks. Enter the exact QuickBooks Account Name to which you want the payments to flow into the associated textbox
    • Return Premium Payments Check the checkbox if you want Named Insured Return Premium transactions entered into BriteCore to flow to QuickBooks. Enter the exact QuickBooks Account Name to which you want the payments to flow into the associated textbox
    • Claims Payments Check the checkbox if you want Named Insured Claims Payment transactions entered into BriteCore to flow to QuickBooks. Enter the exact QuickBooks Account Name to which you want the payments to flow into the associated textbox. You can also map Claims Expense Accounts to a line of business by clicking the Detailed Level Claims Mapping checkbox. For each line of business, enter the exact QuickBooks Account Name into which you want the payments to flow
  17. Click Save

BriteCore Processing

A claim, return premium, or commission payment exists in BriteCore:

  1. Open QuickBooks
  2. Choose the appropriate Company File
  3. Open the Web Connector from QuickBooks (File > Update Web Services). Only transactions dated today or before will export. All future dated transactions will not export until their specified date
    • Option 1, export one at a time
      • Check the box to the far left of IWS QuickBooks Web Service row
      • Click the Update Selected button until you receive No data exchange required
    • Option 2, auto export (recommended for processing commissions)
      • Click Auto-Run on the IWS QuickBooks Web Service row
      • Set the Every_Min column to your desired rate

View Exported Transactions

  1. In QuickBooks, browse to the Customer Center
  2. View the imported payments based upon the payee
  3. Double click the Payment Entry in the summary section. The Check View will open for printing and a check number will be assigned by QuickBooks

There are also a number of reports that can be generated in QuickBooks that can show any level of transaction detail for a given date span. For example,

  1. Choose Reports > Banking > Check Detail
  2. Run the report for a target date range
  3. Sort by Account to see all checks which have been imported from BriteCore into QuickBooks for the expense account of your choosing

How-Tos

Create an IWSWebSvc.qwc File (IWS Only)

  1. Shell > vendors > generate_qwc_file
  2. Use CyberDuck to move the file to your desktop

Restart the QuickBooks Service

  • Connect to BriteCore shell
  • The file itself is located in /srv/www/britecore/soap/QuickBooksService.py
  • cd to the soap directory then run sudo supervisorctl restart quickbooks on both nodes (leader and follower)

FAQ

Does the check number export back to BriteCore?
Presently the integration works one way. You can record the check number by inputting into the individual policy’s Notes section, if desired.

The Web Connector cannot connect to QuickBooks. What is my next step?
If you are using a shared QuickBooks program located on a central server that multiple users can access, the QuickBooks program must be running and pointed to the appropriate company file for the Web Connector to find it. To bypass this requirement, enter a Company File Path in BriteCore > Settings > Vendors > QuickBooks.

Upon application installation, ensure you are logged into QuickBooks as the Administrator and that QuickBooks is in Single User Mode. Once the Application is installed, set QuickBooks back to Multi User Mode, if applicable.

QuickBooks does not recognize the Checking Account / Expense Account name. What is my next step?
There is an option in QuickBooks that prepends account numbers to account names. For example 1005 ∙ Bank Of America Checking where 1005 is the account number, the middle dot is a QuickBooks designated separator, and Bank Of America Checking is the actual account name. Do not include the account number or the middle dot when entering your checking account name into BriteCore; enter only the checking account name.

I ran the Web Connector. Why did only some of the return premiums export?
Only return premiums dated today or before will export.

I ran the Web Connector. Data was expected to export but did not. What is my next step?
Restart QuickBooks and the Web Connector.

I ran the Web Connector, but an error occurred. What is my next step?
Click View Log, and send the result to IWS via a ticket.

When adding the IWSWebSvc.qwc file to QuickBooks, I receive the following error: Error while adding the application: Unique OwnerID/FileID pair value required. What is my next step?

  1. Submit a ticket to IWS
  2. Generate a new file per the How-Tos section
  3. If a row already exists for the QuickBooks Web Connector in the vendor_auth table, then see the Already existing row above
  4. If the service must be restarted then see the Restart the QuickBooks service above

I ran the Web Connector and received Application requested to abort. What is my next step?
The course of action is unclear. Submit a ticket to IWS to restart the web connector service, which may or may not solve the issue.

I ran the Web Connector and received QBWC1041: SendRequestXML failed. What is my next step?
This error typically means the address of the contact was entered on line 2, leaving line 1 blank. Within the Contacts module, ensure address line 1 is not blank for any contacts associated with the return premium, claim payment, or commission payment.


More Information

These general steps help troubleshoot connection issues:

  • Information on the the web
  • Restart the Web Connector service per the How-Tos section
  • If a row already exists for the QuickBooks Web Connector in the vendor_auth table and the client needs a new username/password
    1. Get a new user/pass from the client
    2. Delete the row in the vendor_auth table
    3. Create a new file via the shell tool and enter the new user/pass
  • Check to see if the service is failing on a contact. For example, ensure the addressLine1 is not blank for any contacts
  • If a transaction will not export, check quickbooks.log. If you receive a message like statusMessage="The name "Justin Cimino" of the list element is already in use" then action is needed
    • The payment payee must be in QuickBooks to process the payment. BriteCore is unaware of who is in QuickBooks as a Customer, Vendor, or Employee. Therefore, when BriteCore processes a new transaction it pushes the payee name to be added into QuickBooks first and then the actual transaction. The above error is QuickBooks’ way of communicating that the Customer/Vendor/Employee BriteCore is exporting already exists in QuickBooks. The fix is to manually add the Customer to the BriteCore database via this insert statement
      INSERT INTO qb_contacts 
      VALUES
      (uuid(), 'whomever the contact is', 'Customer')
  • If the Web Connector is in Single User Mode, it must be restarted in order to pass checks to QuickBooks

Feedback

Report unclear or missing documentation.