Technical Documentation - QuickBooks Automation Service

1. Overview

The QuickBooks Automation Service is the entry-point layer for all Salesforce Flow / Process Builder-triggered synchronisation with QuickBooks Online (QBO). It exposes a single Invocable Method (callQBService) that Salesforce Automations can call to push records — Customers, Products, or Invoices — into QuickBooks without requiring custom code from the admin configuring the flow.

The service intelligently routes work between:

• Synchronous bulk processing (multiple records → staged in Salesforce with Process_via_Batch__c = true for batch pickup)

• Asynchronous real-time processing (single record → enqueued via QueueableAutomateQBService for an immediate API callout to QBO)

2. Component Architecture

Salesforce Flow / Process Builder
          │
          ▼
┌─────────────────────────────────┐
│  InvocableAutomateQBService     │  ← Global Apex Class (Invocable)
│                                 │
│  callQBService()                │  → Customer / Product
│  createQBInvoiceFromMapping()   │  → Invoice (primary path)
│  QBInvoiceCallout()             │  → Invoice (bulk path)
│  createJournalLedgerRecords()   │  → Journal Entry
│  createErrorRecords()           │  → Failure logging
└────────────┬────────────────────┘
             │ single record
             ▼
┌─────────────────────────────────┐
│  QueueableAutomateQBService     │  ← Queueable + AllowsCallouts
│                                 │
│  execute()                      │
│  createQBCustomer()             │  → HTTP POST to QBO API
│  createQBInvoice()              │  → HTTP POST to QBO API
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  WS_Quickbooks                  │  ← OAuth + QBO REST API
└─────────────────────────────────┘

Supporting Classes:
  CMQBConnectorUtility   → FLS, request/record factory methods
  QBApiDataWrapper       → Request/Response wrapper models
  Data                   → CRUD + FLS enforced DML
  QuickbooksController   → Customer/Product ID resolution

3. Class Reference

3.1 InvocableAutomateQBService

File: force-app/main/default/classes/InvocableAutomateQBService.cls Access Modifier: global with sharing

The primary service class. Contains the @InvocableMethod entry point and all orchestration logic.

3.1.1 Method: callQBService

@InvocableMethod(label='Call QB Service' description='This function is responsible to call QB Web Service.')
global static void callQBService(List<QBWrapper> listRecords)

Purpose: Primary invocable entry point for Customer and Product synchronisation. Called directly from Salesforce Flows.

Routing Logic:

Bulk Processing Flow (Customer):

1. Resolves the default or specified QuickBooks Company and Realm ID.

2. Queries cm_finance__Custom_Field_Mapping__c for the sObject's field-to-QB mapping.

3. Dynamically queries the source sObject for all mapped fields.

4. Calls QuickbooksController.getRelatedQuickbooksCustomers() to detect if a QB Customer record already exists (update vs. create decision).

5. Builds QBApiDataWrapper.QBRequestWrapper per record and calls WS_Quickbooks.createCustomerResponseWrapper().

6. Creates or upserts cm_finance__Quickbooks_Customer__c records using Composite_Unique_Key__c (QB_Id::Customer::RealmId) as the upsert key.

7. Sets Process_via_Batch__c = true and Ignore_Webhook__c = true on all staged records.

Bulk Processing Flow (Product):

1. Same company/mapping resolution as Customer.

2. Resolves optional Account QB IDs for Income, Expense, and Asset account lookups.

3. Builds product response wrappers and maps SF account record IDs → QB account IDs.

4. Creates or upserts cm_finance__Quickbooks_Product__c records using Composite_Unique_Key__c (QB_Id::Product::RealmId).

3.1.2 Method: createQBInvoiceFromMapping (Currently Active)

global static void createQBInvoiceFromMapping(List<QBWrapper> listRecords)

Purpose: Primary invoice creation path. Uses cm_finance__Custom_Field_Mapping__c configuration to dynamically build an invoice from any source sObject. This is the recommended and currently active method for invoice automation.

