GetPersonalDataPref) that return the authorization preferences currently in effect, but these methods can only be invoked AFTER the call to BeginSession.
IM PORTAN T
Your code im plem ent ing t he new aut hor izat ion capabilit ies w ill not set pr efer ences on QB ver sions earlier t han QuickBooks 2005. How ever, no er r or s w ill occur if you use
Aut hPr efer ences and it s r elat ed m et hods, so you can safely w rit e code and expect no failur es. How ever, you m ay want t o do a check , using t he Aut hPreferences m et hod
WasAut hPr efer encesObeyed t o det er m ine w het her t he QuickBook s ver sion support s Aut hPreferences or not .
Code Sa m ple : Usin g Au t h Pr e fe r e n ce s
The following snippet is taken from the SDK sample SDKTestPlus3, which is located at samples\qbdt\vb\qbxml\SDKTestPlus3. This snippet shows the use of the AuthPreference object to set preferences in AuthPreferences. Notice that this does not set QuickBooks authorization preferences (only the QuickBooks administrator can do that) but it sets up AuthPreferences so that QuickBooks will display the authorization dialogs that correspond to the preferences your applications has specified.
If (frmSDKTestPlus3.AuthPrefsDirty) Then Dim prefs As QBXMLRP2Lib.AuthPreferences Set prefs = qbXMLCOM.AuthPreferences If (frmSDKTestPlus3.Unattended.Value) Then
prefs.PutUnattendedModePref umpRequired Else
prefs.PutUnattendedModePref umpOptional End If
prefs.PutIsReadOnly frmSDKTestPlus3.ReadOnly.Value If (frmSDKTestPlus3.pdRequired.Value) Then
prefs.PutPersonalDataPref pdpRequired
ElseIf (frmSDKTestPlus3.pdNotNeeded.Value) Then prefs.PutPersonalDataPref pdpNotNeeded Else
prefs.PutPersonalDataPref pdpOptional End If
End If
In this snippet, the parent form frmSDKTestPlus3 is checked to see whether any
preferences have been changed. If any changes were made, the various components in the form are checked for new user selections and those choices are then set in the
AuthPreferences object.
NOTE
This snippet is for a sandbox t y pe applicat ion t hat allow s for a r unt im e changing of t he Aut hPrefer ences r equirem ent s. Your applicat ion pr obably w ould not do t his, but w ould inst ead sim ply set t he pr efer ences in t he way your applicat ion requires.
The next time the application connects to QuickBooks after any change, the proper
authorization dialog is shown. For example, if you set the AuthPreferences such that access to personal data was required, the ability to run in unattended mode was required, and you specified read-only access, then the authorization dialog shown in Figure 2-2 on page 12 would be shown to the user.
Figure 2- 2 Aut horizat ion Dialog for Read- Only, Personal Dat a, and Unat t ended Mode
If the user chooses to authorize, QuickBooks pops up the confirmation message shown in Figure 2-3 on page 13.
Figure 2- 3 Aut horizat ion Confirm at ion
Notice that the confirmation messages lists all of the authorized access preferences.
Set t ing Aut horizat ion Preferences Wit hin QuickBooks
If your application does not use the AuthPreferences object and methods to help the QuickBooks administrator set authorizations properly, the QuickBooks administrator may need to set additional authorization preferences or change existing authorization
preferences for integrated applications within QuickBooks by clicking on the Integrated Applications icon in the QuickBooks Preferences window, then selecting Company Preferences. Preferences that can be set by the administrator include the following:
• Disallowing or changing application access
• Enabling certificate date checking
• Listing authorized applications
• Granting auto-login privileges and assigning the name of the auto-login user
• Allowing application access to personal company data
Figure 2-4 on page 14 shows the window presented to the administrator for managing integrated applications and their access to QuickBooks.
Figure 2- 4 I nt egrat ed Applicat ion Preferences
More I nform at ion about Login Modes
Integrated applications can log in to QuickBooks in one of two modes:
• In interactive mode, QuickBooks runs in the foreground, and its user interface is displayed. The user logs in to QuickBooks and opens a company file. Subsequently, your application is launched and “attaches” to the company file that has already been opened. The user can interact directly with your application and with QuickBooks.
• In unattended mode (auto-login), QuickBooks runs in the background, and its user interface may or may not be displayed, depending on the connection type you specify in the call to OpenConnection2. The ctLocalQBD type either uses the local
QuickBooks currently running or, if not running, launches QB in unattended mode (without UI, thus non interactively). If QuickBooks is not running, the
ctLocalQBDLaunchUI type launches it in interactive mode (the UI is displayed). If your connection type doesn’t specify the launching of the QuickBooks UI, then QuickBooks features are fully available to your application but not to the user. Notice that whenever QuickBooks is started by the application rather than by the small-business owner, it is in auto-login mode.
NOTE
When an applicat ion accesses a com pany file t hat was opened by a user from t he QuickBooks user int er face, t he applicat ion has t he sam e pr iv ileges as t hat logged- in user. I n som e cases, t he user can im pose fur t her r est r ict ions via t he pr efer ences for t he applicat ion. ( I n QuickBooks, br ing up pr efer ences by select ing Edit - > Pr efer ences- > I nt egrat ed Applicat
ions-> Com pany Pr efer ences- ions-> Pr oper t ies.)
Se t t in g Up Au t o- Login
As described in the preceding section, you use the AuthPreferences object to inform the user that auto-login (unattended) mode is required. The proper dialog with the auto-login prompt will be presented to the user for confirmation. If the user chooses not to authorize your application’s requirements, then your application will not be allowed to access the QuickBooks company. Notice that this is “all or nothing.” Either your application gets all of its requirements or it is refused access to QuickBooks.
Alternatively, you can set up auto-login from within QuickBooks. Using this method, the QuickBooks administrator sets the user name under which your application will run in QuickBooks under Company Preferences, Properties, Access Rights, a window that is accessible only to QuickBooks administrators (see Figure 2-5 on page 15).
Figure 2- 5 QuickBooks window for allowing aut o- login by an int egrat ed applicat ion
If you don’t use AuthPreferences, be sure to tell your user that the QuickBooks administrator must give your application the necessary authorizations.
W h a t H a ppe n s if t h e Adm in ist r a t iv e Use r D e le t e s t h e Au t o- Login Use r ?
If an application is set up for auto-login, then a warning message is displayed to the
administrative user when that user attempts to delete. The message indicates that the user to be deleted is used by an integrated application.
IM PORTAN T
I f an applicat ion st ar t s QuickBooks in aut o- login m ode, any subsequent applicat ions aut hor ized for aut o- login w ill have t he pr iv ileges of t he fir st applicat ion dur ing t hat session. The fir st aut o- login applicat ion set s t he user for any subsequent applicat ions dur ing t he session. This is t he user t hat is t he
“ act ive” user for all applicat ions unt il all of t he applicat ions end t heir sessions and QuickBooks exit s.
Only One Aut o- Login User per Applicat ion
Regardless of whether single-user or multi-user mode is specified for a given session, there can be only one auto-login active during that session. Figure 2-6 on page 16 illustrates a multi-user session, with four different users accessing the same company file. Because Joe is designated as an auto-login user on System 4, no other users can log in automatically until “Joe” (the auto-user) logs out. When multiple instances of an integrated application are running on different systems and accessing the same company file, as shown in Figure 2-6 on page 16, each user must have a different name.
Figure 2- 6 Mult iple users accessing t he sam e com pany file
Lim it at ions on Accessing Com pany Files
Only one company file at a time can be accessed by integrated applications on any given machine running QuickBooks. The company file that must be used by integrated
applications is the one currently opened by the user from the QuickBooks user interface, or the company file that is currently open by an application that started QuickBooks in auto-login mode.
Company File:
QuickBooks System 1 User: Sam (interactive login)
Joe’s Bakery
(shared drive) User: Jane (interactive login)
User: Everett (interactive login)
User: Joe (auto-login) QuickBooks System 2
QuickBooks System 3
QuickBooks System 4
Allowing Applicat ion Access t o Personal Dat a
The Access Rights window shown in Figure 2-5 on page 15 also includes a checkbox that allows your application access to personal data in the company file. Personal data can include:
• Employee social security numbers
• Any field directly related to an employee’s salary or wages
• Anything related to credit card numbers or bank account numbers
Be sure to instruct the QuickBooks administrator to check this box if your application requires access to personal employee or customer data. (Alternatively, your application can require access to personal data using the AuthPreferences object, which is available for QuickBooks 2005 and later.)
Single- User vs. Mult i- User Mode
During a QuickBooks session, your application specifies whether to open the company data file in single-user or multi-user mode. It is important to balance your needs with the overall implications of selecting one mode over the other. Table 2-1 on page 18 summarizes the different combinations. Note that if an integrated application opens a company file in single-user mode, no other applications or users can work on that company file during that session. In some cases, this mode may be necessary, but in others it may be bad citizenship.
Another interesting case is that even when the integrated application opens a company file in multi-user mode, other integrated applications can access the company file, but no actual users can access that company file on the same system.
Table 2- 1 QuickBooks com pany file login m ode access condit ions and rI ght s
Trade- offs of Using Single- User Mode
Here are some of the advantages and disadvantages of using single-user mode.
Advantages:
• Certain QuickBooks features require that a user operate in single-user mode. For instance, a company file must be open in single-user mode for you to delete any of its list items.
• Locking and opening protection. If the company file is not already opened by another QuickBooks-integrated application, your application will be able to open it with exclusive access (locking out other applications), gaining improved performance.
Disadvantages:
• Lockout. If your application attempts to open a company file in single-user mode and that company file is already open in multi-user mode, your application will not be able to access the company data file. Your application will be locked out. (If your
application specifies multi-user mode, it can share access to the company file.)
• Exclusion of other applications. Your application locks out other applications, denying them access to the company file. This behavior is considered impolite. In environments that are known to need multi-user access, this might be of some concern.
W ho st a r t e d Qu ick Book s M ode W h o m a y obt a in a cce ss I nt egrat ed Applicat ion Single- user No one else
I nt egrat ed Applicat ion Mult i- user QB users on sam e m achine = no access
All ot her int egrat ed applicat ions
= access
QB users on ot her m achines = access
QuickBooks User Single- user QB user already logged in Only one int egrat ed applicat ion
= access
QuickBooks User Mult i- user QB users = access
I nt egrat ed applicat ions = access
Hello, QuickBooks
The following code samples illustrate the typical sequence for communicating with
QuickBooks. The first example is written in C++, the second in Visual Basic. Highlights of this sample test code are as follows (see boldface calls in sample code):
1. Read the qbXML request from a file.
2. Instantiate the Request Processor.
3. Open the connection to QuickBooks (OpenConnection method; the application name and ID are parameters to this method, or default values can be used here).
4. Begin the session for working on a specific company (BeginSession method; the QuickBooks company data file is provided here as a parameter. The mode can also be specified here. Your application needs to save the ticket.).
5. Show the name of the currently open data file.
6. Process the request (ProcessRequest method; uses the ticket and reads data from the provided qbXML file). This step can be repeated multiple times within a session.
7. Dump the response to a file.
8. End the session (EndSession method).
9. Close the connection (CloseConnection method).
C+ + Exam ple
The complete sample code for this example is included in the SDK; see SDKTest.cpp. Also see the Visual Basic sample code in the following section and in Appendix A of the Technical Overview.
if (!readXMLinputFile (inputXMLFileName, &xmlInput)) {
std::cout << "SDKTEST: Could not read the XML input file.\n";
return;
} try {
std::cout << "SDKTEST: COM access to SDK starting ...\n";
// start the clock startTime = clock();
hr = pReqProc.CreateInstance (__uuidof (QBXMLRP2Lib::RequestProcessor2));
if (SUCCEEDED (hr) && pReqProc != NULL) {
hr = pReqProc->OpenConnection (appID.m_str, appName.m_str);
if (SUCCEEDED (hr)) {
hr = pReqProc->BeginSession (qbFile.m_str, qbMode, &ticket);
if (SUCCEEDED (hr)) {
hr = pReqProc->GetCurrentCompanyFileName (ticket,
&companyName);
if (SUCCEEDED (hr)) {
std::cout << "data file name: " <<
_com_util::ConvertBSTRToString (companyName) << "\n";
} else {
std::cout << "could not get the data file name\n";
}
std::cout << "could not open output file" <<
outputXMLFileName << "\n";
} else {
TCHAR *outputData2; // this pointer does not change;
TCHAR *outputData = _com_util::ConvertBSTRToString (xmlOutput);
outputData2 = outputData; // keep it so that we can // delete it
}
pReqProc->CloseConnection ();
} }
finishTime = clock();
if (FAILED (hr)) { handleError (hr);
}
duration = (double) (finishTime - startTime) / CLOCKS_PER_SEC;
sprintf (durationStr, "SDKTest: Finished after %3.3f seconds\n", duration);
std::cout << durationStr;
} catch (const _com_error& err) { std::cout << "Error: ";
_bstr_t desc = err.Description();
if (desc.length() > 0) { std::cout << (char *) desc;
} else {
const TCHAR * message = err.ErrorMessage();
if (message != NULL) { std::cout << message;
} else {
std::cout << "No additional information";
} } }
} // process_XMLDataCOM
Visual Basic Exam ple
The Visual Basic version of “IDN: Hello, QuickBooks” is listed below. Notice the use of OpenConnection2, new in SDK 4.0, which specifies that the connection to be made is with a copy of QuickBooks on the same machine (local) as the application.
Public Function sendXMLtoQB(xml As String) As String On Error GoTo errHandler
' Open connection to qbXMLRP COM
Dim qbXMLRP As New QBXMLRP2Lib.RequestProcessor2
qbXMLRP.OpenConnection2 "", "IDN: Hello, QuickBooks", localQBD ' Begin Session
' Pass empty string for the data file name to use the currently ' open data file.
When your application makes a BeginSession call to QuickBooks, the QuickBooks qbXML Request Processor checks to ensure that the following are true:
• QuickBooks Version 10 or greater is currently running.
• The version of QuickBooks and the version of the company data file, if one was specified, match one another. (If NULL or an empty string was specified, this task is skipped.)
• The file access mode specified by your application and the mode in which the company data file is currently open are compatible.
• The Request Processor is able to successfully launch the located, required version of QuickBooks. If it cannot start QuickBooks, any number of problems might exist; for instance, QuickBooks might not have been correctly installed (perhaps only partially installed) or there might be some other problem with QuickBooks.
• The QuickBooks administrator has granted the application permission to log in automatically. If this permission has not been granted in the QuickBooks Integrated Applications Preference section, which is accessible to administrators only,
QuickBooks returns an error code to your application in the BeginSession call.
If any of these tasks fail, your application will not be able to complete the login process or connect to QuickBooks. However, in the event of failure, your application will have the opportunity to present the user with direction on how to resolve the problem. For related information, see Chapter 3, “Supporting Your User.”
Subscribing Your Application to QuickBooks Events
The QuickBooks SDK Concepts Manual provides a description (see the chapter on Event Notification) of event notification and how to implement a qbXML application that handles these events.
For information on the request processor API supporting event subscription, see Chapter 4,
“Method Reference,” later in this guide.
C HAPTER 3
1S UPPORTI NG Y OUR U SER
1This chapter 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 outlined here.
Helping Users Troubleshoot and Resolve Problem s
The most commonly occurring error conditions not resolvable by your application are
• Version incompatibility between the running version of QuickBooks and the version of QuickBooks your application requires
• Version incompatibility between the company data file and QuickBooks
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.
Mult iple I nst alled Versions of QuickBooks
If multiple versions of QuickBooks are installed, either of the following two cases might prevail:
• No version of QuickBooks is open.
No problem: In this case, when the user opens your application and your application attempts to connect to QuickBooks to begin processing, the Request Processor will locate and successfully launch the correct version of QuickBooks.
• A version of QuickBooks that is incompatible with the application is open.
Problem: In this case, when the user launches your application and your application calls the BeginSession method to connect to QuickBooks in response to a user action, your application will receive result code 0x80040404, which indicates that the version of QuickBooks currently running does not support the QuickBooks SDK.
Response: Your application should present the user with a window informing the user of the problem and the version of QuickBooks required. The window content should
direct the user to quit the currently open version of QuickBooks and launch the correct version.
I ncom pat ible Versions: QuickBooks and Com pany File
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).
Different Com pany File I s Already Open
Problem: If the user specifies the name of a company file that is different from the one
Problem: If the user specifies the name of a company file that is different from the one