As mentioned before, the QuickBooks Web Connector expects your web service to be able to accept remote procedure calls (RPC) for six different methods. What you do when your server receives the RPC is largely up to you, but the data you send back to the Web Connector in response to the RPC is largely up to the designers of the system. Each method is expected to respond in a certain way, as outlined below using our standard way to handle sessions with the Web Connector:
Where used below, WC stands for the Web Connector and SWS stands for the SOAP web service.
Preliminary steps... the Web Connector uses .qwc files to add web services to its list of available applications:
- The user downloads and installs the .qwc file the points to our web service (PSU).
- Web Connector (WC) establishes the server as a valid web service and makes updates possible.
- The user enters the password (username supplied in the .qwc file) and hits update.
Once the user hits update, the Web Connector begins the following application loop:
- WC calls SWS's authenticate() method to initiate the process.
- SWS returns an array with the session's ticket (unique ID) and with the result of authentication.
- A successful authentication returns the company file to use (or a blank string for the currently open file).
- An unsuccessful authentication returns nvu. Upon receiving this message, WC calls SWS's closeConnection method and ends the session.
- WC opens the QuickBooks file, gathers some settings data, and sends that to the SWS through sendRequestXML(). It then waits for a response.
- (SWS here should parse and store the data received in HCPResponse. If this is the first call, SWS should also store in the database this update session's information for the duration of the update process.)
- Based on what's in SWS's action queue, it sends a qbXML request for QuickBooks as the return value of sendRequestXML(). An empty return string indicates an error.
- WC passes this request onto QuickBooks and awaits its response. The response is sent to SWS's receiveResponseXML() method as a qbXML message in $response. If an error occurred, it will be indicated in $hresult and $message.
- PSU processes the response and returns an integer indicating the percentage of completion for the current update process.
- A negative value indicates an error occurred. This will cause WC to call the getLastError() method and display the appropriate message to the user.
- A positive value less than 100 indicates there is more work to do. WC will update its status bar and call sendRequestXML() again, ommitting HCPResponse.
- The loop between sendRequestXML() and receiveResponseXML() continues until an error occurs or the return value is 100, indicating completion.
- When the update is complete, WC calls closeConnection() to indicate it is done with the session. This returns a final status message.
- PSU should clean up the database and remove the appropriate entries from the tables.
The core server application you write must be developed around this process. You're left up to your own devices to decide how to implement session handling, message construction, settings, logging, and more. We've included as an attachment to this post a skeleton server file that we used in an application using the NuSOAP library. Questions about the server may be posted in the forums. (The file has been commented some. The general structure is includes, server initialization, server methods, and at the very bottom the butter that makes it work. Read more about NuSOAP in the section below this.) Also attached is a class taken from the comments at PHP.net that is extremely useful for parsing the XML strings passed to the web service by the Web Connector.
To learn more about our method of storing import actions and delivering the data to QuickBooks, read the Implementing an Action Queue section.