Preparing report requests

Generating reports with the Desktop SDK follows the same request/response model, with qbXML as the message medium, as other SDK-to-QuickBooks interactions. The specific points to consider when working with reports are:

Report request objects name the report being requested; they can also include qbXML tags that specify customizations and filters for the requested report.
Report response detail objects consist of data formatted into rows and columns, which are demarcated with qbXML markup, which your application will iterate over in order to prepare it for display. (See Processing report responses for more information.)

This page concentrates on these aspects of report requests and responses.

As is usual for the desktop SDK, you can write your request messages directly in qbXML or work with QBFC report request objects.

For a general discussion of sending requests, see Preparing and sending requests. For a general discussion of processing responses, see Receiving and processing responses.

Getting started with reports in the SDK

The QuickBooks SDK supports most of the report types, customizations, and filters that can be generated in QuickBooks. The SDK also supports the Custom Summary and Custom Transaction Detail reports, which can be customized and filtered to cover situations for which there is no defined report type. For a complete list of reports supported by the SDK, see Reports that can be requested with the SDK.

Familiarity with the reports in QuickBooks will help you prepare report requests with the SDK. Acquiring familiarity with the following aspects of QuickBooks reporting is recommended:

The defined reports, both summary and detail, that are available in QuickBooks
The business purposes of the defined reports
Which features of the defined reports can be modified

The QuickBooks Report Finder is a useful tool that shows samples of all the defined reports. It allows you to explore the different reports and see which aspects of each report can be modified through customization and filtering.

Because the SDK produces the same reports as the QuickBooks user interface and offers similar modifications, the following methodology is suggested for preparing a report request in the SDK:

In the QuickBooks user interface, select the QuickBooks report that presents the basic type of data you need (for example, the Profit And Loss Standard).
Also in the QuickBooks user interface, modify the report, as needed. For example, you might want to display columns by quarter, and you might want to add subcolumns for the previous period.
Still in the QuickBooks user interface, generate a report and see if it meets the requirements. If not, continue to modify the report until it produces the desired information.
Make a list of the modifications you made to the defined report (fields and values).
Using the API reference, determine which attributes of the SDK request message for the report type you are working on correspond to the user interface controls you used to modify the report. (In our example, you would look at the attributes of the GeneralSummaryReportQueryRq, since the Profit And Loss Standard report is from the General Summary Report category.)
Using either qbXML or a QBFC request object, prepare a report request in the SDK. The request needs to name the defined report and supply information about the modifications you want to make to the report.

Requests for unmodified reports

When an application sends a report request without any modifying customizations or filters, QuickBooks generates the default form of the report. For example, the following request message would generate the default form of the Profit and Loss Standard report:

<QBXML>
    <QBXMLMsgsRq>
        <GeneralSummaryReportQueryRq>
            <GeneralSummaryReportType>ProfitAndLossStandard</GeneralSummaryReportType>
        </GeneralSummaryQueryRq>
    </QBXMLMsgsRq>
</QBXML>

The parameters that QuickBooks uses when it receives a report request message like this are the same that it would use when a user requested the report without modification through the QuickBooks user interface.

NOTE

Different editions of QuickBooks can produce slightly different versions of a report. In the Profit and Loss Standard, for example, the Accountant edition replaces the Amount column with separate Credit and Debit columns. If such differences are a concern, you may want to test the report with different editions of QuickBooks so that your application can handle the differences appropriately. To insulate your application from such differences, specify, in your requests, the columns that are needed by your application using the IncludeColumnelement.

Requests for modified reports

This section uses a common report, the Profit and Loss Standard report, as an example of using the QuickBooks UI to investigate the options available for modifying a specific report that you would like to generate via the SDK.

Matching report modifiers in the UI to report attributes in the SDK

In the QuickBooks UI, the Modify Report: Profit & Loss dialog’s Display tab has the following controls for modifying the report:

In the SDK, this report belongs to the General Summary Report category. The request message for this category, <generalsummaryreportqueryrq,>

The following table shows how the controls on the QuickBooks Modify Report: Profit & Loss dialog match up to attributes listed for the report request message in the API reference and notes the similarities and differences in functionality.

