QuickBooks Desktop integration setup

Owned by Oksana Vishchuk
Last updated: Jul 04, 2024
7 min read

Introduction

To connect your QuickBooks Desktop (QBD) instance with XTRF, you have to set up some settings on both sides.

Configure XTRF 

  1. Sign in to the XTRF Home Portal.

  2. Go to Configuration Menu → User Management → Users.

  3. 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.

  4. Go to Integration → Quick Books.

  5. In the Main Settings tab, click the Edit button.

  6. Check the QuickBooks Integration Enabled box. The settings menu expands.

  7. In the General Settings section:

     

    1. In the QuickBooks will Sign into XTRF as field, select the user you have created for the integration.

    2. Choose the Main Currency in your QuickBooks Installation.

    3. 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.

    4. In the Add QB Invoice Items based on field, set up whether XTRF should send to QuickBooks Invoice Items or Payables/Receivables data.

    5. (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.

  8. 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:

     

    1. In the QB Job Name Expression field, set up the way the Client Jobs are created in QuickBooks. By default, it is ${project.idNumber}.

    2. 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.

    3. 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}.

    4. 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}.

    5. In the For Client Invoices Use QB Default Item Name field, enter a proper expression. By default, it is customerItem.

    6. 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.

  9. 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:

     

    1. 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.

    2. 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}.

    3. In the For Vendor Invoices Use QB Default Item Name field, enter a proper expression. By default, it is providerItem.

    4. 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.

  10. Once you are done, click the Save button at the bottom of the page.

  11. 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.

     

  12. 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.

  1. Run the QuickBooks Web Connector software and open the .qwc file generated by XTRF.

  2. If asked, authorize XTRF to access QuickBooks.

  3. 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.

  4. 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

 

Email

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

 

Email

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.