This page suggests ways you can help users troubleshoot and resolve some problems without contacting technical support. In particular, it deals with ways your application can respond to error messages when it attempts to open a connection with QuickBooks and begin a session working on a company file.
In many cases, your application can present windows that help users handle these problems themselves. Additional tips to help users avoid common pitfalls, which you may want to include in your documentation, are also included here.
The SDKDiag tool is a diagnostics tool for testing and troubleshooting QuickBooks connections and looking at what files are installed on a system. Find more about SDKDiag here.
The most commonly occurring error conditions not resolvable by your application are
In these cases, your application might need to inform the user about the nature of the problem and recommend an approach to its resolution. Otherwise, the user might wait for your application to recover from a situation it cannot resolve.
This section describes some of the kinds of problems your application should monitor for and the responsive actions it should take.
If multiple versions of QuickBooks are installed, either of the following two cases might occur:
Problem: The correct version of QuickBooks is installed and open, but the company data file specified by the user is incompatible with the current version of QuickBooks. Result code 0x80040409 is returned, which indicates that the version of QuickBooks currently running cannot work with the provided data file.
Response: Your application should present the user with a window describing the problem and direct the user to open the same company file in the correct version of QuickBooks (which will cause it to be converted to the correct format).
Problem: If the user specifies the name of a company file that is different from the one already open in QuickBooks, your application will receive an error. QuickBooks returns a result code of ;0x8004040A for the BeginSession method, which indicates that the data file already open is different from the requested one.
Responses: Your application should present the user with a window describing the problem. There are two possible resolutions, depending on the intention of the user. The resolution you recommend depends on your application.
Use of QuickBooks error recovery features allows you to protect against data loss and data duplication in the event of an error condition. This features requires that:
If the user installed a new version of your application and it has the same name as the one used when the error condition occurred, error recovery is still possible.
The user might consider some problems more serious than others and think it is safer to replace a down-level version of an application with a new, improved one in the event of a serious condition such as a crash. It is important to convey to users that they must first start the installed versions of QuickBooks and your application and allow your application to restore its own data and the data it has modified in the QuickBooks company file. Then, if they want to, they can install the new software.
In addition to a window warning users of this requirement, you will probably also want to include a note in your documentation about this topic.
An integrated application may be revised in between releases of QuickBooks. The name of the application may also be changed with each new release to differentiate the feature sets of each successive revision.
If your application changes its name, be aware that it may be represented as multiple applications in the QuickBooks preferred integrated applications list. Also, should an error condition exist, users should complete error recovery in one version of the application before they upgrade to the next version.
It is possible for an application to get locked into a error recovery loop, sending the same message repeatedly to QuickBooks. This condition might occur, for instance, if an application sent a request that caused an error condition to occur and in sending the request again as part of error recovery, the request caused the error condition to occur yet again.
With each recurrence, QuickBooks would respond with the same error recovery status response. Though perhaps an uncommon event, when this kind of loop occurs, there is no way for the user to interrupt the process. Therefore, as a safeguard, it is a good idea to put a “back door” into your application—a hidden keystroke sequence, perhaps—and inform your technical support organization about it.
You might also provide support for a control key set—Ctrl+<shift>+1 (for example)—that allows your user to break out of the loop and recover control of the application. You would tell your user support organization about this control key set. Your documentation might also mention it.
The following sections suggest topics you may want to include in the documentation to help users avoid common pitfalls concerning permissions and error recovery.
The auto-login option allows your application to integrate and run QuickBooks in unattended mode. Auto-login without the QuickBooks user interface can be efficient if your application needs to avoid the costly overhead entailed in updating the user interface management of lists and messages. For complete details on auto-login, see Connections, sessions and authorizations.
You can use the AuthPreferences property and its PutUnattendedModePref method to specify whether your application needs auto-login (unattended mode) permissions. The appropriate authorization dialog will be presented to the user the next time your application calls BeginSession. (Notice that only the QuickBooks administrator can authorize this.)
However, in order for your application to run using the auto-login option, the QuickBooks administrator must first define an auto-login user in QuickBooks; The administrator can specify that your application run under any user, including the administrator.
The QuickBooks administrator must configure each QuickBooks user that your application will log in under to have the permissions your application requires. For example, if your application deals with time sheets and time reports in QuickBooks, the administrator must grant your user Time Tracking permissions in QuickBooks when the administrator sets up the name and password for the new user.
Check the QuickBooks documentation to determine what permissions your application requires. Then, to ensure that things work properly, use the AuthPreferences property and its methods to prompt the user for the correct permissions. Also, include explicit directions in your documentation on how to set these permissions and why they are necessary.
For a thorough discussion of authorization, see Connections, sessions and authorizations.
The QuickBooks administrator must authorize an application to deal with personal data such as employee social security numbers, any field directly related to an employee’s salary, and anything related to credit card numbers or bank account numbers. Click the Integrated Applications icon in QuickBooks, then Company Preferences, then Properties and be sure the administrator checks the box for allowing the application to access personal data.
Note
Note
The application can use the AuthPreferences property and the property method PutPersonalDataPref to specify whether this access is required, optional, or not needed. This will cause the appropriate authorization dialog to be displayed to the user.
As described in Warn Your Users to Complete Error Recovery before Upgrading, it is important that you include directions to your users to complete error recovery within the same version of the application used when the problems occurred. You should include this information in installation notes to upgrades of your product. If you find it warranted, you might also include it in your more formal documentation.