If you walked through the demonstration of basic steps with SDKTestPlus3, you saw that before an application can send an actual data request, it must open a connection to the QuickBooks request processor, then begin a session, and then get authorized. The demonstration performed these steps in the simplest possible way. This page looks at how you perform these steps in your applications, with attention to following points:
This is not a large number of options, but some of these options interact with others, and the number of possible combinations is large enough to require some care in choosing an application’s connection, session, and authorization options.
Because of the interactions between connection type, file access mode, and authorization type, this page looks at connections, sessions, and authorizations together. For more information about the request processor, see Communicating with QuickBooks: the QuickBooks request processor.
In the demonstration, you launched the SDKTestPlus3 tool and clicked buttons that opened a connection with the QuickBooks request processor and began a session. In an application, you write code that does these things. If your application is going to use qbXML directly, you use methods of the
QBXMLRP2Lib.
Depending on which programming language you are using, you can gain the necessary access to the lib with an import statement, a project reference, or a similar technique.
The following snippet shows, in Visual Basic, the sequence of calls that opens a connection and begins a session.
1 2 3 4 5 6 7 8 9 10 11 12 | Dim MyQbXMLRP2 As QBXMLRP2Lib.RequestProcessor2 Set MyQbXMLRP2 = New QBXMLRP2Lib.RequestProcessor2 MyQbXMLRP2.OpenConnection2 "", "My Sample App", localQBD Dim ticket As String Dim sendXMLtoQB As String ticket = MyQbXMLRP2.BeginSession("", QBXMLRP2Lib.qbFileOpenDoNotCare) ‘ The variable “xmlRequestSet” in the following line represents a fully formed qbXML request set; ‘ This snippet omitted the code that assembled the request set in order to keep the ‘ example focused on the session and the connection. sendXMLtoQB = MyQbXMLRP2.ProcessRequest(ticket, xmlRequestSet) MyQbXMLRP2.EndSession ticket MyQbXMLRP2.CloseConnection |
The OpenConnection2 call has three parameters. The values supplied in this snippet are:
The parameters supplied in this snippet for the BeginSession call are also basic values:
QBXMLRP2Lib.qbFileOpenDoNotCare
is supplied. This parameter indicates whether the application is requesting access to the company file in single-user mode or multi-user mode. The value supplied – QBXMLRP2Lib.qbFileOpenDoNotCare
– allows for
either multi-user or single-user mode, depending on whether the company file is currently open or not.Use of these parameters to specify how an application interacts with QuickBooks at run time is explored below.
If the BeginSession call succeeds, it returns a session ticket, which you need to supply as a parameter for the various following calls to the request processor, such as ProcessRequest and CloseConnection.
If you use the QBFC foundation classes, you need to include and use the QBFC DLL How you do this depends on which programming language you are using.
The following snippet shows the sequence of calls, in Visual Basic, that connects to the request processor and opens a session:
1 2 3 4 5 6 7 8 9 10 11 | Dim MySessionManager As QBSessionManager Set MySessionManager = New QBSessionManager MySessionManager.OpenConnection2 “ “, “My Sample App”, ctLocalQBD MySessionManager.BeginSession "", omDontCare ‘ In the following lines, “MyMsgRequestSet” represents a fully formed message ‘ request set; the steps for assembling the request set were omitted to keep ‘ this snippet focused on connections and sessions. Dim MyDataExt_resp As IMsgSetResponse Set MyDataExt_resp = MySessionManager.DoRequests(MyMsgRequestSet) MySessionManager.EndSession MySessionManager.CloseConnection |
The parameter values in this snippet generally parallel those supplied in the qbXML snippet above. However, the call to MySessionManager.OpenConnection2 does not visibly return a session ticket. The ticket is handled internally by QBFC.
The third parameter of the OpenConnection call (the values used in the snippets are localQBD
and ctLocalQBD
) specifies the type of connection the application is requesting. As mentioned above, the behavior of the application and QuickBooks when beginning a session is affected by the
combination of connection type and the application’s authorization privileges, particularly when the application has been authorized for running unattended (auto-login).
Running unattended (auto-login) is an privilege that can be granted during the authorization process:
The default privilege for this parameter is umptOptional
, and with this type of authorization, connection type has no effect on behavior, so you will mostly be concerned with the effects of the connection type parameter if you are developing an application that you expect to run unattended. For
more information on running unattended, see Unattended mode (auto-login).
The possible combinations of connection type and the running unattended privilege, and the resulting behaviors, are listed in the following table. Note that this describes the behavior when authorization privileges have been granted, and the application’s authorization preferences, if any, match the actual authorization privileges in QuickBooks.
If, for any reason–such as manual change to privileges via the QuickBooks Ui, or a new version of the application with different authorization preferences-the authorization preferences sent in BeginSession do not match the authorization privileges in QuickBooks, there will be problems.
connType (or connPref) specified in the OpenConnection call | Application’s requested authorization privilege is umptOptional | Application’s requested authorization privilege is umptRequired |
---|---|---|
localQBD | QuickBooks is running: If a company file is specified in BeginSession and it is open, the session begins and the application is able to send and receive messages. If a company file is specified in BeginSession and it is not open, QuickBooks returns an error. If no file is specified in BeginSession, QuickBooks checks to see whether application is authorized to access the currently open company file; if it is not authorized, QuickBooks will open the authorization dialog, and the session does not begin until an administrator authorizes the application. QuickBooks is not running: QuickBooks returns an error |
TaQuickBooks is running: If a company file is specified in BeginSession and it is open, the session begins and the application is able to send and receive messages. If a company file is specified in BeginSession and it is not open, QuickBooks returns an error. If no file is specified in BeginSession, QuickBooks checks to see whether application is authorized to access the currently open company file; if it is not authorized, QuickBooks will open the authorization dialog, and the session does not begin until an administrator authorizes the application. QuickBooks is not running: The BeginSession call must specify a company file. If the file specified is a valid file name, and the application is authorized to access it, the session begins (without opening the QuickBooks UI) and the application is able to send and receive messages. QuickBooks features are fully available to the application but not to a user (unless that user starts the UI and multi-user is allowed).xable |
localQBDLaunchUI | QuickBooks is running: If a company file is specified in BeginSession and it is open, the session begins and the application is able to send and receive messages. If a company file is specified in BeginSession but it is not open, QuickBooks returns an error. If no file is specified in BeginSession, QuickBooks checks to see whether application is authorized to access the currently open company file; if it is not authorized, QuickBooks will open the authorization dialog, and the session does not begin until an administrator authorizes the application. QuickBooks is not running: QuickBooks is unable to begin a session. |
QuickBooks is running: If a company file is specified in BeginSession and it is open, the session begins and the application is able to send and receive messages. If a company file is specified in BeginSession but it is not open, QuickBooks returns an error. If no file is specified in BeginSession, QuickBooks checks to see whether application is authorized to access the currently open company file; if it is not authorized, QuickBooks will open the authorization dialog, and the session does not begin until an administrator authorizes the application. QuickBooks is not running: The BeginSession call must specify a company file. If the file specified is a valid file name, and the application is authorized to access it, the QuickBooks UI opens. If the user that was specified on the authorization dialog (when the application was initially authorized) has a password, that user account must log in before the session begins. When the session begins, the application is able to send and receive messages. Other users may be able to work with the UI during the session. |
The second parameter of the BeginSession call (the values used in the snippets are QBXMLRP2Lib.qbFileOpenDoNotCare
and omDontCare
) specifies the application’s preference for opening a company data file. The possible values are single-user mode, multi-user mode, and do not care.
One thing to keep in mind is that QuickBooks defines an access mode for each company file, and if the access mode specified in a BeginSession call does not match the mode defined in QuickBooks, BeginSession will return with an error and the session will not begin. The do not care option is designed to avoid these errors in situations when the access mode does not matter to the application.
Some circumstances that make single-user mode preferable:
Some circumstances that may make multi-user mode preferable:
In addition, the file access mode chosen by an application has an effect on overall file access for other applications and active QuickBooks GUI users, even when QuickBooks has been started by a user before the application began its session. The possible combinations of file access mode and who started QuickBooks, and the resulting behaviors, are listed in the following table.
Who started QuickBooks | openMode/qbOpenFileMode | Who may access |
---|---|---|
Application, via SDK | omSingleUser/qbFileOpenSingleUser | All other integrated applications have access QuickBooks users have no access. |
Application, via SDK | omMultiUser/qbFileOpen | All other integrated applications have access QuickBooks users on same machine have no access QuickBooks users on other machines have access |
Application, via SDK | omDontCare/qbFileOpenDoNotCare | All other integrated applications have access QuickBooks users on same machine have no access QuickBooks users on other machines have access |
QuickBooks User | single-user | Only one integrated application will have access The QuickBooks user who started QuickBooks will continue to have access |
QuickBooks User | multi-user | All integrated applications have access All QuickBooks users have access |
QuickBooks User | do not care | All other integrated applications have access QuickBooks users on same machine have no access QuickBooks users on other machines have access |
Note
Note
If QuickBooks 2007 and later is running non-hosted, SDK applications that start QuickBooks in DoNotCare mode will open QuickBooks in single-user mode.
If you walked through the demonstration of basic steps with SDKTestPlus3, you saw that the BeginSession call triggered the display of the QuickBooks authorization dialog, and you accepted the default value, Yes, prompt each time, which allowed SDKTestPlus3 to access a single company file for the duration of the session.
In some cases, you may decide that one-time authorization like this, repeated for each session, is the way to have your application authorized, but the Desktop SDK offers a number of other ways to authorize an application, which are covered in this section.
The authorization process proceeds as follows:
As mentioned above, the first time your application calls BeginSession, it can let QuickBooks open the default authorization dialog and let the administrator select from the three default authorization options, or it can send authorization preferences, which are passed with the BeginSession call and give the administrator guidance in granting privileges. All of these options are summarized and compared in the following tables. (Remember that at the time of the initial BeginSession call, QuickBooks must be running, the administrator must be logged in, and a company file that will be accessed by the application must be open.)
The following table lists the three default authorization modes–these are listed on the default authorization dialog, which is displayed in response to the initial BeginSession call when the application sends no authorization preferences.
All three default modes support the Allow this application to access personal data… option.
Authorization features supported in each of the default authorization modes: | Supports option to authorize access to personal data? | Supports option to authorize read-only, no-write access? | Supports option to run unattended (auto-login)? | Supports option to specify compatible QuickBooks versions? |
---|---|---|---|---|
Yes, prompt each time –requires repeated, one-session- only authorizations | X | |||
Yes, whenever this QuickBooks company file is open –allows on-going access to a running QuickBooks (QuickBooks must be running and the authorized company file must be open before the application can begin a session). | X | |||
Yes, always, allow access even if QuickBooks is not running –allows on-going access to QuickBooks, running or not (if QuickBooks is not running, BeginSession will start QuickBooks in the background, with no UI. See `Connection type parameter onnection-type-parameter>`__ and Unattended mode (auto-login) for more information. | X | X |
The second table lists the authorization modes that can be requested with authorization preferences and authorization flags. On an initial BeginSession call from an application that has set authorization flags and preferences, QuickBooks will display an application-specific authorization dialog to the administrator, showing only the type of authorization that the application has requested.
Authorization features requested by setting the authorization preferences and flags: | Requests option to authorize access to personal data? | Supports option to authorize read-only, no-write access? | Supports option to run unattended (auto-login)? | Supports option to specify compatible QuickBooks versions? |
---|---|---|---|---|
Set authorization flags to identify compatible QuickBooks versions | X | |||
Use authorization preference: PutUnattendedModePref–allows ongoing access to QuickBooks, running or not (if QuickBooks is not running, BeginSession will start QuickBooks in the background, with no UI). SeeConnection type parameter and Unattended mode (auto-login) for more information. - | X | |||
Use authorization preference: PutIsReadOnly–allows on-going access to QuickBooks in read-only mode. | X | |||
Use authorization preference: PutPersonalDataPref–allows the application to access personal data that may be in the QuickBooks company file. | X |
Setting authorization preferences with the AuthPreferences object tells QuickBooks exactly which privileges your application requires, which simplifies the administrator’s work by limiting the options on the authorization dialog to only those that are relevant to your application. Notice that the user must be logged in as the QuickBooks administrative user in order to review the requested privileges and approve them. Remember to explain in your documentation what the QuickBooks administrator should expect to see during installation and setup.
To set authorization preferences in your application, use the methods of the AuthPreferences object (first available with the QuickBooks 2005 SDK). The AuthPreferences object has three “put” methods, each of which sets a different preference:
PutIsReadOnly
– calling this method indicates that the application can function with read-only access; the QuickBooks authorization dialog will display a message informing the administrator that the application’s access will be read-only; if authorization is granted the application will have read-only access.PutUnattendedModePref
– calling this method indicates whether the application is requesting unattended (auto-login) mode:umptOptional
– calling with this parameter indicates that the application does not require unattended mode; the authorization dialog will display the three default authorization options and let the administrator choose from them (including the option to allow unattended mode).umptRequired
– calling with this parameter indicates that the application requires unattended mode to function properly; the authorization dialog will display only two choices, Yes, allow access even if QuickBooks is not running, which authorizes unattended mode and No, which declines any authorization for the application. (In other words, “if it’s going to be running unattended, I want to disallow it from running at all.”) If Yes is selected, the administrator is also asked to select the user account the application should run under. If that account has a password, and if the application accesses QuickBooks when it is running, QuickBooks will require that account to log in.PutPersonalDataPref
– calling this method indicates what degree of access to personal data the application is requesting:pdpRequired
– calling with this parameter indicates that the application requires access to personal data; the QuickBooks authorization dialog will not display the personal information checkbox to the administrator; instead it displays a warning that the application will access personal data such as SSN or credit card information.In addition to these methods, the AuthPreferences object has three “get” methods (GetIsReadOnly
, GetUnattendedModePref
, and GetPersonalDataPref
) that an application can use to determine the authorization preferences currently in effect. These methods can only be invoked after a
successful call to BeginSession.
Setting authorization preferences with the AuthPreferences object has no effect on QuickBooks versions earlier than QuickBooks 2005. However, no errors will occur if you use AuthPreferences and its related methods with earlier versions, so you can safely write AuthPreferences code and know that there will be no failures. However, you may want to add a check to your application, using the AuthPreferences method WasAuthPreferencesObeyed that determines whether the QuickBooks version supports AuthPreferences or not.
The following snippet shows the use of the AuthPreferences object to set preferences. This sample is from an application that will write its own qbXML, so it uses QBXMLRP2Lib to set the authorization preferences.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | 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-type application (SDKTestPlus3) that has a user interface that toggles the AuthPreferences requirements for test purposes. Your application should not do this, but simply set the preferences in the way your application requires.
The following snippet shows how to set the AuthPreferences object with QBFC.
1 2 3 4 5 6 7 8 9 | Dim SessionManager As QBSessionManager Set SessionManager = New QBSessionManager Dim MyAuthPrefs As IAuthPreferences Set MyAuthPrefs = SessionManager.QBAuthPreferences MyAuthPrefs.PutIsReadOnly SessionManager.OpenConnection2 appID, appleName, ctLocalQBD SessionManager.BeginSession "", omDontCare |
As noted above, an application can indicate via the authorization preferences that it requires running in unattended mode (auto-login). Here are some things to note about unattended mode:
Prior to QuickBooks 2006, the various editions of QuickBooks provided virtually the same support for the various SDK requests. However, beginning with QuickBooks 2006, a new edition called QuickBooks Simple Start provides support for a subset of SDK requests. Consequently, to prevent applications from behaving unexpectedly while running on QuickBooks Simple Start, the request processor now checks the AuthFlags property during the call to BeginSession to determine whether your application supports QuickBooks Simple Start.
For existing applications that aren’t designed for QuickBooks Simple Start, no code changes are necessary, because by default, AuthFlags is set to support QuickBooks Pro, Premier, and Enterprise.
However, if you are writing an application that does support QuickBooks Simple Start, you need to explicitly set AuthFlags to indicate your application’s support of that edition. Otherwise, if your application attempts to begin a session with QuickBooks Simple Start, you will get an error when you call BeginSession.
Another feature provided by the SDK is the ability for an application to identify which editions of QuickBooks it supports. To do this, the application uses the “put” methods for the authFlags method of the AuthPreferences object before it calls BeginSession. The basic call sequence is straightforward:
The tricky part in all this is constructing the authFlags value. The QuickBooks editions are represented by the following enumerated values:
Behavior Needed | Value |
---|---|
SupportQBSimpleStart | 0x1 |
SupportQBPro | 0x2 |
SupportQBPremier | 0x4 |
SupportQBEnterprise | 0x8 |
ForceAuthDialog | 0x80000000 |
The ForceAuthDialog value is included as a convenience; if you include it when you construct your authFlags, QuickBooks will display the authorization dialog, allowing the administrator to change any permissions that may have been set for your application.
To specify support for multiple editions, you simply OR the values for each edition you are supporting. The following VB snippet specifies support for all of the QuickBooks editions and forces the display of the authorization dialog.
1 2 3 4 5 6 7 8 | Dim authFlags As Long authFlags = 0 authFlags = authFlags Or &H8& authFlags = authFlags Or &H4& authFlags = authFlags Or &H2& authFlags = authFlags Or &H1& authFlags = authFlags Or &H80000000 |
After constructing the authFlags, set them as follows:
1 2 3 4 | Dim qbXMLCOM As QBXMLRP2Lib.RequestProcessor2 Dim prefs As QBXMLRP2Lib.AuthPreferences Set prefs = qbXMLCOM.AuthPreferences prefs.PutAuthFlags (authFlags) |
The SDK sample program SDKTestPlus3 provides an example of constructing the authFlags a bit more selectively, ORring only the editions you choose in its UI.
If you start your application by invoking BeginSession with localQBDLaunchUI and you have Simple Start, but do not set the authFlags to specify Simple Start support, Simple Start will launch with the company file specified, and you’ll get an error regarding the fact that your application doesn’t support Simple Start. Once Simple Start is launched in this scenario, your application won’t have SDK access to Simple Start.
An SDK session gives your application access to one company file. Depending on whether your typical user behavior is working with a single company file or working with multiple company files in QuickBooks, your application may need to supply the ability for the user to request termination of a session and then begin another session with another company file.
In most cases, an application will send multiple requests to QuickBooks in a single session. The processing is synchronous: your application must wait until one ProcessRequest call completes execution and returns with the qbXML response data sent from QuickBooks before issuing the next ProcessRequest call.
When your application makes a BeginSession call, the request processor checks the following:
umptRequired
and QuickBooks is not currently running), that this privilege has been already been granted by the QuickBooks administrative user.If any of these checks fail, your application will not be able to complete the login process and begin a session . However, in the event of failure, your application will have the opportunity to present the user with directions on how to resolve the problem. For related information, see Making your application robust.
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.