Integrating with the QuickBooks UI

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

• Adding a menu item with subitems – applications can add a single menu item, with optional subitems, to a top-level QuickBooks menu. The menu item is added and described via an event subscription request, and when an end user selects one of an application’s menu items, the application is receives an event notification. The application has some control over when these menu extensions are visible and enabled. Starting with SDK 4.0, the event notification provides context data, meaning that it identifies which QuickBooks form was open when a user clicked the menu item.
• Subscribing to QuickBooks UI events – applications can subscribe to QuickBooks UI events, such as the opening or closing of a company file and receive notification when the events take place.
• Opening QuickBooks windows – applications can open certain QuickBooks transaction windows, list windows, and reports to present them to the end user. Starting with SDK 4.0, applications can also prefill certain transaction creation forms with customer, vendor, employee, or OtherName data.

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.

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

• File menu
• Company menu
• Customers menu
• Vendors menu
• Employees menu
• Banking menu

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 application must be installed on each machine
• The QuickBooks administrator must grant access on each machine, for each data file.

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).

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:

• It is possible that a user who selects your UI extension from within a Canadian or UK edition of QuickBooks will be taken to the US version of your application, and vice versa. You cannot create a subscription on one machine such that a UI item added to U.S. editions of QuickBooks will invoke the U.S. version of your application while that same UI item in Canadian editions of QuickBooks will invoke the Canadian version of your application. Instead, each version of the application will overwrite any existing subscription, so that the last one installed “wins.”
• If you have a U.S.-only application, you cannot prevent your UI items from showing up in Canadian or UK editions of QuickBooks. Conversely, if you have a Canada or UK- only application, you cannot have a UI item that only shows up in Canadian or UK editions of QuickBooks. UI extensions show up in all editions of QuickBooks.

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,

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.

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:

• File menu commands move data into or out of QuickBooks, interact with external files, and operate on a company file in its entirety. If your application, for example, imports and exports data to and from QuickBooks, your menu extension would fit well under the File menu.
• The Company, Customers, Vendors, Employees, and Banking menus correspond to the activities and information shown in the QuickBooks Navigators. If your application, for example, manages sales tax or inventory, your menu extension would fit well under the Vendors menu.

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.

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:

• In QuickBooks, a separator shows as a single line that spans the width of the menu. The SDK does not support the creation of separators that would look like this, because a MenuText element cannot include HTML or graphics.
• QuickBooks separators are impossible to select, whereas a user could select whatever characters you used to create your separator. If you can’t organize your submenu without creating a separator, we recommend that you follow these guidelines:
• Nothing should happen if an end user selects your separator.
• Avoid using words in a separator.
• If separators don’t make it easier for users to find what they’re looking for, consider leaving them out.

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

• AppName – this is a string that identifies the application in the authorization dialog and in the QuickBooks menus. The AppName has a maximum of 128 characters, and the value supplied in the UIExtensionSubscriptionAddRq should match the AppName supplied in the connection request. (For more information on the connection request, see Connections, sessions and authorizations.)
• The primary MenuText – this is a string that appears when the designated QuickBooks menu is opened. In the UIExtensionSubscriptionAddRq message, this is the MenuText that appears under ORMenuSubmenu > MenuItem.
• The submenu MenuTexts – these are optional strings; if defined, they are displayed when a user clicks the application’s primary menu item.

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:

• MenuText can have up to 50 characters, it can use special characters
• MenuText occurrences cannot have keyboard shortcuts or access keys (mnemonics) set for them, they cannot have functional check boxes, radio buttons, or other graphics next to them
• Menu-item names should be as short as possible.
• Try to begin the name of any subitems with a verb. For example:
  • Launch Invoice Manager
  • Show Invoice List
• If a menu item opens a dialog box or form within your application, it’s a good idea to have the QuickBooks menu-item name match the resulting window title or the title of the front pane or tab.
• Using an ellipsis (…) after a menu-item name lets users know that they will have to complete some extra step before the command is carried out.
• If choosing a menu item will result in the machine attempting to connect to the Internet, it’s a good idea to name the item in a way that makes that clear. (For example, if selecting help will connect the user to your web site, you might name that subitem “View Online Help” rather than just “View Help.”)

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:

• Some text {AppName}
• {AppName} some text
• Some text {AppName} more text
• {AppName} (if all you want to show is the application name

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.

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:

• HasCustomers (Are there any customers, active or inactive, in the company file?)
• HasVendors (Are there any vendors, active or inactive, in the data file?)
• MultiUserMode (Is this company file open in multi-user mode?)
• AccountantCopyExists (Has an accountant’s copy been created for this company file?)
• IsAccountantCopy (Is this company file the accountant’s copy?)
• InventoryEnabled, ClassesEnabled, PriceLevelsEnabled , EstimatesEnabled, SalesTaxEnabled, TimeTrackingEnabled, PayrollEnabled (Does this company file use the inventory, classes, price levels, and other listed features? The end user enables or disables these features in the Preferences dialog box.)
• SalesOrdersEnabled, AssemblyItemsEnabled (Does this data file use sales orders? Assembly items? If this is a Premier or Enterprise edition of QuickBooks, the end user enables or disables these features in the Preferences dialog box. If it is a Pro edition of QuickBooks, sales orders and assembly items are not available.)

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.

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.

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:

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.

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.

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

• Launch transaction form. It can be blank, allowing the QuickBooks user to create a new transaction, or filled with an existing transaction, allowing the user to edit it.
• Launch a list window. It can be blank, allowing the QuickBooks user to create a new list object, or filled with an existing object, allowing the user to edit it.
• Display any of the reports that can be queried through the SDK.

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 request messages for opening transaction windows are TxnDisplayAddRq and TxnDisplayModRq:

• TxnDisplayAddRq opens a blank form. Beginning with SDK 4.0, a number of transaction windows can be launched prefilled with customer, vendor, employee, or OtherName data.
• TxnDisplayModRq opens a form displaying an existing transaction, which the user can modify.

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

• Bill*
• Bill payment
• BuildAssembly*
• Charge
• Check*
• Credit card charge*
• Credit card credit*
• Credit memo*
• Deposit*
• Estimate*
• Inventory adjustment
• Invoice*
• Item receipt*
• Journal entry
• Purchase order*
• Receive payment*
• Sales order*
• Sales receipt*
• Sales tax payment check
• Vendor credit*

* 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.

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

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:

• CreditCardCharge and CreditCardCredit use the same form. If a CreditCardCharge form is open and the application sends an a request to open a new CreditCard Credit form, QuickBooks will open a new CreditCardCharge form instead. Similarly, if a CreditCardCredit form is open, invoking a new CreditCardCharge brings up a new CreditCardCredit form.
• ItemReceipt, Bill, and VendorCredit use the same form. So, for example, if a Bill form is open and the application sends an add request to open a new ItemReceipt form, QuickBooks will open a new Bill form instead.

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 request messages for opening list windows are ListDisplayAddRq and ListDisplayModRq:

• ListDisplayAddRq opens a blank form.
• ListDisplayModRq opens a form displaying an existing list object, which the user can modify.

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

• Account
• Customer
• Employee
• Item
• Other Name
• Vendor

Sometimes the list window an application requests will not open:

• Job and Customer use the same form, so if the user is viewing the Edit Job form when your application invokes a new Customer form, the New Job form will open instead. It is not possible to show a New Customer form if a Job form is already open. However, if the user is viewing the Edit Customer form when you invoke a new Customer, a new (blank) Customer form will open.

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.