QuickBooks Desktop integration setup
Introduction
To connect your QuickBooks Desktop (QBD) instance with XTRF, you have to set up some settings on both sides.
Configure XTRF
Sign in to the XTRF Home Portal.
Go to Configuration Menu → User Management → Users.
Click the Add button on top of the list of users. You need to create a new user for the purposes of the integration. Make sure that this user is given the rights to create and modify Clients, Vendors, and their Invoices. Also, ensure the user has an allocated license and can always log in to XTRF. To find out how to give users specific rights, see the https://help.xtm.cloud/xtrf/home-portal/configuration-menu/en/user-groups-and-rights.html article.
Go to Integration → Quick Books.
In the Main Settings tab, click the Edit button.
Check the QuickBooks Integration Enabled box. The settings menu expands.
In the General Settings section:
In the QuickBooks will Sign into XTRF as field, select the user you have created for the integration.
Choose the Main Currency in your QuickBooks Installation.
In the Synchronize Items Newer than field, set up the desired date of the first synchronization. This field will be updated automatically each time the synchronization occurs.
In the Add QB Invoice Items based on field, set up whether XTRF should send to QuickBooks Invoice Items or Payables/Receivables data.
(Optional) Once the synchronization is performed, you will be able to browse the Logs. Also, you will be able to see the items that have been synchronized in the Integration Log tab.
In the Clients section, select whether the integration should synchronize XTRF Clients and Projects to QuickBooks by checking or unchecking Synchronize Clients and Synchronize Projects as QB Jobs boxes. If you choose to synchronize clients and projects, additional settings appear:
In the QB Job Name Expression field, set up the way the Client Jobs are created in QuickBooks. By default, it is ${project.idNumber}.
In the For Client Invoices Use QB Item Name Expression field, set up how the Client invoice items are created in QuickBooks. By default, it is ${item.name}.
This option is not available if you select XTRF Payables/Receivables in the Add QB Invoice Items Based on field in step 7.d. of this guide.In the For Client Invoices Use Description Expression field, set up how the Client invoice descriptions are created in QuickBooks. By default, it is ${entity.finalNumber}.
In the For Client Invoices Use QB Item Description Expression field, set up how the Client invoice item descriptions are created in QuickBooks. By default, it is ${item.displayName}.
In the For Client Invoices Use QB Default Item Name field, enter a proper expression. By default, it is customerItem.
In the Synchronize when Client Invoice Status is field, choose the first status of a Client Invoice in XTRF that will trigger the invoice transfer and synchronization to QuickBooks. By default, it is Ready.
In the Vendors section, select whether the integration should synchronize XTRF Vendors by checking or unchecking the Synchronise Vendors box. If you choose to synchronize vendors, additional settings appear:
In the For Vendor Invoices Use QB Item Name Expression field, set up the way the Vendor invoice items are created in QuickBooks. By default, it is ${item.activityType.name}.
This option is not available if you select XTRF Payables/Receivables in the Add QB Invoice Items Based on field.In the For Vendor Invoices Use QB Item Description Expression field, set up the way the Vendor invoice items are created in QuickBooks. By default, it is ${item.displayName}.
In the For Vendor Invoices Use QB Default Item Name field, enter a proper expression. By default, it is providerItem.
In the Synchronize when Vendor Invoice Status is field, choose the first status of a Vendor Invoice in XTRF that will trigger the invoice transfer and synchronization to QuickBooks. By default, it is Confirmed.
Once you are done, click the Save button at the bottom of the page.
Go to the QWC File Generation tab. Here you can generate a .qwc file that you will need to use later in the QuickBooks Web Connector.
Click the Generate button to generate the .qwc file. Save the file on your local drive.
In QuickBooks integrator, colon (:) has a special meaning: it is used as a separator for hierarchic structures in QB.
IMPORTANT!
Do not use QB Category names as item descriptors, as this will disrupt the synchronization.
XTRF Projects and QuickBooks Client Jobs are synchronized only one way, from XTRF to QuickBooks. If an XTRF Client Invoice contains tasks from only one project, it gets linked to the Client Job. QuickBooks bills are linked to Client Jobs too.
Configure QuickBooks
QuickBooks Web Connector
To integrate your QuickBooks Desktop with XTRF, you first need to install the QuickBooks Web Connector provided by the developer of QuickBooks. It is a software application that runs on Microsoft Windows and enables specially designed web-based applications to exchange data with QuickBooks products. For more information, see the Get started with QuickBooks web connector article.
Run the QuickBooks Web Connector software and open the .qwc file generated by XTRF.
If asked, authorize XTRF to access QuickBooks.
In the Password field, enter the password of the XTRF user created for the integration (see Configure XTRF step 3).
Click Yes if asked if you would like the password to be saved.
Check the box on the left of the XTRF application and click the Update Selected button to run the initial synchronization.
Your QuickBooks application and XTRF are now integrated.
See also: SSL Certificate Installation.
Field Mapping between QuickBooks Desktop and XTRF
Client
Client in XTRF is mapped into Customer in QuickBooks. Their names must be unique across the whole system, not only among clients but also among vendors.
QuickBooks field name | XTRF field name | Field length limit | Comment |
Name | customer.name | 41 |
|
IsActive |
|
| true if the client is not in state "Inactive" in XTRF |
CompanyName | customer.fullname | 41 |
|
BillAddress | customer.address.* |
| see Address mapping below |
ShipAddress | customer.address.* |
| see Address mapping below |
Phone | customer.phone | 21 |
|
customer.email | 1023 |
| |
CurrencyRef |
|
| currency from price profile mapped into QuickBooks currency |
Vendor
Vendor in XTRF is mapped into Vendor in QuickBooks.
QuickBooks field name | XTRF field name | Field length limit | Comment |
Name | provider.name | 41 |
|
IsActive |