Generate Reports

Overview

Our API provides two primary endpoints for generating reports:

1. Run a Report: /report/run
2. Run a Saved Report: /report/saved/run

Before developing against the API, it may be beneficial to understand how the report builder operates within aXcelerate’s interface. For more information, please refer to our support documentation on Report Builder: https://support.axcelerate.com.au/hc/en-gb/articles/360000368955-Report-Builder

Types of Reports

aXcelerate offers two types of reports:

• Live Reports: These reports provide data as it currently exists in the system, offering you the most up-to-date information.
• Warehoused Reports: These reports contain data from the previous day. They allow for filtering and displaying additional fields created as part of our overnight warehousing aggregation.

Please note that not all reports support both Live and Warehoused options.

To optimise performance, apply appropriate filters when generating reports to focus on data changes since your last report. For example, use a filter with a relevant 'last updated date' field and value. This approach is particularly important for integrations that run the same report on a periodic basis. Configure your systems to only require and request the data that has changed since the last report.

Get a list of reports

All reports (including Live, Warehoused, and saved versions) are based on a foundation of pre-defined reports. You can view these in the aXcelerate interface by navigating to Reports > Report Builder. Alternatively, you can fetch a list of available reports through the API by making a GET request to /report/list.

The response provides an array of reports with details such as name, description, and the references for both warehoused and live data needed for generating the report through the API (reportReference).

To retrieve a list of your saved reports, make a GET request to /report/saved/list. The response will contain an array of saved reports, each including a 'reportId' key, which is necessary for making requests to the /report/saved/run endpoint.

Get a list of available fields

In the aXcelerate interface, you have the ability to customise the fields you want to display in your report. To discover which display fields are available for a report, make a GET request to the /report/fields endpoint, supplying the reportReference parameter with the appropriate value for the desired report. The 'name' key in the response serves as the 'fieldReference' for use in subsequent requests.

Get a list of filter operators for a field

In the aXcelerate interface, you can set up a report to filter results based on one or more filters. If you're familiar with the interface, you'll know that the available input values change depending on the selected field. For example, for a date field, you may need to input one or two date values depending on the chosen operator.

To discover the available operator options for a specific field, make a GET request to the /report/field endpoint, providing the fieldReference parameter with the value from the 'name' key in the /report/fields endpoint response.

The response will include an 'operatorOptions' key containing an array of possible operators (e.g., 'is', 'on', 'between', 'before', 'after', 'startsWith', 'endsWith', 'contains', 'doesNotContain', etc.). Different fields will offer different operator options.

It is important to note that not all fields will be available as filters for a report.

Run a report

After identifying the report you want to run, you can execute it by making a POST request to /report/run. The minimum parameters needed are:

• reportReference
• selectedFilterFields

All reports come with default display fields, but you can use the selectedViewFields parameter to specify additional fields for display. This parameter accepts a comma-separated list of fieldReference values. Refer to the /report/fields endpoint to find the available display field options.

The selectedFilterFields parameter should be an array of stringified JSON objects representing each filter. Here’s an example of a single filter:

[
    {
        "name":"contactsaggregates.contactentrydate",
        "value":"2024-04-01",
        "operator":"after"
    }
]

And for multiple filters:

[
    {
        "name":"contactsaggregates.contactentrydate",
        "value":"2024-04-01",
        "operator":"after"
    },
    {
        "name":"contactsaggregates.surname",
        "value":"Jones",
        "operator":"is"
    }
]

And where a filter requires two values:

[
    {
        "name":"contactsaggregates.contactentrydate",
        "value":"2024-04-01",
        "value2":"2024-04-02",
        "operator":"between"
    }
]

The /report/run endpoint can mimic the /report/saved/run endpoint if you include the reportId parameter and its value. However, we recommend using the /report/saved/run endpoint directly as described below.

Run a saved report

To save a report, you can create one within the aXcelerate interface (refer to the support documentation linked in the Overview section). For more guidance on managing saved reports, visit our help guide for saved reports: https://support.axcelerate.com.au/hc/en-gb/articles/360000390516-Saved-Reports.

Unlike the /report/run endpoint, saved reports have predefined filters that cannot be modified or added to through the API. However, you can override the filter values of a saved report. Any filter provided in the override that doesn't exist in the report will be ignored.

To view the current display fields and filter fields for a specific report, make a GET request to the /report/saved endpoint with a reportId parameter. The response includes an array of display fields under the viewFields key and an array of applied filters under the filterFields key.

To execute a specific saved report at /report/saved/run, the only required parameter is reportId.

To override the applied filter values, use the filterOverride parameter following the same structure as described in the "Run a report" section for selectedFilterFields.

Retrieve records beyond report maximum (pagination)

For warehoused reports, both the /report/run and /report/saved/run endpoints support two additional parameters to help retrieve more records than the report’s default allows:

• displayLength: Controls the number of records returned, accepting values between 10 and 1000.
• offsetRows: Specifies the starting point for records, with a maximum value of 100,000.

Using these parameters, you can paginate through up to 101,000 records. For optimal performance, we strongly recommend applying additional filters to minimise the number of records retrieved.

Report Field ‘consultants.inactive’

When attempting to filter reports using this field, the values are flipped. So consultants.inactive = 1 will mean only active Trainers will be included with the results.

Active Trainers

[{"NAME":"consultants.inactive", "OPERATOR":"IS", "VALUE":"1"}]

Inactive Trainers

[{"NAME":"consultants.inactive", "OPERATOR":"IS", "VALUE":"0"}]