Custom Reports

Custom reports based on company information can be created in the Sage Intacct UI and then used to read records.

Overview

Intacct has two types of custom reports:

  • Reports created with the Interactive Custom Report Writer (more modern reports with advanced controls)
  • Reports created with the original custom report writer

You use the readReport function described on this page to get report definitions or to run reports.

In addition, readReport can be used for both interactive and original custom reports:

  • When the type parameter is set to interactive, an interactive report can be specified.
  • When the type parameter is omitted, an original custom report can be specified. Note that an asynchronous callback is available for original custom reports.

After a report is run, a report ID is generated. You then use the readMore function on this ID to page through the results for both types of reports.

To learn about about creating both types of custom reports, see the usage information for custom reports in the Sage Intacct product help.

About Asynchronous Results for Original Custom Reports

If you want results to be sent automatically when available instead of having to poll for results with readMore, you can set up asynchronous processing. With this approach, the readReport call initiates a secondary process to automatically send the response to your handler.

Your Web Services sender ID must have an asynchronous policy transport ID and a URL with your result handler (see Asynchronous responses).

Your asynchronous response can include the first batch of results along with the status message, or only the status message. In addition, you can provide your own unique ID for the results or use an automatically generated one.

Get the Definition of an Interactive Custom Report

Return an interactive custom report definition in a company:

readReport

<readReport type="interactive" returnDef="true">
    <report>VendorPayments</report>
</readReport>

Parameters

Name Required Type Description
type (attribute) Required string Custom report type. Use interactive.
returnDef (attribute) Required boolean Return the definition. Use true
report Required string Name of the interactive custom report definition to get

Response

report_definition

The above function returns both user-defined and system-defined arguments:

<report_definition>
    <REPORTNAME>VendorPayments</REPORTNAME>
    <REPORTTYPE>CRW</REPORTTYPE>
    <OBJECT>AP_DETAIL</OBJECT>
    <DOCPARID></DOCPARID>
    <COLUMNS>
        <COLUMN>
            <PATH>AMOUNT</PATH>
            <FULLPATH>AP_DETAIL.AMOUNT</FULLPATH>
            <LABEL>Base amount</LABEL>
        </COLUMN>
        <COLUMN>
            <PATH>RECORDTYPE</PATH>
            <FULLPATH>AP_DETAIL.RECORDTYPE</FULLPATH>
            <LABEL>Record type</LABEL>
        </COLUMN>
        <COLUMN>
            <PATH>WHENCREATED</PATH>
            <FULLPATH>AP_RECORD.WHENCREATED</FULLPATH>
            <LABEL>Date</LABEL>
        </COLUMN>
        <COLUMN>
            <PATH>VENDORNAME</PATH>
            <FULLPATH>AP_RECORD.VENDORNAME</FULLPATH>
            <LABEL>Vendor name</LABEL>
        </COLUMN>
    </COLUMNS>
    <ARGUMENTS>
        <ARGUMENT>
            <NAME>AP_RECORD.WHENCREATED</NAME>
            <LABEL>Date</LABEL>
        </ARGUMENT>
    </ARGUMENTS>
</report_definition>

Parameters

Name Type Description
REPORTNAME string Report name defined during creation of the report.
REPORTTYPE string Report type is CRW
OBJECT string Object the report is set for.
DOCPARID string Document type if relevant
COLUMNS array of COLUMN Columns used in the report.
ARGUMENTS array of ARGUMENT Input prompts for the report.

COLUMN

Name Type Description
PATH string Simple name of the parameter
FULLPATH string Name of the parameter
LABEL string Column heading

ARGUMENT

Name Type Description
NAME string Name of the parameter
LABEL string Label of the parameter

Get the Definition of an Original Custom Report

Return an original custom report definition in a company:

readReport

<readReport returnDef="true">
    <report>TestBill2</report>
</readReport>

Parameters

Name Required Type Description
returnDef (attribute) Required boolean Use true
report Required string Name of the custom report definition to get

Response

report_definition

The above function returns both user-defined and system-defined arguments:

<report_definition>
    <REPORTNAME>TestBill2</REPORTNAME>
    <REPORTTYPE>tabular</REPORTTYPE>
    <OBJECT>APBILLITEM</OBJECT>
    <DOCPARID></DOCPARID>
    <PARAMETERS>
        <PARAMETER>
            <NAME>APBILLITEM.APBILL.VENDORID</NAME>
            <label>Vendor ID</label>
            <promptOnRun>1</promptOnRun>
        </PARAMETER>
        <PARAMETER>
            <NAME>PERIOD</NAME>
        </PARAMETER>
    </PARAMETERS>
    <SORTBY>
        <APBILLITEM.APBILL.VENDORNAME>
            <dir>asc</dir>
        </APBILLITEM.APBILL.VENDORNAME>
    </SORTBY>
</report_definition>

Parameters

Name Type Description
REPORTNAME string Report name defined during creation of the report.
REPORTTYPE string Report type, either tabular or summary
OBJECT string Object the report is set for
DOCPARID string Document type if relevant
PARAMETERS PARAMETER[0...n] Run-time parameters of the report, including both user-defined and system-defined parameters.

PARAMETER

