Integrating with the QuickBooks UI

Applications can programmatically integrate with the QuickBooks user interface (UI) in three ways:

Both adding a menu item and subscribing to QuickBooks UI events rely on the QuickBooks event subscription and notification mechanism. This means the application must send subscription request messages to QuickBooks and gain authorization from the QuickBooks administrator before QuickBooks will send notifications and make the integration functional. The request can be made and authorization can be granted when the application is installed or as part of its QuickBooks setup. For detailed information about the event subscription and notification mechanism, see Subscribing to events and processing event notifications.

Note

Note

Consider the following limitations:

  • Events are not supported for QuickBooks Simple Start edition.
  • Menu extensions and menu-extension event notification can only be used locally, not remotely. Opening QuickBooks windows, however, will work locally or remotely.
Adding a menu item to QuickBooks

Your application can add one (and only one) menu item to one (and only one) of these top- level QuickBooks menus:

The added menu item can include subitems, but not nested submenus. You can optionally specify display conditions that determine when your menu items will appear (be visible or invisible) and when they will be grayed out (enabled or disabled).

Each QuickBooks menu has a designated location for menu extensions. If your menu item has subitems, you can name these in whatever way is appropriate, but the top-level of a QuickBooks menu extension will always include the application name.

When an end user selects a menu extension (or one of its subitems), QuickBooks will notify the application via the event notification mechanism. At that point, your application might launch itself and display a UI, update certain QuickBooks data, or invoke a QuickBooks window.

UI extensions and UI event notification are “per machine”—that is, UI extensions show up and UI events are sent only on the machine where the application is installed. To make UI event notification and UI extensions available on multiple machines:

The UIExtensionSubscriptionAddRq

To add menu extensions to QuickBooks, an application must send a UIExtensionSubscripAddRq message to QuickBooks, This request message specifies the extension menu item’s name, its subitems, its location, and its behavior for visibility/invisibility–all the options described below. This request can be sent when the application is installed or as part of its QuickBooks setup. For detailed information about preparing an event subscription request and defining the executable that will process the event to QuickBooks, see Subscribing to events and processing event notifications. QuickBooks does not have to be running when the subscription request is sent. After the subscription message has been sent, QuickBooks must be restarted, and the QuickBooks administrator must authorize the requesting application.

A single subscription request applies to all QuickBooks company files on a machine and to all installations of QuickBooks on that machine (except QuickBooks Basic).

Note

Note

If you certify your application, the SDK can verify that a malicious application has not replaced the callback application specified in your subscription requests. For more information, see Digitally signing your code.

Applications with Canadian, UK, and US versions

If you have several versions of your application, for example, one for Canadian, one for UK and one for U.S. editions of QuickBooks, note the following limitations:

The authorization process

After an application sends a UIExtensionSubscriptionAddRq, the requested menu extension is not visible and the QuickBooks UI is not accessible to the application until the QuickBooks administrator authorizes the application. Note that any authorization granted will apply to all types of access via the Desktop SDK–the administrator cannot give an application access to the QuickBooks UI without also giving, for example, access to QuickBooks data,

Note

Note

Authorizations will carry over when the QuickBooks user upgrades to a newer version of QuickBooks. Authorizations will also carry over to installations that are separate from the current installation, for example, if the QuickBooks user puts a QuickBooks upgrade in a different directory or installs a different edition of QuickBooks, such as the Contractor Edition.

The following table shows what will happen in various situations when an end user starts QuickBooks and selects a QuickBooks company file to open after an application has sent a UIExtensionSubscriptionAddRq.

Situation QuickBooks UI behavior
The administrator has not yet authorized the application, as would be the case if the application has just been installed or is being set up. (Also applies if the application was previously authorized but the authorization information has since been removed from the company file.)
  • If the user is the QuickBooks administrator, the authorization dialog will appear. If the administrator authorizes the application, the company file will open and the UI extensions requested by the application will appear.
  • If the user is not the QuickBooks administrator, or if the user is the QuickBooks administrator and chooses not to authorize the application, the company file will open without the requested UI extensions.
The QuickBooks administrator has previously authorized the application. The company file will open with the application’s UI extensions.

An end user opens QuickBooks on a machine where:

  • the application is not installed, or
  • the application did not request the UI subscription, or
  • the administrator has not authorized the application.
The application’s UI extensions will not be available. For example, an accountant with an accountant’s copy of the data file would not see your application’s menu items.

For more information on the authorization dialog and the authorization process, see Connections, sessions and authorizations.

The options available for placing menu extensions, naming them, etc., are covered in the following sections.

Deciding where a menu item should appear

