QuickBooks Integrator 2020 .NET Edition

Questions / Feedback?

QBWCServer Component

Properties   Methods   Events   Configuration Settings   Errors  

The QBWCServer component is used to communicate with QuickBooks Web Connector from your application.




The QBWCServer component is designed to process requests from QuickBooks Web Connector and fire events that allow you to provide information to, and get information from QuickBooks Web Connector.

This allows you to create an application that can communicate with a remote copy of QuickBooks without worrying about directly accessing the machine where QuickBooks is running. For more information on the design of this approach refer to the Intuit website for QuickBooks Web Connector.

QWC Files

The first step in establishing a relationship between your application and a remote instance of QuickBooks is to create a QWC file. This file specifies information about your application its requirements, as well as the access you need. The CreateQWCFile method creates the QWC file which must be generated for each user of your application. The minimum required properties are:

Once the file is generated the end user will obtain the file from your website, and you will assign a password for that user at that time. The password is not part of the QWC file but the user will provide this directly in QuickBooks Web Connector and it will be sent to your web application during the connection for verification purposes.

Request Processing

The component is designed with a server environment in mind. That is, it's typical that the component will be used in a web page, but is not required. However the HTTP request is received, it can be passed to the RequestData property. After passing the request data to the component call ProcessRequest method processes the request from QuickBooks Web Connector. Processing the requests will fire one of the events.

The component provides various events to interact with QuickBooks Web Connector. QuickBooks Web Connector will make a sequence of calls for any given session, and the events correspond to these calls. Within the events you control the response which dictates what QuickBooks Web Connector will do next.

A session ticket is provided so you can keep track of a particular session over the course of multiple calls. An example of a typical session:

  1. ServerVersion fires. This allows you to provide an the version of your application. This is purely informational and does not need to be implemented.
  2. ClientVersion fires. This provides version information about the QuickBooks Web Connector. It may be used to reject a connection based on minimum required versions, but in most cases no action would be taken in your code and the session proceeds.
  3. Authenticate fires. This event allows verification of the user that is connecting. Here you will either accept or reject the connection.
  4. SendRequest fires. Within this event you will supply a QBXML request that will be passed to QuickBooks.
  5. ReceiveResponse fires. QuickBooks Web Connector returns the QBXML response from the request you gave it in the previous step, or error information about why the request failed.
  6. CloseConnection fires. This is the last event in the session. You may provide a message that will be displayed in QuickBooks Web Connector, but in most cases you would not take any action in this event.

Preparing Requests and Parsing Responses

The SendRequest event requires that you provide a QBXML request. This can be generated using the other components in this toolkit. To do so, simply set the QBRequestMode property to rmOffline before making a method call. For instance:

Customer customer = new Customer();
customer.QBRequestMode = CustomerQBRequestModes.rmOffline;
customer.GetByName("John Doe");
e.Request = customer.QBRequestAggregate;
In the above code the component is used in the same way you would use the component if you were communicating directly with QuickBooks with the exception that QBRequestMode is set to rmOffline. When the GetByName method is called instead of attempting to communicate with QuickBooks only the QBRequestAggregate property is populated. This QBXML aggregate should be passed to the e.Request parameter inside the SendRequest event.

Processing responses is similar. You will receive the QBXML response from the e.Response parameter inside the ReceiveResponse event. You may then pass the response to the QBResponseAggregate property, or InputQBXML method of other components in the toolkit. For instance:

Customer customer = new Customer();
customer.QBResponseAggregate = e.Response;
string myAccountNumber = customer.AccountNumber;
Setting QBResponseAggregate and calling InputQBXML do the exact same thing. The component parses the response and populates the properties of the component.

Error Handling

There are two basic types of errors when dealing with QuickBooks Web Connector. The first are errors that originate from your application and are reported to QuickBooks Web Connector. These are driven by the actions you take inside events. For instance in the SendRequest event you may set e.Request to empty string to signify an error. QuickBooks Web Connector will see this and make another call and GetLastError will fire. GetLastError is fired when QuickBooks Web Connector is asking from error information from your application. Here you may provide details about the error.

The second type of error is a communication error between QuickBooks Web Connector and QuickBooks itself. When this happens QuickBooks Web Connector will make a call and ConnectionError will fire with information about the error received from QuickBooks.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

OverwriteWhether to overwrite QWC files.
QWCFileInfoSpecifies the specific requirements for the QWC file.
RequestDataThe request data to process.
ResponseDataThe response data.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

ConfigSets or retrieves a configuration setting.
CreateQWCFileCreates a QWC file.
ProcessRequestProcesses the request.
ReadRequestReads the request from the HTTP context.
SendResponseSends the response.
SetRequestStreamSet's the request stream.
SetResponseStreamSet's the response stream.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

AuthenticateFired when the QuickBooks Web Connector authenticates.
ClientVersionProvides the QuickBooks Web Connector version information.
CloseConnectionFires when the update session completes.
ConnectionErrorFires when QuickBooks Web Connector is unable to connect to QuickBooks.
ErrorInformation about errors during data delivery.
GetInteractiveURLFires when the URL for an interactive session is needed.
GetLastErrorFires when QuickBooks Web Connector checks for error information.
InteractiveDoneThis event fires when QuickBooks Web Connector checks to see if the interactive session is finished.
InteractiveRejectedThis event fires after a user rejects an interactive session.
ReceiveResponseFires when a response is received.
SendRequestFires when QuickBooks Web Connector asks for a request.
ServerVersionFires when QuickBooks Web Connector requests the version of your application.

Configuration Settings

The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

QBTypeThe type of QuickBooks software the connection will be made to.
StyleSpecifies the SOAP encoding style used in requests made by QuickBooks Web Connector.
BuildInfoInformation about the product's build.
GUIAvailableTells the component whether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2022 4D Payments Inc. - All rights reserved.
QuickBooks Integrator 2020 .NET Edition - Version 20.0 [Build 8076]