Field Mapping in the QuickBooks Online Integration

Overview

Field Mapping describes how the fields in two systems are synced with each other. For the Sugar-Quickbooks Online integration, fields are mapped automatically, but you can set up additional custom field mappings. This article describes the different types of field mappings of the integration.

Table of Contents

1. Custom Field Mappings

2. Fixed Field Mappings

3. Sugar Quotes to QuickBooks Estimates or Invoices

4. Optional/Advanced Configurations

1. Custom Field Mappings

If you intend to map a custom QuickBooks field you MUST complete the Installing the QuickBooks Web Connector setup section first before proceeding. You can find instructions for this step here.

Navigate to the Admin screen, scroll to the bottom, and click on the QuickBooks & SugarCRM Field Mapping.

Note: Default field mappings are loaded upon installation, so you do NOT need to set up your own mappings.

Some helpful fields from QuickBooks you may want to map would be customer FirstName, LastName, and MiddleName fields.

1. From the Field Mapping page you can set up custom field mappings between Sugarfields and QuickBooks fields.

2. Each QuickBooks module has its own mapping. To select a different QuickBooks module click on the button of the desired module.

3. To modify a field mapping click on the dropdown menu on any of the existing mappings. Your changes will be instantly saved when you make a selection.

4. To add a new mapping scroll to the bottom of the existing mapped fields and you will see an empty mapping row in green.

5. Select both the Sugar field and the QuickBooks field that you want to map and click on the add button.

Note: Some fields have special meaning or are handled in special ways, and/or do not make sense to map differently. So be very careful when changing the default mapping.

Example: Shipping and billing address fields are specially processed in the back-end during syncs. Although you can change the mapping for these fields, it is possible to map them incorrectly which may cause the sync to have issues or fail completely.

2. Fixed Field Mappings

The default field mappings, as mentioned at the beginning of the Field Mapping section, are automatically loaded when the integration is installed and can be modified as seen in the Custom Field Mappings subsection.

However, there are field mappings between QuickBooks and Sugar that are fixed and therefore cannot be remapped or modified in any way.

These fixed field mappings have either special purposes or require specific processing during syncs. This subsection will cover these fixed field mappings so that you can better understand how data is handled by the integration.

3. Sugar Quotes to QuickBooks Estimates or Invoices

Sugar Quotes are synced to QuickBooks Online Estimates or Invoices. This is determined by the Quote Stage dropdown value of a Sugar Quote (QB Estimate or QB Invoice).

Mappings for this sync are not available for custom mapping, as the sync does special processing to translate the Quote into an Estimate or Invoice. In order for a Sugar Quote to sync to QuickBooks, the quote must meet the following criteria:

1. All items in the quote must be items that exist in QuickBooks and have been synced to the Sugar Product Catalog from the QuickBooks item list.

2. The Billing Account must be matched with a QB Online Customer.

If these criteria have been met then the Sugar Quote will be synced to QuickBooks Online during the next sync.

The field mappings from Sugar Quote to QuickBooks Estimates, Invoices, Purchase Orders or Sales Orders are as follows:

Sugar Quote Field	QuickBooks Field	Notes
Quote Number	P.O. No.
Valid Until	Due Date
Payment Terms	Terms
Billing Account	Customer
Billing Address	Billing Address
Shipping Address	Shipping Address
Tax Rate	Sales Order Tax
Quantity	Ordered
Product	Item
Tax Class	Line Item Taxable	This is inherited from the Product Catalog entry for each product which comes from QuickBooks originally
Unit Price	Rate
Discount	Rate	Line-Item discounts are automatically calculated into the Rate field
Quote Number	Memo	The Sugar Quote Number is inserted into the memo field automatically during the sync in order to reference the Sugar Quote from within QuickBooks
Description	Sales Order Number	This value is passed from QuickBooks to Sugar during the sync and is inserted into the Sugar Quote description field in order to reference the QuickBooks record from within Sugar

The following fields are NOT mapped from Sugar Quotes to QuickBooks Estimates, Invoices, Purchase Orders, or Sales Orders:

Sugar Quote Field	Notes
Opportunity Name
Original P.O. Date
Assigned To
Teams
Currency	The currency will be set by QuickBooks default currency value
Shipping Provider	QuickBooks does not store specific shipping provider information
Display Grand Total	This is a layout option that only applies to Sugar. QuickBooks controls its own Sales Order layout and that may be changed by the user from within QuickBooks.
Display Line Items	This is a layout option that only applies to Sugar. QuickBooks controls its own Sales Order layout and that may be changed by the user from within QuickBooks.
Group Name
Group Stage
Shipping	This field is automatically set by QuickBooks, defaulting to the default shipping provider set for the customer.

Note: If you are exporting Quotes from Sugar and are importing them into QuickBooks the fields will be mapped in a similar manner.

4. Optional/Advanced Configurations

Using a Custom Sync-Key Mapping for Accounts/Customers

Note: You will need to have the QuickBooks Web Connector installed and configured in order to complete the following steps.

By default, the QuickBooks integration matches Sugar Accounts and QuickBooks Customers by the primary email address field.

Please see the How to sync Accounts/Customers between Sugar and QuickBooks article for more detail on how this default mapping works.

By creating a Custom Sync-Key the integration will match Sugar Accounts to QuickBooks Customers based on the values in the fields set by the sync-key.

Note: It is recommended that you use the DEFAULT settings for this integration.

WARNING: Improper configuration of these settings can cause the sync to have issues which may result in duplicate Account/Customer entries being created or the sync could fail entirely.

1. To set up a custom sync-key go to the Advanced Configuration Tab on the QuickBooks Integration Configuration page.

2. On the Advanced Configuration tab click on the Customer Sub-tab and scroll down until you find the Account/Customer Sync Key option.

3. Change the value in the drop-down from Primary Email Address to Custom Mapping.

4. Two new dropdown menus will appear below the former dropdown; these dropdown menus will allow you to choose which field in Sugar and QuickBooks field to match.

Note: It is recommended that you pick a field that will be unique across all Accounts and Customers.

5. Now the integration will match Sugar Accounts to QuickBooks Customers based on the values in the fields chosen in the previous step.