Overview

The VKM QB ↔ SF Desktop Connector is a real-time bidirectional integration between Salesforce CRM and QuickBooks Desktop. It eliminates manual data entry by automatically syncing Accounts, Products, Opportunities, Invoices and more — in both directions.

Prerequisites

System Requirements

Salesforce Requirements

• ✅ Salesforce Connected App (provided by VKM)
• ✅ VKM metadata package deployed
• ✅ OAuth Username-Password Flows enabled
• ✅ System Administrator or custom profile with API access

Installation

The connector is a self-contained Windows application — no installation required. Simply copy the provided folder to your machine and run.

1. 1

   Copy the connector folder

   Extract the provided ZIP file to a permanent location, e.g. C:\VKMConnector\. Do not move it after setup as settings are stored relative to this path.

2. 2

   Open QuickBooks Desktop first

   Launch QuickBooks and open your company file before starting the connector. QuickBooks must be running whenever the connector is active.

3. 3

   Run QBSFConnector.exe

   Double-click QBSFConnector.exe. The connector window will open.

4. 4

   Accept the QuickBooks popup

   On first run, QuickBooks will show a security prompt asking permission for the connector app. Click Yes, Always Allow. This only appears once.

First Sync Setup

1. 1

   Click Settings

   Open the Settings panel and enter your Salesforce credentials. Click Connect to Salesforce — a browser window will open for OAuth login.

2. 2

   Configure QuickBooks connection

   Enter the QB App Name (provided by VKM) and optionally the path to your company file. Leave company file blank to use the currently open file.

3. 3

   Set QB Default Accounts

   Click QB Accounts and enter your QuickBooks Chart of Accounts defaults. These are required for creating Items in QB. Enter names exactly as they appear in QB.

4. 4

   Enter License Key

   Enter the license key provided by VKM and click Verify.

5. 5

   Click Start

   Click the ▶ Start button. Watch the Live Log — you should see Salesforce and QuickBooks both show as Connected within 30 seconds.

Salesforce Setup

Manage Mappings

All field mapping configuration is done from the Manage Mappings button in the Salesforce dashboard. You can view active mappings, upload new ones, and delete existing ones.

Uploading a Mapping CSV

1. 1

   Download the mapping template

   Download QB_SF_Mapping_Template_v3.xlsx from VKM. Each sheet is a separate mapping. Export the sheet you need as CSV.

2. 2

   Open Manage Mappings

   In the Salesforce dashboard, click Manage Mappings → Upload Mapping CSV.

3. 3

   Select your CSV file

   Choose the exported CSV. The filename must contain the entity name: Acct, Product, Oppty, or Invoice. For child mappings, include _CHILD_ in the filename.

4. 4

   Upload and verify

   Click Upload. The mapping will appear in the Active Mappings list immediately.

Connector Settings

QB Default Accounts

Click QB Accounts in the connector to set default Chart of Accounts. These are used when creating Items in QuickBooks. Enter names exactly as they appear in QB (Lists → Chart of Accounts).

Field Mapping

Field mappings define which Salesforce fields sync to which QuickBooks fields. All mappings are configured via CSV upload — no code changes needed.

CSV Format

SF_Field_API_Name,QB_Field_Name,Required (Y/N),Transformation,Default_Value,Notes
Name,Name,Y,Simple,,Customer name
BillingStreet,BillAddr1,N,AddressSplit:1,,First 41 chars of address
BillingStreet,BillAddr2,N,AddressSplit:2,,Address overflow
CustomerRef.ListID,Linked_Account__c,N,Link:Account:QB_Customer_ID__c,,Links to SF Account

Supported Entities

Transformations

Transformations modify field values during sync. Set in the Transformation column of your mapping CSV.

SF → QB Sync

Salesforce changes are automatically detected and synced to QuickBooks on the next connector cycle (default: every 30 seconds).

How it works

1. 1

   Record saved in Salesforce

   When an Account, Product, Opportunity, or Contact is created or updated in SF, an Apex trigger fires automatically.

2. 2

   Job queued

   The trigger creates a record in the sync queue (QBSync_Queue__c) with the record data as payload.