Prerequisites (must be configured in cm_finance__Custom_Field_Mapping__c):

Processing Flow:

1. Resolve QB company from QBWrapper.oRequestWrapper.companyId
2. Query Custom_Field_Mapping__c for Mapping_Type__c = 'Invoice' and matching sObject
3. Extract all required SF field names from all mapping configurations
4. Query source sObject for all fields in one SOQL
5. For each record:
   a. Build QBApiDataWrapper.Invoice via populateField() from cm_finance__Field_Mapping__c
   b. Resolve QB Customer ID via cm_finance__Source_Invoice_Customer_Lookup_field__c
      → If no QB Customer found for 1 record: auto-trigger callQBService() to create it first
      → If no QB Customer found for >1 record: log Failed invoice record
   c. Build Line Items from child sObjects via Invoice_Product_Pre_Population_Mapping__c
      → Resolves QB Product IDs from cm_finance__Quickbooks_Product__c
      → Resolves QB Class IDs from cm_finance__Quickbooks_Class__c
   d. Populate QB Custom Fields from cm_finance__QB_Custom_Fields_Mapping__c
6. Call QBInvoiceCallout() with all valid requests
7. Any pre-validation failures → insert Failed cm_finance__Quickbooks_Invoice__c records immediately

Line Item Mapping Configuration (Invoice_Product_Pre_Population_Mapping__c JSON structure):

{
  "query": "SELECT Id, {0}, ProductId__c, UnitPrice__c, Quantity__c, Description__c, QBClass__c FROM OpportunityLineItem WHERE {0} IN :parentRecordId",
  "lookupFieldName": "OpportunityId",
  "fieldMapping": {
    "sfProductId": "ProductId__c",
    "ProductQuantity": "Quantity__c",
    "ProductUnitPrice": "UnitPrice__c",
    "ProductDescription": "Description__c",
    "QBClassLookup": "QBClass__c"
  }
}

Failure Modes & Error Records Created:

3.1.3 Method: QBInvoiceCallout

global static void QBInvoiceCallout(List<QBWrapper> listRecords)

Purpose: Second-stage invoice processor. Accepts pre-built QBApiDataWrapper.Invoice objects inside QBWrapper.oRequestWrapper and stages them for QB sync.

Routing:

Bulk Lookup Resolution:

The bulk path resolves all lookups in-memory before DML, performing 4 SOQL queries against:

1. cm_finance__Quickbooks_Customer__c → maps QB_Id::CompanyRecordId → SF Customer Record Id

2. cm_finance__Quickbooks_Product__c → maps QB_Id::CompanyRecordId → SF Product Record Id

3. cm_finance__Quickbooks_Class__c → maps QB_Id::CompanyRecordId → SF Class Record Id

4. cm_finance__Quickbooks_Custom_Field__c → maps DefinitionId~CompanyRecordId → SF Custom Field Record Id

Custom Field Encoding: Custom field values are temporarily stored in cm_finance__Custom_Field_1__c / _2__c / _3__c using the format DefinitionId::FieldValue. The method splits this, resolves the SF Custom Field record ID, and writes the final value.

3.1.4 Method: createQBSalesReceiptFromMapping (Currently Active)

global static void createQBSalesReceiptFromMapping(List<QBWrapper> listRecords)

Purpose: Primary Sales Receipt creation path. Uses cm_finance__Custom_Field_Mapping__c configuration to dynamically build a Sales Receipt from any source sObject. This is the recommended and currently active method for Sales Receipt automation.

Prerequisites (must be configured in cm_finance__Custom_Field_Mapping__c):

Processing Flow:

