Tips and techniques

This page describes “best practices” for programming with the QuickBooks SDK. It also suggests what to do when you encounter problems before you contact QuickBooks Intuit Partner Platform (IPP) Developer Support.

This section offers some friendly advice in the form of best practices with these intentions: to help safeguard your application against possible security exposures, errors, excessive data transport (how to use filters and purposeful construction of messages); and possibly to improve application performance. These best practices are suggestions, not requirements.

They are the outcome of developer experience and are offered in the spirit of encouragement:

• Sign your code (using the digital signing process) – The QuickBooks SDK provides for application authentication through use of a digital signature within the application . A signed application offers your user greater confidence in the authenticity of your application. Your signed application is more secure from the users’ perspective in relation to their QuickBooks company file data.
• Store company file data in a secure manner – For applications that store company file data, be certain to store the data in a secure manner using an internal database or file. If practical, encrypt data. Do not store QuickBooks company file data in the regular file system, exposing it to security breaches. Also, if you save qbXML text streams or discrete object requests between calls, store them in a secure manner. | For instance, some applications integrate storage of qbXML within their databases removing the text stream only after they complete processing the response code and exit their message recovery routines.
• Be purposeful in your construction of messages:
  • Use well-defined filters in query requests. Consider this maxim: the briefer the request, the more verbose the response. | If an application is sending a query request and you don’t want all of the data of a certain type returned to you, use filters to limit the number of response objects returned and the data transported. The more verbose the request (the more filters), the briefer (more pertinent) the response. | For multiple, unbounded queries, issue separate requests to limit the amount of data transmitted in one request. | Alternatively, use the MaxReturned filter in the query to limit the number of objects returned by a single call. See Chapter 8, “Creating Queries.”
  • Do not include empty elements in requests without express intention and only in modify requests or certain add requests to clear the element value (see Modify, delete, and void requests and responses for which values can be cleared in an add request).
  • If you are using qbXML, pay attention to encoding issues. Be aware of your use of special characters, including ampersand (&), single quotes (‘), double quotes (“), greater-than (>), and less-than (<) characters.
• Always run the qbXML Validator on your qbXML requests as you develop the code. Better yet, incorporate your own qbXML request validation routines in your code. For QBFC, use the Verify method to check the validity of your messages.
• Call GetCurrentCompanyFileName after BeginSession with qbCompanyFileName set to NULL. | If you pass in NULL for the company file name qbCompanyFileName in BeginSession because the file is already open, call GetCurrentCompanyFileName immediately after calling BeginSession to determine the identity of the file. Under these circumstances, before you modify any data in that company file, verify the company file name with the user through your application interface to ensure that your application acts on the intended company data file.
• Provide a mechanism for your user to run your application without having to provide a company file name to the BeginSession call. | This technique is useful in troubleshooting certain application problems and allows the user to continue using the software while a software problem is being investigated and resolved.
• Always parse the received response and analyze the status code and status severity for every response object.
• If you are using qbXML, provide your application with the ability to write application- generated qbXML routinely to a file for debugging purposes. Also, enable it with a debug switch that could be used during production time by your technical support organization to write application-generated qbXML to a file.
• Implement application features that provide your technical support organization with means of helping your users resolve problems. For instance, add a routine to compress and e-mail the log file to you.
• In your user interface, provide your users with a Browse button so that they may browse to select the company file. This approach is less prone to error than is entering the company file name and path by typing it in a window field.
• It is always good practice to test your application on a system equivalent to the machine and system you assess to be most like the target system of your customer. To ensure that your application is robust, run the application against a complex and large company data file. Use a target system that has an average amount of memory. Check your use of queries and filters against the company data file on that system. If the system thrashes or QuickBooks returns an out-of-memory error, enhance your application’s use of queries with additional, appropriate filters.
• Your code should always test for the status code , not the status message, since status messages are more likely to change from one release to the next.

The QuickBooks SDK includes an external Validator tool ( qbXMLValidator.exe ) that allows you to validate qbXML documents to ensure that their grammar and syntax adheres to the requirements of the qbXML specification. Similarly, the QBFC Library contains a Verify method for IMsgSetRequest, which allows you to verify requests before DoRequests is called.) The Validator tool is useful during the development cycle, since it helps you isolate invalid requests before you send them to be processed. The request format is also validated automatically when the call to ProcessRequest (or, in the case of QBFC, DoRequests) is made.

If you want more control over validating requests before they are sent to QuickBooks, you can build your own validator into your application. Be sure to validate your document before you report any problems to Intuit Developer Support.

In most cases, you will have undergone various processes in attempting to solve your development problem before you consider contacting IPP Developer Support. However, here are some troubleshooting strategies to include in your investigation that you might not have considered.

Try these approaches before you contact IPP developer support:

• If you are using qbXML, write out to a file the portion of qbXML that is causing the problem and check it thoroughly.
• Check the qbsdklog.txt file for additional detailed information pertaining to the error condition. This file is written to the directory where the QuickBooks executable file is installed.
• Ensure that you can recreate the problem using the SDKTest program. (The developer support engineer will want to know that this can be done and perhaps will also want to recreate the problem to investigate it further.)

Here are the guidelines to follow in building a test case:

• Create the smallest possible test case that will embody the problem. Let the test case simply point out the problem.
• Make the test case complete. If it requires the creation of any particular customers, vendors, accounts, invoices, and so on, create a setup file in addition to the one that shows the problem.
• Run the test case against one of the standard QuickBooks sample company files, and make the test case run successfully, if possible.

If you must contact IPP Developer Support, the developer support engineer will ask you to build a test case according to the guidelines. See “Building a Test Case to Make Available to Developer Support” for details. To proceed speedily in solving the problem, have the test case ready when you contact developer support. Send the test case as qbXML files to QuickBooks via the SDKTest program. Also send the portion of the log file ( qbsdklog.txt ) that pertains to the problem. (You do not have to send the entire qbsdklog.txt file.)