QBWCServer Control

Properties Methods Events Configuration Settings Errors

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

Syntax

QBWCServer

Remarks

The QBWCServer control 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 control is designed with a server environment in mind. That is, it's typical that the control 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 control call ProcessRequest method processes the request from QuickBooks Web Connector. Processing the requests will fire one of the events.

The control 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:

ServerVersion fires. This allows you to provide an the version of your application. This is purely informational and does not need to be implemented.
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.
Authenticate fires. This event allows verification of the user that is connecting. Here you will either accept or reject the connection.
SendRequest fires. Within this event you will supply a QBXML request that will be passed to QuickBooks.
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.
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 control is used in the same way you would use the control 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 control parses the response and populates the properties of the control.

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 control with short descriptions. Click on the links for further details.


Overwrite	Whether to overwrite QWC files.
QWCFileInfoAppDescription	A brief description of the application.
QWCFileInfoAppDisplayName	The display name of the application.
QWCFileInfoAppId	The application Id.
QWCFileInfoAppName	The name of the application.
QWCFileInfoAppSupportURL	A URL where users can find support for your product.
QWCFileInfoAppUniqueName	If this property is set the QuickBooks Web Connector will not use its clone/replace model for the AppName and will instead use the replace routine.
QWCFileInfoAppURL	The URL of your web application.
QWCFileInfoAuthFlags	This property specifies which versions of QuickBooks your application supports.
QWCFileInfoCertURL	This property specifies a URL which is used by the QuickBooks Web Connector to obtain and validate the SSL certificate.
QWCFileInfoFileId	This property specifies a unique Id.
QWCFileInfoIsReadOnly	Specifies whether read or read/write access is needed.
QWCFileInfoNotify	Determines if notification are allowed.
QWCFileInfoOwnerId	This property specifies an Id which identifies your application.
QWCFileInfoPersonalDataPref	This property defines the type of access to personal/sensitive data required by your application.
QWCFileInfoUnattendedModePref	This property specifies whether you need to access QuickBooks in unattended mode (when QuickBooks is closed).
QWCFileInfoUpdateInterval	This property specifies the desired update interval in seconds.
QWCFileInfoUser	This property species the user.
RequestData	The request data to process.
ResponseData	The response data.

Method List

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


Config	Sets or retrieves a configuration setting .
CreateQWCFile	Creates a QWC file.
ProcessRequest	Processes the request.

Event List

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


Authenticate	Fired when the QuickBooks Web Connector authenticates.
ClientVersion	Provides the QuickBooks Web Connector version information.
CloseConnection	Fires when the update session completes.
ConnectionError	Fires when QuickBooks Web Connector is unable to connect to QuickBooks.
Error	Information about errors during data delivery.
GetInteractiveURL	Fires when the URL for an interactive session is needed.
GetLastError	Fires when QuickBooks Web Connector checks for error information.
InteractiveDone	This event fires when QuickBooks Web Connector checks to see if the interactive session is finished.
InteractiveRejected	This event fires after a user rejects an interactive session.
ReceiveResponse	Fires when a response is received.
SendRequest	Fires when QuickBooks Web Connector asks for a request.
ServerVersion	Fires when QuickBooks Web Connector requests the version of your application.

Configuration Settings

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


QBType	The type of QuickBooks software the connection will be made to.
Style	Specifies the SOAP encoding style used in requests made by QuickBooks Web Connector.
CodePage	The system code page used for Unicode to Multibyte translations.