1. Resolve QB company from QBWrapper.oRequestWrapper.companyId
2. Query Custom_Field_Mapping__c for Mapping_Type__c = 'SalesReceipt' and matching sObject
3. Extract all required Salesforce field names from the mapping configurations
4. Query the source sObject for all fields in one SOQL query
5. For each record:
   a. Build QBApiDataWrapper.SalesReceipt via populateField() from cm_finance__Field_Mapping__c
   b. Resolve the QB Customer ID via cm_finance__Source_Invoice_Customer_Lookup_field__c
      → If no QB Customer is found for 1 record: auto-trigger callQBService() to create it first
      → If no QB Customer is found for >1 record: log a Failed Sales Receipt record
   c. Build line items from child sObjects via Invoice_Product_Pre_Population_Mapping__c
      → Resolve QB Product IDs from cm_finance__Quickbooks_Product__c
      → Resolve QB Class IDs from cm_finance__Quickbooks_Class__c
   d. Populate QB custom fields from cm_finance__QB_Custom_Fields_Mapping__c
6. Call QBSalesReceiptCallout() with all valid requests
7. Insert Failed cm_finance__Quickbooks_Sales_Receipt__c records for pre-validation failures

Line Item Mapping: Uses the configured child-record query, parent lookup field, product field, quantity, unit price, description, and optional QB Class lookup to build Sales Receipt line items. Product and Class references are resolved from their corresponding QuickBooks mapping records before the request is sent.

Failure Modes & Error Records Created:

3.1.5 Method: QBSalesReceiptCallout

global static void QBSalesReceiptCallout(List<QBWrapper> listRecords)

Purpose: Second-stage Sales Receipt processor. Accepts pre-built QBApiDataWrapper.SalesReceipt objects inside QBWrapper.oRequestWrapper and either sends them through the real-time queueable path or stages them for bulk QB synchronisation.

Routing:

Bulk Lookup Resolution:

The bulk path resolves all references in memory before DML, using Salesforce mapping records for:

1. cm_finance__Quickbooks_Customer__c → QB Customer ID to Salesforce Customer record

2. cm_finance__Quickbooks_Product__c → QB Product ID to Salesforce Product record

3. cm_finance__Quickbooks_Class__c → QB Class ID to Salesforce Class record

4. cm_finance__Quickbooks_Custom_Field__c → Definition ID and company to Salesforce Custom Field record

5. cm_finance__Payment_Method__c → QB Payment Method ID to Salesforce Payment Method record

6. 1. cm_finance__Quickbooks_Account__c → QB Account ID to Salesforce QB Account record

Custom Field Encoding: Custom field values are temporarily stored in cm_finance__Custom_Field_1__c, _2__c, and _3__c using the format DefinitionId::FieldValue. The method splits each value, resolves the Salesforce Custom Field record ID, and writes the final value to the staged Sales Receipt record.

3.1.6 Method: createErrorRecords

public static void createErrorRecords(List<QBWrapper> listRecords)

Purpose: Fallback error handler. Creates Failed status records in the corresponding QB object for each item in the list, using upsert on cm_finance__Parent_Record_Id__c.

3.1.7 Method: createJournalLedgerRecords

global static Map<String, Object> createJournalLedgerRecords(List<QBWrapper> lstRecords)

Purpose: Delegates journal ledger creation to QuickbooksController.createJournalLedgerInQuickbooks().

Required QBWrapper Fields:

Return Value: Map<String, Object> with keys:

• isSuccess (Boolean)

• message (String) — error detail if isSuccess = false

3.2 Inner Class: QBWrapper

global class QBWrapper { ... }

The data transfer object passed to all invocable and static methods in this service. Fields marked with @InvocableVariable are directly assignable from Salesforce Flows.

3.3 QueueableAutomateQBService

File: force-app/main/default/classes/QueueableAutomateQBService.cls Access Modifier: public with sharing Implements: Queueable, Database.AllowsCallouts

Handles the real-time single-record path. Enqueued by InvocableAutomateQBService when listRecords.size() == 1.

Method: execute

Routes to createQBCustomer(), createQBSalesReceipt() or createQBInvoice() based on requestType.

Customer → Invoice Chaining: After a Customer is successfully created in QBO:

