QuickBooks Desktop
This document outlines the integration with the QuickBooks Desktop connector, enabling the OvalEdge application to connect through the QBXML protocol using the QuickBooks Web Connector (QBWC). The integration leverages a dedicated QBWC Service (csp-qbwc-app) that acts as a REST-to-SOAP bridge, facilitating secure communication between OvalEdge CSP Apps and QuickBooks Desktop. It supports structured metadata extraction through crawling, and data preview, along with secure authentication using QBWC credentials and service-level authentication.
Overview
Connector Details
Connector Category
CSP Apps (Accounting)
OE Application Version
R8.0
QuickBooks Desktop Version
24.0
Connectivity [How the connection is established with QuickBooks Desktop]
QBXML via QuickBooks Web Connector (REST-to-SOAP bridge)
QBXML Versions
16.0, 17.0 (default 17.0)
The QuickBooks Desktop connector has been validated with the mentioned "QuickBooks Desktop Versions" and is expected to be compatible with other supported QuickBooks Desktop Versions. If there are any issues with validation or metadata crawling, please submit a support ticket for investigation and feedback.
Connector Features
Crawling
✅
Profiling
❌
Query Sheet
❌
Data Preview
✅
Auto Lineage
❌
Manual Lineage
❌
Secure Authentication via (QBWC)
✅
Metadata Mapping
The following objects are crawled from QuickBooks Desktop and mapped to the corresponding UI assets.
QuickBooks company file
Container
Database for Tables
Domain for Reports
QuickBooks entity type
Entity
Table
QuickBooks report name
Report
Report
Entity/Report column
Field
Table Column/ Report Column
Set up a Connection
Prerequisites
The following are the prerequisites to establish a connection:
Before configuring the connector, the QuickBooks Desktop environment must be prepared with the target company file, a dedicated QuickBooks user, the QuickBooks Web Connector setup, and the required service credentials. These components are essential for enabling controlled access to the company file and establishing secure communication through the Web Connector. For detailed instructions on setting up these prerequisites, click here.
System & Software Requirements
QuickBooks Desktop
Must be installed on a Windows machine where the company file is hosted
QuickBooks Web Connector (QBWC)
Required to enable SOAP polling and QBXML request execution
QBWC Service (csp-qbwc-app)
Must be installed, running, and accessible by OvalEdge (via REST) and QBWC (via SOAP Polling)
Windows Environment
Required to support QuickBooks Desktop and Web Connector
QuickBooks Company File (.QBW)
A valid company file must be available and accessible to QuickBooks Desktop
External Supporting Services
csp-qbwc-app (QBWC Service)
Acts as a REST-to-SOAP bridge between OvalEdge and QuickBooks Desktop
QuickBooks Web Connector
Polls the SOAP endpoint, executes QBXML, and returns responses
QuickBooks Desktop does not provide a native REST API; all communication is performed through QBXML over SOAP using QuickBooks Web Connector.
The QBWC Service (csp-qbwc-app) is mandatory to bridge REST requests from OvalEdge to SOAP-based QBXML execution.
Ensure the company file path is accessible, Web Connector polling is active, and credentials are valid before validating the connection.
Connection Configuration Steps
Users are required to have the Connector Creator role in order to configure a new connection.
Log into OvalEdge, go to Administration > Connectors, click + (New Connector), search for QuickBooks Desktop, and complete the required parameters.
Fields marked with an asterisk (*) are mandatory for establishing a connection.
Connector Type
By default, "QuickBooks Desktop" is displayed as the selected connector type.
Connector Name*
Enter a unique name for the QuickBooks Desktop connection
(Example: "QuickBooks Desktop_Prod").
Connector description
Enter a brief description of the connector.
Company File Path*
Enter the full file system path to the QuickBooks Desktop company file (.QBW) that will be used for metadata extraction and query execution.
OE QBWC Service URL*
Enter the REST API URL of the OvalEdge QBWC Service (csp-qbwc-app) used to submit requests and retrieve responses from QuickBooks Web Connector (e.g., https://qbwc-service.com)
Username*
Enter the QuickBooks Web Connector (QBWC) username required to authenticate access to the QuickBooks Desktop company file.
File Open Mode*
Select the mode in which the company file should be opened: Single-user or Multi-user based on operational requirements.
QBXML Version*
Select the QBXML protocol version (16.0 or 17.0) to ensure compatibility with the installed QuickBooks Desktop environment.
OE QBWC Service Username*
Enter the username used to authenticate REST API access to the QBWC Service (csp-qbwc-app).
OE QBWC Service Password*
Enter the password associated with the QBWC Service username to securely authenticate REST API requests.
Default Governance Roles
Default Governance Roles*
Select the appropriate users or teams for each governance role from the drop-down list. All users and teams configured in OvalEdge Security are displayed for selection.
Admin Roles
Admin Roles*
Select one or more users from the dropdown list for Integration Admin and Security & Governance Admin. All users configured in OvalEdge Security are available for selection.
After entering all connection details, the following actions can be performed:
Click Validate to confirm the complete end-to-end connectivity, including QBWC Service communication, Web Connector polling, and successful access to the QuickBooks Desktop company file.
Click Save to store the connection for future use.
Click Save & Configure to apply additional settings before saving.
The saved connection will appear on the Connectors home page.
Manage Connector Operations
Crawl
To perform crawl operations, users must be assigned the Integration Admin role.
The Crawl/Profile button allows users to select one or more schemas for crawling.
Navigate to the Connectors page and click Crawl/Profile.
Select the schemas to crawl.
The Crawl option is selected by default.
Click Run to collect metadata from the connected source and load it into the OvalEdge Data Catalog.
After a successful crawl, the information appears in the Data Catalog > Databases/Reports/Tables tab.
The Schedule checkbox allows automated crawling at defined intervals, from a minute to a year.
Click the Schedule checkbox to enable the Select Period drop-down.
Select a time period for the operation from the drop-down menu.
Click Schedule to initiate metadata collection from the connected source.
The system will automatically execute the Crawl operation at the scheduled time.
Other Operations
The Connectors page in OvalEdge provides a centralized view of all configured connectors, including their health status.
Managing connectors includes:
Connectors Health: Displays the current status of each connector using a green icon for active connections and a red icon for inactive connections, helping to monitor the connectivity with data sources.
Viewing: Click the Eye icon next to the connector name to view connector details, including databases, tables, columns, and codes.
Nine Dots Menu Options:
To view, edit, validate, configure, or delete connectors, click on the Nine Dots menu.
Edit Connector: Update and revalidate the data source.
Validate Connector: Check the integrity of the connection.
Settings: Modify connector settings.
Crawler: Configure data extraction.
Business Glossary Settings: Manage term associations at the connector level.
Others: Configure notification recipients for metadata changes.
Delete Connector: Remove a connector with confirmation.
Connectivity Troubleshooting
If incorrect parameters are entered, error messages may appear. Ensure all inputs are accurate to resolve these issues. If issues persist, contact the assigned support team.
1
QBWC did not return a response
Error Description:
The QuickBooks Web Connector (QBWC) is not polling the QBWC Service or is not authenticated.
Resolution:
Ensure the Web Connector is running, properly authenticated, and actively polling the QBWC Service.
Verify that the company file is accessible.
2
Validation failed while establishing connection
Error Description:
The QBWC Service URL, credentials, or company file path may be incorrect.
Resolution:
Verify the QBWC Service REST URL, service username/password, and the full .QBW file path.
Ensure the QBWC Service is running and accessible.
3
The company file cannot be opened
Error Description: QuickBooks Desktop cannot access the specified company file due to an incorrect path, missing permissions, or unsupported file mode.
Resolution:
Confirm the company file path is correct, accessible to QuickBooks Desktop, and configured in the appropriate Single-user or Multi-user mode.
4
Long-running or timed-out queries
Error Description: Large datasets or complex reports may exceed default timeout limits.
Resolution:
Increase timeout settings in the QBWC Service or narrow query scope by applying filters.
5
QBXML request execution failed
Error Description: An unsupported QBXML version or malformed query may be used.
Resolution:
Ensure QBXML Version 16.0 or 17.0 is selected and confirm the query structure complies with QuickBooks Desktop QBXML standards.
6
Authentication failed for QBWC Service
Error Description: Incorrect QBWC Service username or password provided.
Resolution: Validate the service credentials and confirm REST authentication is enabled on the QBWC Service.
7
No entities or reports returned during crawl
Error Description: Connection registration may be incomplete or metadata retrieval may have failed.
Resolution:
Re-register the connection, ensure QBWC polling is active, and confirm that QuickBooks Desktop is accessible.
8
Report fields returned empty
Error Description: The selected report may not support the default discovery filters (such as dateMacro or reportBasis).
Resolution: Verify that the report supports default filters or refine the report parameters during query execution.
Copyright © 2026, OvalEdge LLC, Peachtree Corners GA USA
Last updated
Was this helpful?