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:

• An application will open a connection and begin a session by calling SDK methods that communicate with the request processor.
• The OpenConnection call has an option for connection type that indicates whether the QuickBooks UI must be open for the application to connect.
• The BeginSession call has an option for file access mode that indicates whether the application will access the company file in single-user or multi-user mode.
• An application is authorized to access QuickBooks (or denied) when it makes a BeginSession call. Authorization can take place at run time, through the authorization dialog (as was done in the demonstration), or the QuickBooks administrator can give the application on-going authorization, in which case it will be recognized by QuickBooks and authorized without opening the authorization dialog.
• Applications have the option to specify their authorization preferences in the BeginSession call, particularly whether the application requests access in auto-login (unattended) mode.

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:

• For the first parameter, appId, a null is supplied. This parameter is not currently used.
• For the second, appName, “My Sample App” is supplied. The application name is a string of your choice that will identify your application in interactions with the QuickBooks UI (such as the authorization dialog) and in the QuickBooks log files.
• For the third, connPref, “localQBD” is supplied. This is the type of connection to QuickBooks that the application is requesting.The connection type parameter interacts with the unattended mode authorization preference specified in the BeginSession call, and influences how your application interacts with QuickBooks at run time. This interaction of parameter values is explored below.

The parameters supplied in this snippet for the BeginSession call are also basic values:

• For the first parameter, qbCompanyFileName, which is the full path to the QuickBooks company file the application wants to use, an empty string is supplied. This is interpreted as “use the file that is currently open in QuickBooks.”
• For the second parameter, qbOpenFileMode, 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 unattended privilege can be requested in the authorization preferences, passed in the BeginSession call, and granted by the QuickBooks administrator.
• The unattended privilege can also be granted by the QuickBooks administrator on the authorization dialog or in the QuickBooks UI.

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.

• Generally, if an application attempts to begin a session with a running QuickBooks and there is a mismatch between preferences and authorization privileges, QuickBooks will display the authorization dialog so that the application can be re-authorized.
• Generally, if an application attempts to begin a session with a non-running QuickBooks and there is a mismatch, BeginSession is likely to return an error.

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:

• Certain QuickBooks operations (such as deleting a list item) require that the application access the file in single-user mode.
• Performance; If your application is able to open the company file in single-user mode, it will have exclusive access and lock out other applications, gaining improved performance.

Some circumstances that may make multi-user mode preferable:

• To prevent locking other users out. This would be mainly used on an enterprise company file where multiple users are likely to be accessing a company file simultaneously.

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.

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:

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.

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.

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.

• Flags and preferences are set before the BeginSession call and passed to QuickBooks in the call. Any combination of flags and preferences can be selected.
• Once authorization has been granted, on subsequent calls to BeginSession the application will be recognized and authorized.
• Any changes to the authorization preferences and flags in subsequent calls will result in QuickBooks requesting re-authorization of the application.

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:

• If the application sets authorization preferences for unattended mode, on first access, an authorization dialog with the auto-login prompt will be presented to the administrator for confirmation. Notice that this is “all or nothing.” If the administrator chooses to disallow unattended mode, then your application will not be allowed any access to the QuickBooks company file.
• Alternatively, the administrator can set up auto-login from within QuickBooks (in a dialog that is opened with the following menu sequence: Edit > Preferences > Integrated applications > Company Preferences). If your application needs to run unattended, but doesn’t indicate via the authorization preferences that it requires unattended mode, be sure to tell the QuickBooks administrators, via documentation, that they must give your application the necessary authorizations.
• If your application is set up for auto-login with a specific user, and the administrator attempts to delete that user, QuickBooks will display a warning message explaining that the user account is used by your application.
• If more than one application with auto-login permission accesses QuickBooks, the first auto-login application sets the user and therefore all the privileges for all subsequent applications. In other words, if some application starts QuickBooks in auto-login mode, any other applications authorized for auto-login that subsequently begin sessions will have the same privileges as the first application during that session. The user specified by the first application is the “active” user for all applications until all of the applications have end their sessions and QuickBooks has exited.
• Keep in mind that the behavior of an application that runs in unattended mode is also affected by the value of the connection type parameter supplied to the OpenConnection call. For more information see the section on Connection type parameter.
• Regardless of whether the session specifies single-user mode or multi-user mode, there can be only one auto-login active during that session. In the following example, Joe is designated as an auto-login user on System 4 and no other users can log in automatically until Joe ends his session. (When multiple instances of an integrated application are running on different systems and accessing the same company file, each user must have a different name.)

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:

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:

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.

• If typical user behavior with your application is to work with only one company’s data, the application can probably open a connection, begin a session, process multiple requests, end the session and close the connection.
• If the typical user behavior is working with multiple companies in the way that, for example, a professional accountant who manages finances for multiple companies does, you will need to make it possible for your application to open a connection and then begin and end several sessions, each session working on a different company file, before ending the final session and closing the connection.

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:

• That the current QuickBooks supports the SDK (QuickBooks Version 10 or greater).
• That the version of QuickBooks and the version of the company data file, if one was specified, match one another. (If the call specified NULL or an empty string, this step is skipped.)
• That the file access mode specified in the parameters and the mode in which the company data file is currently open are compatible.
• That 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.
• If the application attempts auto-login/unattended mode (the connection type requested is umptRequiredand 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.