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

You can use the functions on this page to get and run both supported 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

The readReport function on this page has two uses:

  • When the returnDef parameter is set to true, the report definition is returned.
  • When the returnDef parameter is set to false or excluded, the report is run and data is generated.

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 specified.
  • When the type parameter is omitted, an original custom report can be specified.

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.


Get Interactive Custom Report Definition

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 Required string Custom report type. Use interactive.
returnDef 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 COLUMN[0...n] Columns used in the report.
ARGUMENTS ARGUMENT[0...n] 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 Original Custom Report Definition

Return an original custom report definition in a company:

readReport

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

Parameters

Name Required Type Description
returnDef 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 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 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

To eliminate conflicts on overlapping requests, the system returns report IDs on your initial request:

<reportId>k267Hj5x93gGrmQ12I4n6z457f83bZh3</reportId>

Parameters

Name Type Description
reportId string Stored report ID to use in subsequent readMore requests.

Run Original Custom Report

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>

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

To eliminate conflicts on overlapping requests, the system returns report IDs on your initial request:

<reportId>k267Hj5x93gGrmQ12I4n6z457f83bZh3</reportId>

Parameters

Name Type Description
reportId string Stored report ID to use in subsequent readMore requests.

List Stored Report Data

List report data for an interactive or original report:

readMore

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

When you reach the end of the report, the report ID no longer works. You need to initiate a new readReport request again to generate a new report ID. Think of it as if the system is running your report, giving that instance an ID, and then holding it in queue for you to read with the readMore method. After you finish reading it, the system purges it from the queue.

Parameters

Name Required Type Description
reportId Required string Report ID of the stored custom report

Provide feedback