QBWCServer Class

Properties Methods Events Configuration Settings Errors

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

Syntax

class inqb.QBWCServer

Remarks

The QBWCServer class 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 create_qwc_file 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 class is designed with a server environment in mind. That is, it's typical that the class will be used in a web page, but is not required. However the HTTP request is received, it can be passed to the request_data property. After passing the request data to the class call process_request method processes the request from QuickBooks Web Connector. Processing the requests will fire one of the events.

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

on_server_version fires. This allows you to provide an the version of your application. This is purely informational and does not need to be implemented.
on_client_version 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.
on_authenticate fires. This event allows verification of the user that is connecting. Here you will either accept or reject the connection.
on_send_request fires. Within this event you will supply a QBXML request that will be passed to QuickBooks.
on_receive_response 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.
on_close_connection 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 on_send_request 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 class is used in the same way you would use the class 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 on_send_request event.

Processing responses is similar. You will receive the QBXML response from the e.Response parameter inside the on_receive_response 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 class parses the response and populates the properties of the class.

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 on_send_request event you may set e.Request to empty string to signify an error. QuickBooks Web Connector will see this and make another call and on_get_last_error will fire. on_get_last_error 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 on_connection_error will fire with information about the error received from QuickBooks.

Property List

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


overwrite	Whether to overwrite QWC files.
qwc_file_info_app_description	A brief description of the application.
qwc_file_info_app_display_name	The display name of the application.
qwc_file_info_app_id	The application Id.
qwc_file_info_app_name	The name of the application.
qwc_file_info_app_support_url	A URL where users can find support for your product.
qwc_file_info_app_unique_name	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.
qwc_file_info_app_url	The URL of your web application.
qwc_file_info_auth_flags	This property specifies which versions of QuickBooks your application supports.
qwc_file_info_cert_url	This property specifies a URL which is used by the QuickBooks Web Connector to obtain and validate the SSL certificate.
qwc_file_info_file_id	This property specifies a unique Id.
qwc_file_info_is_read_only	Specifies whether read or read/write access is needed.
qwc_file_info_notify	Determines if notification are allowed.
qwc_file_info_owner_id	This property specifies an Id which identifies your application.
qwc_file_info_personal_data_pref	This property defines the type of access to personal/sensitive data required by your application.
qwc_file_info_unattended_mode_pref	This property specifies whether you need to access QuickBooks in unattended mode (when QuickBooks is closed).
qwc_file_info_update_interval	This property specifies the desired update interval in seconds.
qwc_file_info_user	This property species the user.
request_data	The request data to process.
response_data	The response data.

Method List

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


config	Sets or retrieves a configuration setting.
create_qwc_file	Creates a QWC file.
process_request	Processes the request.

Event List

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


on_authenticate	Fired when the QuickBooks Web Connector authenticates.
on_client_version	Provides the QuickBooks Web Connector version information.
on_close_connection	Fires when the update session completes.
on_connection_error	Fires when QuickBooks Web Connector is unable to connect to QuickBooks.
on_error	Information about errors during data delivery.
on_get_interactive_url	Fires when the URL for an interactive session is needed.
on_get_last_error	Fires when QuickBooks Web Connector checks for error information.
on_interactive_done	This event fires when QuickBooks Web Connector checks to see if the interactive session is finished.
on_interactive_rejected	This event fires after a user rejects an interactive session.
on_receive_response	Fires when a response is received.
on_send_request	Fires when QuickBooks Web Connector asks for a request.
on_server_version	Fires when QuickBooks Web Connector requests the version of your application.

Configuration Settings

The following is a list of configuration settings for the class 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.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.