Connections sessions and authorizations

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.

Connection and session snippet for applications that use qbXML

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:

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.

Connection and session snippet for applications that use QBFC

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.

Connection type parameter

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.

File access mode parameter

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.

Authorizations

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.

Authorization process

The authorization process proceeds as follows:

  1. Before an application is authorized, QuickBooks has no authorization information for it and doesn’t know whether to grant it access. Therefore, when the application first attempts to begin a session with QuickBooks, QuickBooks must be running, a company file must be open, and the QuickBooks administrator must be logged in. This gives the administrator the opportunity to authorize the application.
  2. The first time an application calls BeginSession, if the conditions listed above are met, QuickBooks opens its authorization dialog. The dialog can display either:
    • The default authorization options, which give the QuickBooks administrator user a choice of three default authorization options.
    • Application-specific authorization options, which are specified by the application in authorization preferences and passed in the BeginSession call, which tell the QuickBooks administrator exactly what kind of authorization the application needs in order to function fully.
  3. The QuickBooks administrator grants (or doesn’t grant) the application some set of authorization privileges.
    • If the QuickBooks administrator grants one-time access, on every subsequent attempt to begin a session, the initial conditions (QuickBooks running, company file open, and QuickBooks administrator logged in) must be met, and the authorization dialog will be displayed again.
    • If the QuickBooks administrator grants some form of ongoing authorization, this is recorded in QuickBooks, and on subsequent attempts QuickBooks will recognize the application as authorized and allow it access without displaying the authorization dialog.
  4. However, if the privileges requested by the application change (for example a new version of the application requests different privileges in its BeginSession call) QuickBooks will again display the authorization dialog.
  5. Similarly, if the QuickBooks administrator uses the QuickBooks user interface to change the privileges granted to the application, a BeginSession call will redisplay the authentication dialog.
Authorization options

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      
AuthPreferences object

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:

../../../_images/authentication_dialog_with_preferences_1.jpg ../../../_images/authentication_dialog_with_preferences_2.jpg

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.

Setting authorization preferences via qbXML

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.

Setting authorization preferences via QBFC

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
Unattended mode (auto-login)

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:

../../../_images/multi_users_and_auto_login.gif
Using authorization flags to indicate which QuickBooks editions are supported

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.

Setting authorization flags to identify supported QuickBooks editions

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:

  1. Instantiate the session manager and then instantiate the AuthPreferences object, as shown above in AuthPreferences object.
  2. Construct the desired authFlags value.
  3. Invoke the PutAuthFlags method on AuthPreferences, passing the authFlags value you just constructed.

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.

Single sessions and multiple sessions

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.

What happens in the BeginSession call?

When your application makes a BeginSession call, the request processor checks the following:

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.

Troubleshooting errors in the BeginSession call

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.