• If the wrapper also contains a pre-built oRequestWrapper.oInvoice, the method automatically re-enqueues itself with requestType = 'Invoice'.

• This enables a customer-first, invoice-second sequential flow in a single automation trigger.

Flow execution:
  Queueable[1]: requestType='Customer'
    → Creates customer in QBO
    → If invoice is pending in wrapper:
        enqueue Queueable[2]: requestType='Invoice'

  Queueable[2]: requestType='Invoice'
    → Creates invoice in QBO, sets customerRef from Queueable[1] result

Customer → Sales Receipt Chaining: After a Customer is successfully created in QBO:

• If the wrapper also contains a pre-built oRequestWrapper.oSalesReceipt, the method automatically re-enqueues itself with requestType = 'SalesReceipt'.

• This enables a customer-first, sales receipt-second sequential flow in a single automation trigger.

Flow execution:
  Queueable[1]: requestType='Customer'
    → Creates customer in QBO
    → If sales receipt is pending in wrapper:
        enqueue Queueable[2]: requestType='SalesReceipt'

  Queueable[2]: requestType='SalesReceipt'
    → Creates sales receipt in QBO, sets customerRef from Queueable[1] result

Method: createQBCustomer

public static List<cm_finance__Quickbooks_Customer__c> createQBCustomer(InvocableAutomateQBService.QBWrapper oReqWrapper)

Steps:

1. Resolves QB Company and Realm ID.

2. Calls CMQBConnectorUtility.getQBObjectMapping() to get Customer field mapping for the source sObject.

3. Queries source sObject for all mapped fields.

4. Checks for existing QB Customer (update scenario) via QuickbooksController.getRelatedQuickbooksCustomers().

5. Calls WS_Quickbooks.createCustomer() — live HTTP callout to QBO.

6. On success: enriches and upserts cm_finance__Quickbooks_Customer__c using Composite_Unique_Key__c.

7. On failure: upserts a Failed status Customer record using Parent_Record_Id__c.

Composite Unique Key format: {QB_Id}::Customer::{RealmId}

Method: createQBInvoice

public static void createQBInvoice(InvocableAutomateQBService.QBWrapper oWrapper)

Steps:

1. Validates QB Company.

2. Calls WS_Quickbooks.createInvoice() — live HTTP callout to QBO.

3. Resolves all reference lookups (Customer, Product, Class, Custom Fields) from Salesforce.

4. Sets invoice status to Invoice PDF Pending if GenerateInvoicePDF setting is true, else Awaiting Salesforce Sync.

5. Inserts cm_finance__Quickbooks_Invoice__c and child cm_finance__Quickbooks_Invoice_Item__c records.

6. Sets Composite_Unique_Key__c ({QB_Id}::{RealmId}) and Ignore_Webhook__c = true.

7. On failure: upserts a Failed status invoice record.

Method: createQBSalesReceipt

public static void createQBSalesReceipt(InvocableAutomateQBService.QBWrapper oWrapper)

Steps:

1. Validates QB Company.

2. Calls WS_Quickbooks.createQBSalesReceipt() — live HTTP callout to QBO.

3. Resolves all reference lookups (Customer, Product, Class, Custom Fields, Payment Method, QB Account) from Salesforce.

4. Sets sales receipt status to Sales Receipt PDF Pending if GenerateSalesReceiptPDF setting is true, else Awaiting Salesforce Sync.

5. Inserts cm_finance__Quickbooks_Sales_Receipt__c and child cm_finance__Quickbooks_Sales_Receipt_Item__c records.

6. Sets Composite_Unique_Key__c ({QB_Id}::{RealmId}) and Ignore_Webhook__c = true.

7. On failure: upserts a Failed status invoice record.

3.4 Supporting Class: CMQBConnectorUtility

File: force-app/main/default/classes/CMQBConnectorUtility.cls Access Modifier: public with sharing

Central utility class used by all automation service classes.