Name Type Description
NAME string Name of the parameter. Returned for both user-defined and system-defined parameters.
label string Given label of the parameter. Return for only user-defined parameters.
promptOnRun boolean Whether the parameter was defined as one that needs prompting from the user when the report is run from the UI.

Run an Interactive Custom Report

readReport

Run an interactive custom report created with vendor payments on a given day:

<readReport type="interactive">
    <report>VendorPayments</report>
    <waitTime>0</waitTime>
    <arguments>
        <AP_RECORD.WHENCREATED>06/19/2018</AP_RECORD.WHENCREATED>
    </arguments>
</readReport>

Parameters

Name Required Type Description
type (attribute) Required string Custom report type. Use interactive.
report Required string The name of the custom report to run
waitTime Optional integer Set a custom wait time between 0 and 30 seconds (Default: 0)
pagesize Optional integer Custom page size between 1 and 1000 items (Default: 100)
arguments Optional XMLElement[] Each argument is specified by its name (as defined in the report definition) and includes the value to be substituted into the report argument. Report arguments are defined in the report in one of two ways. Some report arguments are hard-coded in the definition of the report. Other report arguments are defined as run-time parameters and are selected by the user when running the report.

For reports that define a PERIOD parameter (as returned in the report definition), both system reporting periods and user-defined reporting periods names may be used in the parameter.

Response

reportId

The system returns a unique report ID that you can use to retrieve the report, and the status of the report:

<report_results>
  <REPORTID>YT_jBmIqoVXBFGLNjSVwIPCIIuJa9IKKqQ_Fq9T8PSbonJrnXZl1a2gO0dcby349</REPORTID>
  <STATUS>PENDING</STATUS>
</report_results>

Parameters

Name Type Description
reportId string Report ID to use in readMore requests to retrieve the report.

Run an Original Custom Report

Release Changes
2021 Release 1 Added showStatusOnly
2020 Release 4 Added reportId

This function is intended to allow developers to design a dataset and not to perform grouping and summary operations. If you need to group or summarize your data, you will need to do that in your own code on the data returned from the report. In short, only run readReport on tabular reports where grouping is not set.

readReport

Run an original custom report with Date Range Arguments:

<readReport>
    <report>TestBill Date Runtime</report>
    <waitTime>0</waitTime>
    <arguments>
        <APBILL.TEST_DATE>
            <FROM_DATE>1/1/2014</FROM_DATE>
            <TO_DATE>12/31/2016</TO_DATE>
        </APBILL.TEST_DATE>
    </arguments>
</readReport>

Run an original custom report with Reporting Period Argument:

<readReport>
    <report>Employee Time by Project</report>
    <arguments>
        <REPORTINGPERIOD>Current Year</REPORTINGPERIOD>
    </arguments>
    <waitTime>30</waitTime>
</readReport>

Run an original custom report for getting asynchronous results and store results with the given report ID:

<readReport>
    <report>Employee Time by Project</report>
    <arguments>
        <REPORTINGPERIOD>Current Year</REPORTINGPERIOD>
    </arguments>
    <reportId>empTimeByProject20200626NO001</reportId>
</readReport>

Parameters

Name Required Type Description
report Required string Name of the custom report to run
waitTime Optional integer Set a custom wait time between 0 and 30 seconds (Default: 0)
pagesize Optional integer Custom page size between 1 and 1000 items (Default: 100 for synchronous calls, 1000 for asynchronous calls)
arguments Optional XMLElement[] Each argument is specified by its name (as defined in the report definition) and includes the value to be substituted into the report argument. Report arguments are defined in the report in one of two ways. Some report arguments are hard-coded in the definition of the report. Other report arguments are defined as run-time parameters and are selected by the user when running the report.
reportId Optional string Your own unique ID for the custom report results. Only applicable when using asynchronous results. (Default: automatically generated ID)
showStatusOnly Optional boolean Flag for specifying whether the first batch of results should be sent along with the status when using asynchronous results. Use true to send only the status information. (Default: false)

For reports that define a PERIOD parameter (as returned in the report definition), both system reporting periods and user-defined reporting periods names may be used in the parameter.

Response

reportId

The system returns a unique report ID that you can use to retrieve the report, and the status of the report. For example, a system-generated ID might look like this:

<report_results>
  <REPORTID>YT_jBmIqoVXBFGLNjSVwIPCIIuJa9IKKqQ_Fq9T8PSbonJrnXZl1a2gO0dcby349</REPORTID>
  <STATUS>PENDING</STATUS>
</report_results>

Parameters

Name Type Description
reportId string Report ID to use in readMore requests to retrieve the report.

Get a Report

You use the reportId in a readReport response to retrieve the status of a report and the report itself.

Request a report:

<readMore>
    <reportId>k267Hj5x93gGrmQ12I4n6z457f83bZh3</reportId>
</readMore>

readMore

Parameters

Name Required Type Description
reportId Required string Report ID from a readReport response.

If the STATUS in the response is PENDING, wait a little while and then send the request again. When the report is ready, the first page will be returned in the response.

Note the numremaining attribute of the data element in the response. If the value is not 0, there is more data to retrieve and you should send another readMore request.

<data listtype="report" count="5" totalcount="26" numremaining="21">

When you retrieve the last page of a report, the system deletes the entire report. To get the report a second time, you must send the original readReport request again to generate a new report ID.

Provide feedback