Salesforce to QuickBooks Desktop — SmartTracks Training for Signal Underwriting

1.1The problem being solved

Before SmartTracks, a bound policy existed twice: once in Salesforce as the underwriting record of truth, and once in QuickBooks Desktop as a manually re-typed invoice. Every re-entry was a chance for the premium, fee, or carrier to drift out of sync with what underwriting actually bound. SmartTracks removes the second entry point — Salesforce stays the source of truth for policy detail, and QuickBooks Desktop receives it automatically.

1.2The five SmartTracks layers

Every SmartTracks integration, including this one, runs on five layers: SmartAgents watch for qualifying changes (like a submission moving to Bound) and decide what needs to happen next; Flow Copilot is the tool your admin team used to build and adjust the sync logic without writing code; SmartFlows are the adaptive workflows that actually carry a record from Salesforce to QuickBooks Desktop, healing themselves around minor hiccups like a temporary connection drop; SmartIntegration Hub is the central engine that both systems talk to, so neither Salesforce nor QuickBooks Desktop ever talks to the other directly; and the Connector Ecosystem — specifically the QuickBooks Web Connector for this engagement — is the piece that bridges the Hub to a desktop application that has no cloud API of its own.

1.3Source of truth, by data type

Underwriting detail — insured, coverage lines, effective dates, premium as quoted — originates in Salesforce. Financial detail once the policy is on the books — invoice numbers, payment status, commission payable — originates in QuickBooks Desktop. SmartTracks keeps both in sync, but it does not make either system authoritative for data it wasn't designed to own.

2.1Creating a submission

Every new business or renewal submission starts as an Opportunity on the relevant Account (the agency or, for direct business, the insured). Fill in the Carrier lookup, effective and expiration dates, and at least one coverage line item before moving the record out of the Quoting stage — these four fields anchor everything SmartAgents will later map into QuickBooks Desktop.

2.2What triggers a sync

Nothing syncs while a submission is being quoted or negotiated. The sync trigger is a single, deliberate event: the Opportunity Stage changing to Bound. That change tells the SmartAgent watching Salesforce that the record is final enough to post as a Customer:Job and Invoice in QuickBooks Desktop.

2.3Why line items matter

A single premium total isn't enough for accounting — QuickBooks Desktop needs each coverage line, fee, and any surplus lines tax broken out separately, because each maps to its own Item and may carry its own Class for reporting. Enter premium and fees as separate Opportunity Line Items rather than folding them into one number; Module 04 shows exactly where each line lands on the QuickBooks Desktop invoice.

3.1The Sync Status field

Every Opportunity that has passed through Bound carries a Sync Status of Pending, Synced, or Held. Pending means the next scheduled Web Connector poll hasn't run yet — this typically clears within the sync window. Synced means the Customer:Job and Invoice exist in QuickBooks Desktop; the QuickBooks Invoice # is written back onto the Opportunity as confirmation. Held means the SmartAgent found something it can't resolve on its own, and the Hold Reason field explains why.

3.2Missing Carrier hold

The most common hold is a blank or unrecognized Carrier lookup — QuickBooks Desktop needs a matching Vendor record to post commission against. Fill in or correct the Carrier field and save; the record re-queues for the next poll automatically.

3.3Duplicate Account hold

If two Accounts exist for what's really one insured (a common result of a walk-in quote followed by an agency-submitted one), the SmartAgent holds rather than guessing which Customer:Job to post against. Merge the duplicate Accounts in Salesforce using standard merge tools, and the hold clears on the next poll.

3.4When to escalate instead

Anything involving a QuickBooks Desktop-side error — an Item that won't post, a Class that no longer exists, a Web Connector that hasn't polled in over an hour — is an Admin/IT issue, not a self-service fix. See Module 07 for how to route it.

4.1Why this mapping is fixed

The mapping below is defined once in Flow Copilot and applies to every Bound Opportunity — it isn't re-negotiated per record. Understanding it is what lets Admin/IT diagnose a Held record or a posting error without opening a support ticket for every occurrence.

4.2Reading the table

Each row names a Salesforce object or field on the left and its QuickBooks Desktop destination on the right. Objects map to QuickBooks Desktop lists (Customer:Job, Item, Vendor); the Opportunity itself maps to a QuickBooks Desktop transaction (Invoice), since a bound policy is a financial event, not a standing record.

5.1Why QuickBooks Desktop needs a connector

QuickBooks Online exposes a REST API that a cloud platform can call directly. QuickBooks Desktop does not — the company file lives on a machine inside Signal Underwriting's network, with no public endpoint. The QuickBooks Web Connector (QBWC) bridges that gap: it's a small Windows service, installed on the same machine as the QuickBooks Desktop company file, authorized with a one-time .QWC file issued by InterWeave. QBWC polls the SmartIntegration Hub on a schedule (by default every 10 minutes during business hours), pulls down any queued requests as signed SOAP/XML messages, and applies them to the local company file through QuickBooks' own SDK.

5.2Reading the polling log

QBWC keeps a local log on the host machine showing each poll attempt, whether it authenticated, and how many requests it processed. A healthy log shows a poll roughly every 10 minutes with a non-error result. Gaps longer than the polling interval usually mean QuickBooks Desktop itself wasn't open in single-user mode at poll time — QBWC can't write to the company file while it's closed or in multi-user mode without the right permissions.

5.3The error queue

When a QBWC request fails — a missing Item, an inactive Vendor, a locked company file — it lands in the SmartIntegration Hub's error queue rather than retrying silently forever. Each entry shows the originating Opportunity, the QuickBooks-side error text, and a retry action. Most entries clear once the underlying QuickBooks Desktop object (the missing Item or Vendor) is created or reactivated; retry from the Hub rather than re-triggering the Salesforce record.

5.4Credential rotation

The .QWC authorization file and its paired password are scoped per company file and expire on a fixed schedule. InterWeave issues a replacement ahead of expiry — reauthorize QBWC with the new file promptly, since an expired credential simply stops polling rather than raising an alert on the Salesforce side.

6.1Why hierarchy matters here

Signal Underwriting writes business both through retail agencies and direct with insureds. QuickBooks Desktop's Customer:Job structure mirrors that: the agency posts as the top-level Customer, and each insured they place posts as a Job nested underneath. Direct business posts the insured as a top-level Customer with no parent. This keeps agency-level commission statements and per-insured invoice history both queryable without duplicating data.

6.2Class tracking for line of business

Signal Underwriting reports profitability by line of business — General Liability, Property, E&O, and so on. Rather than creating separate Item lists per line, SmartFlows tag every invoice line with a QuickBooks Class matching the Salesforce Coverage Line value (see Module 04). This lets Signal's accounting team run Profit & Loss by Class in QuickBooks Desktop natively, without a manual export-and-pivot step.

6.3Where hierarchy rules live

The rule that decides whether an Account posts as a top-level Customer or a Job (and under which parent) is maintained in Flow Copilot's mapping configuration, not in Salesforce or QuickBooks Desktop directly. Changes to this rule are a change request per Module 07 — they affect every future sync, not just one record.

7.1Three tiers, one decision

Before opening a ticket, ask whether this is (a) something you can look up, (b) a stuck record with no unusual cause, or (c) something specific to how Signal Underwriting's integration is configured. Those map directly to the three support tiers below.

7.2Sync problem vs. change request

A sync problem is a record that should have synced under the existing rules and didn't. A change request is a request for the rules themselves to be different — a new Item, a different Class scheme, a hierarchy change. Change requests always go to the Signal Underwriting Account Team, since they affect every future record, not just the one in front of you.