3.5 Supporting Class: QBApiDataWrapper

File: force-app/main/default/classes/QBApiDataWrapper.cls Access Modifier: global with sharing

All data models for the QB API integration layer.

Key Wrapper Classes

Entity Classes

Supporting Classes

4. End-to-End Flow Diagrams

4.1 Customer Automation (Single Record)

Flow triggers with 1 Customer record
  │
  ▼
callQBService()
  │
  ├── size == 1 AND type != 'Product'
  │       │
  │       ▼
  │   System.enqueueJob(QueueableAutomateQBService)
  │       │
  │       ▼
  │   execute() → createQBCustomer()
  │       │
  │       ├── [Success] → Upsert cm_finance__Quickbooks_Customer__c
  │       │                Status: 'Awaiting Salesforce Sync'
  │       │                Composite_Unique_Key__c set
  │       │
  │       └── [Failure] → Upsert cm_finance__Quickbooks_Customer__c
  │                        Status: 'Failed', error in Status_Description__c
  │
  └── (end)

4.2 Invoice Automation (Single Record) — Primary Path

Flow triggers with 1 Invoice record
  │
  ▼
createQBInvoiceFromMapping()
  │
  ├── Resolve Custom Field Mapping for source sObject + company
  ├── Query source sObject fields
  ├── Resolve QB Customer ID from lookup field
  │       │
  │       ├── [QB Customer Not Found, 1 record]
  │       │       │
  │       │       ▼
  │       │   callQBService() → creates Customer first
  │       │   (Invoice creation deferred to Queueable chain)
  │       │
  │       └── [QB Customer Found]
  │               │
  │               ▼
  │           Build Invoice + Line Items + Custom Fields
  │               │
  │               ▼
  │           QBInvoiceCallout()
  │               │
  │               ├── size == 1
  │               │       │
  │               │       ▼
  │               │   System.enqueueJob(QueueableAutomateQBService)
  │               │       │
  │               │       ▼
  │               │   createQBInvoice() → Live API callout
  │               │       │
  │               │       ├── [Success] → Insert Invoice + Invoice Items
  │               │       │               Status: 'Invoice PDF Pending' or 'Awaiting Salesforce Sync'
  │               │       │
  │               │       └── [Failure] → Upsert Invoice, Status: 'Failed'
  │               │
  │               └── (end)
  │
  └── (end)

4.3 Bulk Customer/Product Automation

Flow triggers with N records (N > 1 or type = 'Product')
  │
  ▼
callQBService()
  │
  ├── Resolve QB Company + Realm ID
  ├── Query Custom_Field_Mapping__c
  ├── Dynamically query source sObjects
  ├── For each record: build QBApiDataWrapper request wrapper
  │       (no live API callout here)
  ├── Create/Upsert cm_finance__Quickbooks_Customer__c or Product records
  │       Status: 'Awaiting QB Sync'
  │       Process_via_Batch__c = true
  │       Ignore_Webhook__c = true
  │
  └── Batch job picks up records and performs live QB API callout

4.4 Sales Receipt Automation (Single Record) — Primary Path

Flow triggers with 1 Sales Receipt record
  │
  ▼
createQBSalesReceiptFromMapping()
  │
  ├── Resolve Custom Field Mapping for source sObject + company
  ├── Query source sObject fields
  ├── Resolve QB Customer ID from lookup field
  │       │
  │       ├── [QB Customer Not Found, 1 record]
  │       │       │
  │       │       ▼
  │       │   callQBService() → creates Customer first
  │       │   (Sales Receipt creation deferred to Queueable chain)
  │       │
  │       └── [QB Customer Found]
  │               │
  │               ▼
  │           Build Sales Receipt + Line Items + Custom Fields
  │               │
  │               ▼
  │           QBSalesReceiptCallout()
  │               │
  │               ├── size == 1
  │               │       │
  │               │       ▼
  │               │   System.enqueueJob(QueueableAutomateQBService)
  │               │       │
  │               │       ▼
  │               │   createQBSalesReceipt() → Live API callout
  │               │       │
  │               │       ├── [Success] → Insert Sales Receipt + Sales Receipt Items
  │               │       │               Status: 'Sales Receipt PDF Pending' or
  │               │       │               'Awaiting Salesforce Sync'
  │               │       │
  │               │       └── [Failure] → Upsert Sales Receipt, Status: 'Failed'
  │               │
  │               └── (end)
  │
  └── (end)

