QuickBooks Desktop integration setup

This is an old version of the article. Please check the actual version in our new Knowledge Base.

QuickBooks Desktop integration setup

  • Configure XTRF 
  • Configure QuickBooks Desktop 
  • Field Mapping between QuickBooks Desktop and XTRF

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 Image 2428Configuration 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 Add a new user account 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:

    Image 2414

    a. In the QuickBooks will Sign into XTRF as field, select the user you have created for the integration.
    b.Choose the Main Currency in your QuickBooks Installation.
    c.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.
    d. In the Add QB Invoice Items based on field, set up whether XTRF should send to QuickBooks Invoice Items or Payables/Receivables data.
    e.(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:

    Image 2415

    a. In the QB Job Name Expression field, set up the way the Client Jobs are created in QuickBooks. By default, it is ${project.idNumber}.
    b. 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.
    c. 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}.
    d. 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}.
    e. In the For Client Invoices Use QB Default Item Name field, enter a proper expression. By default, it is customerItem.
    f.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:

    Image 2416

    a. 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.
    b. 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}.
    c. In the For Vendor Invoices Use QB Default Item Name field, enter a proper expression. By default, it is providerItem.
    d. 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.

    Image 2417
  12. Click theGenerate button to generate the .qwc file. Save the file on your local drive.

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

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

The following steps should be performed by QuickBooks Administrator.

  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.

    Image 2418

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.

Integrations QuickBooks

Is this article helpful for you?