Before choosing the location for a new menu item extension, consider how it will best fit with the existing menu structure and how a user will perceive it when it appears among the other QuickBooks menu items. For example:

In each QuickBooks menu, there is an assigned location for menu extensions. These are listed in the following table:

QuickBooks menu Assigned location for a menu item extension
File Between “Shipping” and “Update QuickBooks”
Company Between “Synchronize Contacts” and “Company Services”
Customers Between “Billing Solutions” and “Check Credit”
Vendors Between “Item List” and “Vendor Services” (as shown below)
Employees Between “Payroll Item List” and “Employer Services”
Banking Between “Memorized Transaction List” and “Banking Services”

For example, the following figure shows where menu extensions are positioned in the QuickBooks Vendors menu.

../../../../_images/Image_273.jpg

Avoid using separators. In QuickBooks, separators divide some of the menus into functional sections. If you have subitems under your main menu item, we recommend that you not include separators, for the following reasons:

Naming menu items

Several elements of the UIExtensionSubscriptionAddRq contribute to the text displayed in the QuickBooks UI.

The way that QuickBooks displays AppName and MenuText depends on several conditions, which are identified in the following table:

Condition AppName and MenuText are displayed like this

Application adds a single menu item, and

AppName + MenuText < 50 characters

Both values are displayed in one menu position:

AppName: MenuText

The colon (:) and the space that follows it are not included in the character count.

Application adds a single menu item, and

AppName* + MenuText > 50 characters

AppName occupies one menu position and MenuText occupies one submenu position:

AppName > MenuText

Application adds a menu item with subitems AppName occupies one menu position and each occurrence of MenuText occupies one submenu position; all submenus are displayed when a user clicks AppName.

MenuText limitations and recommendations:

You can specify positions for the the application’s name to be appear in the menu text by placing the string {AppName} where you want the application name to appear. For example:

If some other application adds a menu item to the same top-level menu as your application, the applications will be listed in alphabetical order according to the first ten letters of the application name. If two application names share the first ten characters, they will be ordered randomly.

Display condition options

Your application can specify the conditions under which it should be visible and enabled, To avoid cluttering an end user’s menu with items that will never be used, try to match display conditions with whatever user Preferences are set. For example, in a QuickBooks data file that had the time-tracking preference turned off, you would not want a submenu item for time- tracking to show up.

Each menu or submenu item has four tags for identifying conditions: VisibleIfList, VisibleIfNotList, EnabledIfList, and EnabledIfNotList. Each of these has a set of enumerated values that can be supplied to specify when the display state identified in the tag name would be applied. For example, if for VisibleIfNotList the application supplies vinIsAccountantCopy, the menu will be visible when the company file is not an accountant’s copy; in other words, it will be invisible if the company file is an accountant’s copy.

When multiple criteria for a state are given, all criteria must be true for the display state to be “on.” For example, if for VisibleIf the application supplies both HasCustomers and HasVendors, the company file would have to have both customers and vendors for the menu item to be visible.

You can combine visible and enabled states.

All combinations are valid, but not all combinations make sense within QuickBooks. For example, you could have a menu item that in some cases is not visible, in other cases is visible but grayed out, and in yet other cases is both visible and enabled. (An item must be visible to be enabled, of course.) So if you use visible and enabled conditions on the same item, you must make sure that both conditions can be true at the same time.

The following enumerated values are available:

Note

Note

A menu item does not change its state based on the states of its subitems. The worst case of this would be if all the subitems ended up not visible. In this case, the menu item would still be visible, but there would be no subitems under it (and therefore it would not have any functionality).

You can avoid this problem by including an always-visible “Learn About” or “Help” link that provides information about the conditions that will make the other menu items visible.

Getting QuickBooks context information from a menu item click

If and application is successfully sends a UIExtensionSubscriptionAddRq, and its menu extensions are displayed, when a user clicks on its menu extension, QuickBooks notifies the application with a QBXMLEvents message. This message has a CurrentWindow element that will contain the name of the QuickBooks form (if any) that was open when the user clicked the menu item.

UI extension error handling

This section describes error-handling situations specific to UI extensions. For information about QuickBooks SDK error handling in general, see Error recovery with the Desktop SDK.

Sometimes QuickBooks end users will not receive a response (or will not realize that they have received a response) after they select your menu item. With careful planning, you can prevent the following three scenarios (each of which is a bad experience for the end user):

  1. Your application window comes up behind the QuickBooks window when the end user selects your menu item.
  2. Your application does something behind the scenes, without informing the end user what’s going on.
  3. The end user uninstalls your application from the machine, but your uninstall process does not unregister its UI extensions, so your menu extensions still show up in QuickBooks. (To unregister itself, your application must send a SubscriptionDelRq request message to QuickBooks. For details about the syntax of this message, see the SubscriptionDel message in the Onscreen Reference.)