4.4 Sales Receipt Automation (Single Record) — Primary Path

Flow triggers with 1 Sales Receipt record
  │
  ▼
createQBSalesReceiptFromMapping()
  │
  ├── Resolve Custom Field Mapping for source sObject + company
  ├── Query source sObject fields
  ├── Resolve QB Customer ID from lookup field
  │       │
  │       ├── [QB Customer Not Found, 1 record]
  │       │       │
  │       │       ▼
  │       │   callQBService() → creates Customer first
  │       │   (Sales Receipt creation deferred to Queueable chain)
  │       │
  │       └── [QB Customer Found]
  │               │
  │               ▼
  │           Build Sales Receipt + Line Items + Custom Fields
  │               │
  │               ▼
  │           QBSalesReceiptCallout()
  │               │
  │               ├── size == 1
  │               │       │
  │               │       ▼
  │               │   System.enqueueJob(QueueableAutomateQBService)
  │               │       │
  │               │       ▼
  │               │   createQBSalesReceipt() → Live API callout
  │               │       │
  │               │       ├── [Success] → Insert Sales Receipt + Sales Receipt Items
  │               │       │               Status: 'Sales Receipt PDF Pending' or
  │               │       │               'Awaiting Salesforce Sync'
  │               │       │
  │               │       └── [Failure] → Upsert Sales Receipt, Status: 'Failed'
  │               │
  │               └── (end)
  │
  └── (end)

4.4 Sales Receipt Automation (Single Record) — Primary Path

5. Custom Object Record Lifecycle

6. Configuration Reference

6.1 cm_finance__Custom_Field_Mapping__c

This object drives all dynamic field mapping. One record per sObject per company per mapping type.

6.2 cm_finance__Quickbooks_Common_Settings__c (Custom Setting)

7. Configuring a Flow Automation

Step 1 — Set Up Field Mapping

Create a cm_finance__Custom_Field_Mapping__c record:

Source:                 Quickbooks
sObject API Name:       Opportunity  (or any source object)
Mapping Type:           Invoice
QB Company:             [Your QB Company record]
Field Mapping:          {"txnDate": "CloseDate", "dueDate": "DueDate__c"}
Customer Lookup Field:  AccountId
Product Pre-Population: { "query": "SELECT Id, {0}, Product2Id, UnitPrice, Quantity FROM OpportunityLineItem WHERE {0} IN :parentRecordId", "lookupFieldName": "OpportunityId", "fieldMapping": { "sfProductId": "Product2Id", "ProductQuantity": "Quantity", "ProductUnitPrice": "UnitPrice" } }

Step 2 — Configure the Flow

1. Add an Action element to your Flow.

2. Search for "Call QB Service" (the @InvocableMethod label).

3. Map the following input variables:

4. For Invoice flows, the oRequestWrapper is built internally by createQBInvoiceFromMapping() — no additional mapping needed in the Flow.

Step 3 — Invoke createQBInvoiceFromMapping for Invoice Flows

For invoice automations, do not call callQBService directly from the Flow. Instead, call createQBInvoiceFromMapping from Apex (e.g., a trigger or invocable wrapper) that passes the QBWrapper list with oRequestWrapper.companyId pre-populated.

8. Error Handling Summary

Note: Exceptions in the main methods are caught silently (debug only). Monitor debug logs or the Failed status records in QB custom objects to diagnose automation issues.

9. Key Design Decisions