QuickBooks Desktop integration setup
- 1 Configure XTRF
- 2 Configure QuickBooks
- 3 Field Mapping between QuickBooks Desktop and XTRF
- 3.1 Client
- 3.2 Vendor
- 3.3 Client Invoice
- 3.4 Client Invoice Items
- 3.5 Receivables
- 3.6 Vendor Invoice
- 3.7 Vendor Invoice Items
- 3.8 Payables
- 3.9 Address
- 3.10 Terms
- 3.11 Projects
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 User Management - User Groups and Rights 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}.
Note: 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}.
Note: 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.
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 |
|
| true if the vendor is not in state "Inactive" in XTRF |
CompanyName | provider.fullname | 41 |
|
VendorAddress | provider.address.* |
| see Address mapping below |
Phone | provider.phone | 21 |
|
provider.email | 1023 |
| |
CurrencyRef |
|
| currency from price profile mapped into QuickBooks currency |
Client Invoice
Client Invoice in XTRF is mapped into Invoice in QuickBooks.
QuickBooks field name | XTRF field name | Field length limit | Comment |
CustomerRef | customerInvoice.customer |
|
|
TxnDate | customerInvoice.finalDate |
|
|
RefNumber | customerInvoice.finalNumber | 11 |
|
BillAddress | customerInvoice.customerAddress.* |
| see Address mapping below |
ShipAddress | customerInvoice.customerAddress.* |
| see Address mapping below |
TermsRef | terms |
| see Payment mapping below |
DueDate | customerInvoice.requiredPaymentDate |
|
|
Memo | For client invoices use Description Expression | 4095 |
|
Invoice Lines | customerInvoice.invoiceItems customerInvoice.tasks.receivables |
| see Invoice item mapping below |
Client Invoice Items
To choose this method of synchronization, select the XTRF Invoice Items in the Add Invoice Items Based on field (see Configure XTRF step 7.d.).
QuickBooks field name | XTRF field name | Field length limit | Comment |
Full Name | For client invoices use QB Item Name Expression | 31 | Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., "item:subitem:subsubitem" in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem"). Each of the items/subitems can be up to 31 characters long. |
Desc | For client invoices use QB Item Description Expression | 4095 |
|
Quantity | customerInvoiceItem.quantity |
|
|
Rate | customerInvoiceItem.rate |
| converted into QB currency |
Receivables
To choose this method of synchronization, select the XTRF Payables/Receivables in the Add Invoice Items Based on field (see Configure XTRF step 7.d.).
QuickBooks field name | XTRF field name | Field length limit | Comment |
Full Name | For client invoices use QB Item Name Expression | 31 | Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., "item:subitem:subsubitem" in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem"). Each of the items/subitems can be up to 31 characters long. |
Desc | For client invoices use QB Item Description Expression | 4095 |
|
Quantity | receivable.quantity |
|
|
Rate | receivable.rate |
| converted into QB currency |
Vendor Invoice
Vendor Invoice in XTRF is mapped into Bill in QuickBooks.
QuickBooks field name | XTRF field name | Field length limit | Comment |
VendorRef | providerInvoice.provider |
|
|
TxnDate | providerInvoice.finalDate |
|
|
DueDate | providerInvoice.requiredPaymentDate |
|
|
RefNumber | providerInvoice.finalNumber | 20 |
|
TermsRef | terms |
| see Payment terms mapping below |
Memo | providerInvoice.invoiceNote | 4095 |
|
ItemLineAdd | providerInvoice.activities providerInvoice.activities.payables |
| see Invoice items mapping below |
Vendor Invoice Items
To choose this method of synchronization, select the XTRF Invoice Items in the Add Invoice Items Based on field (see Configure XTRF step 7.d.).
QuickBooks field name | XTRF field name | Field length limit | Comment |
Full Name | For vendor invoices use QB Item Name Expression | 31 | Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., "item:subitem:subsubitem" in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem"). Each of the items/subitems can be up to 31 characters long. |
Desc | For vendor invoices use QB Item Description Expression | 4095 |
|
Quantity | always set to 1 |
|
|
Rate | activity.totalAgreed |
| converted into QB currency |
Payables
To choose this method of synchronization, select the XTRF Payables/Receivables in the Add Invoice Items Based on field (see Configure XTRF step 7.d.).
QuickBooks field name | XTRF field name | Field length limit | Comment |
|
Full Name | For vendor invoices use QB Item Name Expression | 31 | Items and subitems are supported. If an XTRF item contains one or more colon(s), in QuickBooks, a hierarchy of items will be created (e.g., "item:subitem:subsubitem" in XTRF will result in creating three items of different levels, named, respectively: "item," "subitem," and "subsubitem"). Each of the items/subitems can be up to 31 characters long. |
|
Desc | For vendor invoices use QB Item Description Expression | 4095 |
|
|
Quantity | payable.quantity |
|
|
|
Rate | payable.rate |
| converted into QB currency |
|
Address
QuickBooks field name | XTRF field name | Field length limit | Comment |
Addr1 | *.address.address | 41 |
|
Addr2 | *.address.address2 | 41 |
|
City | *.address.city | 31 |
|
State | *.address.province | 21 |
|
PostalCode | *.address.zipCode | 13 |
|
Country | *.address.country.name | 31 |
|
Terms
QuickBooks field name | XTRF field name | Field length limit | Comment |
Name | terms.displayName | 31 |
|
StdDueDays | terms.dueDays |
|
|
Projects
Projects in XTRF are mapped into Customer Jobs in QuickBooks.
To enable this feature, check the Synchronize Projects as QB Jobs box (see Configure XTRF step 8).
Only the project information is synchronized. Information about language combinations, tasks, workflows, jobs, etc., is not sent to QuickBooks.
Project / Customer Job Data
QuickBooks field name | XTRF field name | Field length limit | Comment |
JobTitle | ID | 41 |
|
JobStatus | Status |
|
|
JobStartDate | Start Date |
|
|
JobProjectedEndDate | Deadline |
|
|
JobEndDate | Delivery Date |
|
|
JobDesc | Name | 99 |
|
Notes | Notes | 4095 | shown as an entry in the table in the Notes tab in the Job Information window |
Project / Customer Job Status
QuickBooks status | XTRF status | Comment |
In progress | Opened |
|
Closed | Closed | reopening a project (setting the XTRF status back to Opened), sets the QuickBooks status back to In progress |
Closed | Canceled | canceling a project also deactivates it in QuickBooks, i.e., the "Job is inactive" parameter is set |
Other QuickBooks customer job statuses are not used.