The following three scenarios are outside your control, but knowing about them will help you to plan your application’s response:

  1. Someone deletes your application from the machine without uninstalling it.
  2. Someone uninstalls your application while QuickBooks is running, and your application correctly unregisters itself (as described in 3, above). But because QuickBooks has not yet been restarted, your menu items still appear (and can still be selected).
  3. The notification process fails for some other reason (for example, the machine or an application is frozen).

When a QuickBooks user selects a menu extension and there is no response for one of the three reasons listed above, QuickBooks will put up a message box similar to the one shown below:

../../../../_images/Image_281.jpg

A menu click might also fail because your application is still responding to the last menu- click. In this case, the error message shown above would not show up. For more information about what would happen, see Lost UI Events, below.

Lost UI Events

If your application is unable to receive a UI or UI-extension event, the event is lost and cannot be recovered. Your application will not even know that it missed an event.

For example, when a user clicks one of your menu items, subsequent clicks will not send any more notifications until your callback method returns. The user can keep clicking your application’s menu items (the QuickBooks UI does not prevent it by freezing), but nothing will happen. These user menu-clicks are lost. Menu item clicks will also be lost if the callback application is in the process of handling a data event callback.

Lost data events can be detected and recovered. For more information about this, see Subscribing to events and processing event notifications.

Note

Note

Your application should return as quickly as possible, without waiting for UI interaction within your application.

For example, if your application shows a message that the user must dismiss by clicking OK, your application should not wait until OK is clicked before returning from the callback.

Opening QuickBooks windows from an application

An application can open QuickBooks windows for the end user. If QuickBooks is already running, an application can send requests that:

Your application can make these requests either locally or remotely. On the end user’s machine, QuickBooks will return to full size if it was minimized, come to the foreground, and open the windows the application has requested. The requested windows appear within the QuickBooks UI, not within the requesting application.

In general, authorization preferences apply to these requests in the same way they apply to the QuickBooks UI. For example, if user Jeff doesn’t have permission to open an Invoice form in QuickBooks, an application cannot open an Invoice form while Jeff is using QuickBooks.

The TxnDisplayAddRq and TxnDisplayModRq requests

The request messages for opening transaction windows are TxnDisplayAddRq and TxnDisplayModRq:

The transaction forms that can be opened by an these requests are listed below.

* Supports the EntityRef aggregate

Beginning with SDK 4.0, TxnDisplayAddRq has an EntityRef aggregate that can be used to specify a related customer, vendor, employee, or OtherName object. The list of transaction types that support the EntityRef.

The EntityRef aggregate refers to a customer, vendor, employee or OtherName; the aggregate contains either the ListID or the FullName. Notice that the prefilling that is performed is exactly the same as if the end user had typed in a name in that form. That is, the name will appear, but not the rest of the data for that name, for example the address. That will be done automatically in QuickBooks once the end user tabs out of the form, which mirrors the behavior within the QuickBooks UI.

Note

Note

If you supply an entity that is not supported by the transaction, for example, if you specify a vendor name for an invoice form, the SDK does not return any error. Instead, when the user tabs out of the transaction form, QuickBooks will display an error, just as if the user had typed in the invalid name.

If you supply an EntityRef for an unsupported transaction type, an error is returned in the response to the TxnDisplayAdd.

Note

Note

The SalesTaxPaymentCheck form is modal. Therefore, if a sales-tax payment form is already open and your application tries to open another sales-tax payment form, your application will receive an error indicating that QuickBooks is locked in a modal state and cannot be accessed (HRESULT 0x80040414).

In some cases, transaction types share forms, which means that after the application has requested and opened a window, the end user will have to take an extra step to view the right form:

The user can switch to the needed form within the window. For example, the difference between CreditCardCharge and CreditCardCredit is a single radio button that’s either Charge or Credit, the difference between Bill and VendorCredit is a single radio button that’s either Bill or Credit, and the difference between Bill and ItemReceipt is a check box that says “Bill Received.”

The ListDisplayAddRq and ListDisplayModRq requests

The request messages for opening list windows are ListDisplayAddRq and ListDisplayModRq:

The list forms that can be opened by an these requests are listed below.

Sometimes the list window an application requests will not open:

Displaying Reports

To request a report in the SDK and display the report in the QuickBooks Ui, send the report query request with the DisplayReport Boolean value set to true. DisplayReport is false by default.

If you want the request to display the report without returning any data to the application, set the responseData attribute to includeNone,


Displaying the report to the QuickBooks user without having data returned and then processed in the application can cut down significantly on the time needed to process the query.