Overview
This document discusses the setup required both in the Rootstock application and QuickBooks Online, and the testing of the processes that exchange data between the two applications. The first section discusses the Rootstock setup, the second the QuickBooks setup, and finally the list of processes and their subtasks with the expected results for either application.
Required Rootstock Setup Data
Names for Rootstock Setup Data
It is good to be aware of some of the QuickBooks name limitations for Customers, Vendors, Products, etc. when setting up the Rootstock data.
Special Characters
QuickBooks Online United States version of the web service has a limitation on characters used. The list below contains the approved characters. Note that this limitation is only for the US, as UTF-8 is acceptable for foreign QuickBooks accounts.
NOTE The Space ( ) is not allowed in the callback URL which is built from the Company Name Credential created in the Quickbooks Developer App.
System Defaults > Quickbooks Integration (Set up the organization's Quickbooks settings.)
NOTE If an error is encountered during the QuickBooks export and if the flag 'QuickBooks Online-Abort Export on Error' on System Defaults is TRUE then the errors will be shown in the job email, else the errors will be shown in the Processing Results (SYRESULT). In either case, the export will fail if an error is encountered.
Company / Division
The QuickBooks Online interface exports Sales Invoices (or Invoices), Payables Invoice (or Bills), and Journals. The interface processes export the pertinent transactions from the ‘Current Company/Current Division’ of the Rootstock user that runs the export process. The setup of account information for the user's current company/division is key to the entire export process. It is not currently in the scope of this writing to detail how this should be done, however, the Rootstock Sub-Ledger Accounts that are used must reference the appropriate QuickBooks G/L Accounts.
Rootstock supports linkage from two Rootstock Companies to Quickbook orgs, via setup on Company Master record > Financial Interface tab.
Company Master > Financial Interface tab
With settings on this tab, every Rootstock Company can have its own connection to Quickbooks, although only two are supported. One (and only one) of these Rootstock Company records can be marked as the Quickbooks Primary Company.
Fields
QuickBooks Primary Company: Rootstock can support up to two different Quickbook Companies. If this checkbox is set to true only one Company can be used as the primary company.
Online Company: This value on this field represents the company Identification number of the Quickbooks Account.
Quickbooks Online Named Credential: When a company is configured as multi-company (field 'QuickBooks Online Multi-Company Active' is set to true on System Defaults), the value specified on this field is used for connecting to the Quickbooks Online server. When a company is configured as a single company ( field 'QuickBooks Online Multi-Company Active' is set to 'false' on System defaults) the value on the field 'Quickbooks Online Named Credential' of System defaults record is used instead.
QuickBooks Online Consumer Key: This Consumer Key value is generated by Quickbooks during the Intuit Authorization Process. There is a different Consumer Key for Development and Production Databases.
QuickBooks Online Consumer Key Secret: This Consumer Key Secret is generated by Quickbooks during the Intuit Authorization Process. There is a different Consumer Key Secret for Development and Production Databases.
QuickBooks Online Token: This Online Token is generated by Quickbooks during the Intuit Authorization Process. There is a different Online Token for Development and Production Databases.
QuickBooks Online Token Secret: This Online Token Secret is generated by Quickbooks during the Intuit Authorization Process. There is a different Online Token Secret for Development and Production Databases.
The restriction of two connections relates to how many Quickbook connections a Rootstock Customer or Vendor can have, which does limit the number of usable Quickbook connections to two.
-
Each Rootstock Customer & Vendor can hold 2 reference IDs to Quickbooks, a primary and a secondary. (Carried by using syncing Financial System XXX ID and Secondary Financial ID fields on RS Customer and Vendor objects - XXX as in Customer or Vendor-).
-
This means that a single Rootstock Customer or Vendor can be associated with at most 2 Quickbook connections.
-
If a Customer is synced with a primary and a secondary connection, then if an attempt is made to sync with a third connection, then this Customer will be ignored as it will already be fully synced.
-
A solution to this limitation would be to ensure RS Customer & Vendors are only to be used for transactions with two Rootstock Companies.
There’s a similar restriction for Rootstock Products (1 QB connection per RS Product record) but since Rootstock products are division based, it is possible to effectively have the same product associated with any number of Quickbook connections as long as an RS Product record exists for each Division.
Products
Be aware that products in Rootstock are looked up in QuickBooks Online by the Name field of the product, so reference Names for Rootstock Setup Data.
Customers
If the field is empty, Rootstock will check by name to see if it exists in QuickBooks, and add it if it is not found, filling this field in with the QuickBooks reference number. Financial System Customer ID. When creating Rootstock Customers be aware that if the Customer Financial System Customer ID field is empty, Rootstock will check by name to see if it exists in QuickBooks, and add it if it is not found, filling this field in with the QuickBooks reference number.
NOTE This reference number will be the number at the end of the URL when viewing a particular Customer in QuickBooks.
NOTE The Name of the Customer must be unique.
NOTE The user has to change the name of Employees who were both Customers and Vendors.
Test Sync of Customers
As a test, it is a good idea to clear the Financial System Customer ID fields of some or all Rootstock Customer records, and verify (via Sales Invoice Export), that Rootstock ‘syncs’ Customers by populating this field for all Customers.
Test Add of Customers
It is important to add a new Customer and verify (via Sales Invoice Export), that this Customer was both added to QuickBooks Online, and that the Financial System Customer ID was populated in Rootstock.
Vendors
When creating Rootstock Vendors be aware that if the Vendor Financial System Vendor ID field is empty, Rootstock will check by name to see if it exists in QuickBooks, and add it if it is not found, filling this field in with the QuickBooks reference number.
NOTE This reference number will be the number at the end of the URL when viewing a particular Vendor in QuickBooks.
NOTE The Name of the Vendor must be unique.
NOTE The user has to change the name of Employees who were both Customers and Vendors.
Test Sync of Vendors
It is important to add a new Vendor and verify (via Payable Invoice Export), that this Vendor was both added to QuickBooks Online, and that the Financial System Vendor ID was populated in Rootstock.
Accounts
Setting up the GL Accounts and Sub-Ledger Accounts in Rootstock correctly is a critical setup task. The Rootstock Sub Ledger Accounts each point to a QuickBooks G/L Account. If that G/L Account does not have the correct QuickBooks reference number, to the appropriate QuickBooks G/L Account, the transfer will not work (transactions will be rejected by QuickBooks).
Sub-Ledger Accounts (Mfg Accounts)
Every Sub-Ledger Account in Rootstock must point to a valid G/L Account. These G/L Accounts can be imported from QuickBooks as mentioned below or can be manually created in Rootstock, via the Chart of Accounts process.
General Ledger Accounts (Chart of Accounts)
G/L Accounts in Rootstock are critical, and the most important setup link for the Cost Transaction Export (which creates QuickBooks Journals), from Rootstock to QuickBooks. In Rootstock, these exist as syqbcoa__c records, which can be viewed/maintained via the Chart of Accounts process. The Reference Number field must contain the appropriate account reference number in QuickBooks Online. If any G/L Account records have an empty Reference Number then setup is not complete, and any transactions which reference that Account will fail.
Chart of Accounts Import (Test of G/A Account import from QuickBooks)
NOTE prior to running Chart of Accounts Import it is best to verify that all required Accounts are properly created in QuickBooks first so this doesn't need to be patched manually or redone. As part of a thorough test, all Rootstock Chart of Accounts (syqbcoa__c) records should be deleted, and imported via Chart of Accounts Import.
IMPORTANT This is not a trivial thing to do since all Rootstock Sub-Ledger Accounts being tested will need to be re-linked to the appropriate newly imported G/L Account.
Class (optional)
Dimension 1 on Rootstock Sales Invoice and Payable Invoice.
Department (optional)
Dimension 2 on Sales Invoice and Payable Invoice.
Tax Code
Matching by ‘Name’ with the Tax Code values in Rootstock.
Terms
Matching by ‘Name’ with the Terms values in Rootstock.
Required Accounting System (QuickBooks Online) Setup Data
Products
All Products being used for exported Sales Invoices must exist in QuickBooks, matched by ‘Name’. These Products can be manually entered into QuickBooks Online prior to exporting (they are looked up by name so the names must match exactly). Optionally, Rootstock can automatically create Products in QuickBooks, as part of the export process. This option can be activated on the System Defaults page, on the System Setup Menu in Rootstock (QuickBooks Online Auto-Add Products checkbox).
NOTE If Rootstock Sales Order Prepayments are to be used, there is a special prepayment Product that needs to exist in QuickBooks by the name 'PrePayment'. It is created automatically when a prepayment invoice is transferred if the QuickBooks Auto-Add Products option is active. Otherwise, it must be manually added to QuickBooks before attempting the Sales Invoice Export, or the Prepayment Invoice export will fail.
Customers
Customers are automatically added from Rootstock to QuickBooks, if not found in QuickBooks. There should not be anything to do to set up Customers in QuickBooks except for adding ancillary data that is auto-populated by Rootstock (Special Notes, etc.)
Test Customer Match
It is important to make sure when testing that Rootstock can find a Customer by ‘Name’ in QuickBooks, and set the Customer Financial System Customer ID field appropriately.
NOTE When viewing a Customer in QuickBooks the reference ID is the last number of the URL.
Exists as Vendor Error
QuickBooks does not allow an entity to exist as both a Customer and a Vendor (or other types with the same name). Rootstock will mark the Customer Financial System Customer ID field with ‘EXISTS_AS_VEND_ERROR’ if this is found, and transactions for this Rootstock Customer will not be exported until this condition is resolved. As a simple solution, a Customer entity can be created in QuickBooks Online with an altered ‘Name’, and the Customer Financial System Customer ID can be manually set to reference this new Customer entity.
Vendors
Vendors are automatically added from Rootstock to QuickBooks, if not found in QuickBooks. There should not be anything to do to set up Vendors in QuickBooks except for adding ancillary data not auto-created by Rootstock (e.g. Special Notes, etc.).
Test Vendor Match
It is important to make sure when testing that Rootstock can find a Vendor by ‘Name’ in QuickBooks and set the Vendor Financial System Customer ID field appropriately. (When viewing a Vendor in QuickBooks the reference ID is the last number of the URL).
Exists as Customer Error
QuickBooks does not allow an entity to exist as both a Customer and a Vendor (or other types with the same name). Rootstock will mark the Vendor Financial System Customer ID field with ‘EXISTS_AS_CUST_ERROR’ if this is found, and transactions for this Rootstock Vendor will not be exported until this condition is resolved. As a simple solution, a Vendor entity can be created in QuickBooks Online with an altered ‘Name’, and the Vendor Financial System Vendor ID can be manually set to reference this new Vendor entity.
G/L Accounts (Transactions -> Chart of Accounts)
It is important that prior to exporting the Chart of Accounts to verify that each G/L Account has a value for reference number. This number will be the reference number of the G/L Account in Rootstock (this is how the matching is done between Rootstock and QuickBooks).
EXAMPLE Clicking on the view register link of an account row in QuickBooks goes to a URL, with a number at the end. The number will be the reference number of the G/L Account in Rootstock. This is included in the import process.
Class
All class values will need to be manually created in QuickBooks, matching by ‘Name’ with the Rootstock Dimension 1 values to be used.
Department
All department values will need to be manually created in QuickBooks, matching by ‘Name’ with the Rootstock Dimension 2 values to be used.
Tax Code
Tax Codes values will need to be manually entered into QuickBooks, matching by ‘Name’ with the Tax Code values in Rootstock.
Terms
Terms values will need to be manually entered into QuickBooks, matching by ‘Name’ with the Terms values in Rootstock.
SEE ALSO
Rootstock Accounting System Export Processes
Quickbooks Features (Online)