QuickBooks UI control	Equivalent tag in SDK’s request message	Details
Add subcolumns for	IncludeSubcolumns	The SDK provides only a boolean option. In general, False means do not include any subcolumn information. True means include the default subcolumns defined for the report type. Note that if you supply true and the response includes the subcolumns, the application does not have to use and display all of the subcolumn information returned; when processing the response it can take only the data it is interested in.
Display Columns	ReturnColumns	In the QuickBooks user interface, this choice appears when the user clicks Advanced…. The SDK provides the same options as the QuickBooks user interface: all columns, only columns with active information, and only columns with nonzero values.
Display columns by	SummarizeColumnsBy	The SDK provides the same options as the QuickBooks user interface: Day, Month, Year; Employee, Customer, Vendor, PayrollItemDetail, ItemDetail, and ItemType.
Display Rows	ReturnRows	In the QuickBooks user interface, this choice appears when the user clicks Advanced….. The SDK provides the same options as the QuickBooks user interface: only rows with active information, all rows, and only rows with nonzero values.
Report Basis	Report Basis	The SDK provides the same options as the QuickBooks user interface: Cash, Accrual, and None.
Report Date Range	ORReportPeriod	The SDK parallels the QuickBooks user interface and allows you to choose between specifying a date range in the FromReportDate and ToReportDate properties or choosing one of the standard report date ranges using the ReportDateMacro. The enumerated values for the ReportDateMacro field correspond directly to those in the user interface drop-down list: Today, ThisWeek, ThisWeekToDate, and so on.
Reporting Calendar	ReportCalendar	In the QuickBooks user interface, this choice appears when the user clicks Advanced…. The SDK provides the same options as the QuickBooks user interface: fiscal, calendar, and income tax year.

Matching report filters in the UI to report attributes in the SDK

The Modify Report: Profit & Loss dialog also has a Filters tab, which has the following controls for filtering the report data:

The Filters tab has a filter selection list control, that lists Account, Aging, Amount, etc. filters, and the GeneralSummaryReportQuery request has a corresponding set of aggregate attributes named Report*Filter. The filters available in the request are listed in the following table.

QuickBooks UI filter	SDK request equivalent	Use
Account	ReportAccountFilter	Allows you to filter for transactions associated with an account type or a specific account. In the SDK you identify an account type by supplying a value or values from a set of enumerated types; for an account or group of accounts, you supply an ID or FullName.
Customer Type, Vendor Type, etc.	ReportEntityFilter	Allows you to filter for transactions associated with an entity type, such as customer, an employee, or a vendor, or a specific entity. In the SDK you identify an entity type by supplying a value or values from a set of enumerated types; for an specific entity or group of entities, you supply an ID or FullName.
Item	ReportItemFilter	Allows you to filter for transactions associated with an item type, or a specific item. In the SDK you identify an transaction type by supplying a value or values from a set of enumerated types; for an specific entity or group of entities, you supply an ID or FullName.
Class	ReportClassFilter	Allows you to filter for transactions associated with a class that you identify by ID or FullName.
TransactionType	ReportTxnTypeFilter	Allows you to filter for transactions of a specified transaction type, such as check, deposit, estimate, or list of types. In the SDK you supply value or values from a set of enumerated types.
Date	ReportModifiedDateRangeFilter or ReportModifiedDateRangeMacro	Allows you to filter for transactions modified in a date range, that you specify by either from/to dates or a date range macro.
Detail Level	ReportDetailLevelFilter	Allows you to specify the amount of detail to be returned in the report (rdlfAll, rdlfAllExceptSummary, rdlfSummaryOnly).
Posting Statue	ReportPostingStatusFilter	Allows you to filter for transactions of specified posting status (psfEither, rpsfNonPosting, rpsfPosting).

Report filters are very similar, though not identical, to filters that are used in queries. For reports that require either a customer job reference or an account reference, the reference is specified using the appropriate filter.

Preparing the report request

After evaluating the options available in the QuickBooks UI, using them to understand the matching attributes in the SDK’s report request message, and perhaps experimenting with the report options and filters in the QuickBooks UI, you can prepare a request message with the appropriate modifications and filters. The following example is a request for a Profit and Loss Standard report with these modifications and filters:

The report will cover the period This Month to Date
The Columns will be summarized and labeled by Quarter
IncludeSubcolumns is true (for this report, subcolumn information includes Previous Period, Previous Year, and Year- To-Date)
The ActiveOnly values for ReturnRows and Return columns mean that only rows and columns with active information will be included in the response.

<GeneralSummaryReportQueryRq requestID = "928">
    <GeneralSummaryReportType>ProfitAndLossStandard</GeneralSummaryReportType>
    <ReportDateMacro>ThisMonthToDate</ReportDateMacro>
    <SummarizeColumnsBy>Quarter</SummarizeColumnsBy>
    <IncludeSubcolumns>true</IncludeSubcolumns>
    <ReturnRows>ActiveOnly</ReturnRows>
    <ReturnColumns>ActiveOnly</ReturnColumns>
</GeneralSummaryReportQueryRq>

For a list of reports that can be requested from the SDK, see Reports that can be requested with the SDK. For remarks on some report request attributes, see Report request reference and Report datatype reference.