3. 3

   Connector picks up job

   On the next cycle, the connector fetches pending jobs from Salesforce and processes each one through the field mapping engine.

4. 4

   QB record created or updated

   The connector creates or modifies the QB record. If it's a new record, the QB ID is written back to the Salesforce record automatically.

Dependency Order

Triggering a Manual SF → QB Sync

Click ↑ SF → QB button in the Salesforce dashboard to immediately queue all eligible records for sync.

QB → SF Sync

QB → SF sync runs automatically every 10 connector cycles (~5 minutes). You can also trigger it manually from the Salesforce dashboard.

Delta Sync — Only Changed Records

The connector tracks a per-entity timestamp for each QB entity. On each run, only records modified after the last sync timestamp are queried — making subsequent syncs fast regardless of total record count.

Manual QB → SF Trigger

1. 1

   Click ↓ QB → SF in the dashboard

   This queues a manual sync request. The connector picks it up on the next cycle (within 30 seconds).

2. 2

   Confirm the trigger modal

   Click Confirm to proceed. The connector will query QB for all entities that have QB→SF mappings configured.

3. 3

   Watch the Live Log

   In the connector app, you'll see log lines like ✓ Queried 13 QB Customers and ✓ 13 synced, ✗ 0 failed.

Invoice Status

When QB Invoices sync to Salesforce, the Status field is automatically derived:

Salesforce Dashboard

System Status

Action Buttons

QB → SF Sync Timestamps

The timestamp panel shows when each QB entity was last synced to Salesforce. Timestamps control delta sync — only records modified after the timestamp are synced.

Reset Timestamp

Clicking Reset on an entity clears its timestamp. The next QB → SF sync will re-sync all records for that entity from scratch. Use this when:

• • You want to re-sync all QB records after a mapping change
• • SF records were accidentally deleted and need to be recreated
• • Initial migration after going live

Supported Entities

Troubleshooting

Common Issues

QB Connection Failed

1. 1

   Open QB Desktop first

   QuickBooks must be open and a company file loaded before starting the connector.

2. 2

   Check for QB popup

   On first run, QB shows a permission popup. Accept it with "Yes, Always Allow".

3. 3

   Restart both apps

   Close the connector, then close and reopen QB. Start the connector again.

Salesforce Auth Failed

Click Settings → Connect to Salesforce to re-authenticate. If the browser doesn't open, check that ports 8080–8084 are not blocked by your firewall.

Records Not Syncing

Check in order:

• 1. Is the connector running? Check the Live Log for cycle messages.
• 2. Is there an active mapping for that entity? Check Manage Mappings.
• 3. Is the parent record synced first? (Account before Opportunity)
• 4. Check the Recent Activity in the SF dashboard for Failed records.

QB Won't Close

The connector holds a QB session while running. Always click ■ Stop in the connector before closing QuickBooks. Wait for "Sync engine stopped" in the log before closing QB.

Duplicate Records in QB

Should not occur normally — the connector uses external ID upsert. If duplicates appear, verify the QB_Customer_ID__c field on the Account is marked as External ID in Salesforce Setup.

Frequently Asked Questions

Does the connector work with QuickBooks Online?

No. This connector is specifically built for QuickBooks Desktop (Pro, Premier, Enterprise). QuickBooks Online has a different API and is not supported by this connector.

What happens if the connector is offline?

SF changes are queued in QBSync_Queue__c and processed when the connector comes back online. QB→SF sync will catch up from the last timestamp — no records are lost.

Can multiple users trigger syncs simultaneously?

Yes — the queue handles multiple requests. However, only one connector instance should run per QB company file to avoid session conflicts.

How long does a full sync take?

Initial sync depends on record count. Typically: 100 records ≈ 30–60 seconds. Subsequent (delta) syncs are near-instant as only changed records are processed.

Can I add custom fields to the sync?

Yes — add a row to the mapping CSV with the SF API field name and QB field name, then re-upload via Manage Mappings. No developer required.

Is my Salesforce data secure?

Yes. The connector uses OAuth 2.0 — no passwords are stored. All communication is over HTTPS. Data is processed locally on your Windows machine and is never stored by VKM servers.

Support