Custom Metadata Reference Guide | Cloud Maven

This page provides the information about the custom metadata records needed during Quickbooks setup.

Steps to open custom metadata-

Navigate to Setup.
Search Custom Metadata in Quick Find box.
Look for CM QB Connector Settings in the list.
Make sure to check for the below values in CM QB Connector Settings:

This custom metadata type stores connector configuration settings for the QuickBooks–Salesforce integration. All records use a single Value__c field to hold either a SOQL WHERE clause string or a JSON configuration object.

Name	Description	Default Value
AdminConsoleHelpTextConfig	JSON map of admin console screen keys to their corresponding Confluence help article URLs. Used to render contextual help links throughout the Admin Console UI.	JSON object with URLs for `connectionScreen`, `configureClientScreen`, `syncDataScreen`, `mapDataScreen`, `assignPermissionScreen`, and `contactSupportScreen`
AutoMatch_QBCustomerJson	JSON configuration that drives the auto-match logic between Salesforce Account records and QuickBooks Customer records. Defines the SF object, QB object, the flag field that marks a record as auto-matched, and the list of fields to compare (Website, Phone, Company Name, Email).	JSON config targeting `cm_finance__Quickbooks_Customer__c` with four match fields: Website, Phone, Company Name, Email
BatchAllQBSFAccountsSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Accounts full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFAllBudgetSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Budgets full batch sync (`BatchAllQBSFBudgetSync`). Leave blank to sync all records.	(empty)
BatchAllQBSFBillSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Bills full batch sync (`BatchAllQBSFBillSync`). Leave blank to sync all records.	(empty)
BatchAllQBSFClassSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Classes full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFCustomerSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Customers full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFInvoiceSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Invoices full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFPaymentSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Payments full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFProductSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Products full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFTaxRateSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Tax Rates full batch sync. Leave blank to sync all records.	(empty)
BatchAllQBSFVendorSync_WhereClause	Optional SOQL WHERE clause appended to the query when running the QB → SF Vendors full batch sync. Leave blank to sync all records.	(empty)
BatchSFQBBillSync_WhereClause	SOQL WHERE clause used by the SF → QB Bill batch job (`BatchSFQBBillSync`) to filter which bill sync records to process. Protected — modify with caution.	`WHERE Process_via_Batch__c = true AND Status__c != 'Failed'`
BatchSFQBCustomerSync_WhereClause	SOQL WHERE clause used by the SF → QB Customer batch job to filter which customer sync records to process. Protected — modify with caution.	`WHERE Process_via_Batch__c = true AND Status__c != 'Failed'`
BatchSFQBInvoiceSync_WhereClause	SOQL WHERE clause used by the SF → QB Invoice batch job to filter which invoice sync records to process. Protected — modify with caution.	`WHERE Process_via_Batch__c = true AND Status__c != 'Failed'`
BatchSFQBProductSync_WhereClause	SOQL WHERE clause used by the SF → QB Product batch job to filter which product sync records to process. Protected — modify with caution.	`WHERE Process_via_Batch__c = true AND Status__c != 'Failed'`
BatchSFQBVendorSync_WhereClause	SOQL WHERE clause used by the SF → QB Vendor batch job to filter which vendor sync records to process. Protected — modify with caution.	`WHERE Process_via_Batch__c = true AND Status__c != 'Failed'`
BulkInvoiceFieldConfig	JSON array defining the columns shown in the Bulk Invoice creation UI. Each entry specifies `fieldName`, `dataType`, `isRequired`, and `lookupType` for lookup fields.	JSON with 7 fields: QuickbooksCompanyId, CustomerId, ProductId, InvoiceDate, Terms (Days), Quantity, UnitPrice
SalesTermMapping	JSON map that translates QuickBooks sales term names to their equivalent number of days. Used to convert QB payment terms during sync.	`{"Net30": 30, "Net60": 60, "Net90": 90}`

Notes

BatchAllQBSF* records are empty by default — the batch jobs will process every record. Populate Value__c with a valid SOQL WHERE clause (including the WHERE keyword) to filter for large orgs.
BatchSFQB* records are marked protected. Their default clause ensures only records queued for batch processing and not already failed are picked up. Changing these can affect core sync reliability.
JSON config records (AdminConsoleHelpTextConfig, AutoMatch_QBCustomerJson, BulkInvoiceFieldConfig, SalesTermMapping) store structured JSON — ensure the JSON remains valid after any edits.
BatchAllQBSFAllBudgetSync_WhereClause is not shipped with the package — create it only if you need to filter the Budget full sync. Note that its name contains an extra All compared to the other BatchAllQBSF* records; the record must be created with exactly this name to be picked up.

QB Error Mapping

This custom metadata type maps a QuickBooks API error to a friendly message. The friendly message is shown to users instead of the technical QuickBooks text. Each record has one error to look for and the message to show instead.

Steps to open QB Error Mapping

Navigate to Setup.
Search Custom Metadata Types in the Quick Find box.
Click Manage Records next to QB Error Mapping.

Fields

Field	Description
Label / QB Error Mapping Name	Name of the record, for example `Duplicate_Name`.
QB Error Message (`QB_Error_Message__c`)	Text to look for in the QuickBooks error. The match is not case-sensitive, and the text only has to appear somewhere in the error.
Friendly Message (`Friendly_Message__c`)	Message the user sees when the error matches. Up to 500 characters.
Is Active (`Is_Active__c`)	Untick to turn a mapping off without deleting it.

Default records

Name	QuickBooks error contains	Friendly message
`Duplicate_Name`	`Duplicate Name Exists Error`	A record with this name already exists in QuickBooks. Rename it or link it to the existing record.
`Object_Not_Found`	`Object Not Found`	This record no longer exists in QuickBooks. Please re-sync it.
`Stale_Object`	`Stale Object Error`	This record was changed in QuickBooks. Refresh and try again.
`Required_Line_Missing`	`Required parameter Line is missing`	At least one line item is required. Add a line item and try again.

How an error is matched

QuickBooks returns an error with a message and a detail, for example Required param missing, need to supply the required value for the API: Required parameter Line is missing in the request.
The connector looks for an active record whose QB Error Message appears in that text.
If one matches, the user sees that record's Friendly Message.
If more than one matches, the record with the longest QB Error Message is used.
If nothing matches, the user sees the original QuickBooks text.

How to add a new mapping

On the QB Error Mapping list, click New.
Enter a Label and a Name.
In QB Error Message, enter a short, stable part of the QuickBooks error. Leave out parts that change, such as record IDs or names.
Enter the Friendly Message and make sure Is Active is ticked.
Click Save. The change applies straight away and needs no deployment.

Status Description on failed records

When a sync fails, the record's Status is set to Failed. Its Status Description keeps the friendly message and then adds a Technical details section for support:

At least one line item is required. Add a line item and try again.

----- Technical details -----
QuickBooks error: Required param missing, need to supply the required value for the API: Required parameter Line is missing in the request
Stack trace:
Class.CMQBConnectorUtility.createInvoiceRecord: line ...

The technical details are only on the record. Users see only the friendly message in the UI. Records with any other status keep their description unchanged.

Notes

Mappings only apply to errors that QuickBooks itself returns, such as validation errors. Other messages generated by the connector, such as Apex exceptions, authentication issues and "data not found" messages, are not mapped and show their original text.
Keep QB Error Message specific. A very short or common phrase can match unrelated errors.
To switch a mapping off temporarily, untick Is Active instead of deleting the record.
The QuickBooks error code is not used for matching, only the message text.
Check the Status Description field on a failed record when support needs the original QuickBooks error.