All ACME reports are run asynchronously and results are posted once the server has retrieved all of the data requested in the report. The process for running a predefined report follows these steps:

 

  1. Execute the Report
  2. Poll for Report Instance Status
  3. Retrieve the Results


Execute the Report


Endpoint

Method


Endpoint


Payload


Response


POST

/v2/b2b/async/report

Async Report Object

Async Report Object


Sample Request

The request includes the queryExpression object defined in the report object.  You can retrieve that information using the endpoints described in the Defining Reports document.  If you don’t include this information, the report will return an error.

{

    "reportUuid": "5d9ca7d960309f48c33eec7d",

    "endDate": "2020-1-6",

    "startDate": "2020-1-6",

    "endDateTime": "2020-01-06T23:59:59-0500",

    "startDateTime": "2020-01-06T00:00:00-0500",

    "dateRangeField": "EventStartTime",

    "queryExpression": {

        "collectionName": "Events",

        "findFields": [{

            "fieldName": "EventName",

            "include": true

        }, {

            "fieldName": "EventStartTime",

            "include": true

        }, {

            "fieldName": "EventEndTime",

            "include": true

        }, {

            "fieldName": "Capacity",

            "include": true

        }, {

            "fieldName": "SoldQuantity",

            "include": true

        }, {

            "fieldName": "AvailableQuantity",

            "include": true

        }],

        "limit": 0

    }

}


Sample Response

The response includes the report instance ID that you will use to check the status of the report and retrieve the results.


{

    "id": 1797,

    "tenantId": 165,

    "reportUuid": "5d9ca7d960309f48c33eec7d",

    "status": "Pending",

    "queryExpression": {

        "collectionName": "Events",

        "findFields": [

            {

                "fieldName": "EventName",

                "include": true

            },

            {

                "fieldName": "EventStartTime",

                "include": true

            },

            {

                "fieldName": "EventEndTime",

                "include": true

            },

            {

                "fieldName": "Capacity",

                "include": true

            },

            {

                "fieldName": "SoldQuantity",

                "include": true

            },

            {

                "fieldName": "AvailableQuantity",

                "include": true

            }

        ],

        "limit": 0

    },

    "dateRangeField": "EventStartTime",

    "startDate": "2020-01-06T00:00:00-0500",

    "endDate": "2020-01-06T23:59:59-0500",

    "filterByOwner": false,

    "createdOn": 1578328910782,

    "createdBy": "Jason Barfield",

    "updatedOn": 1578328910782,

    "updatedBy": "Jason Barfield",

    "reportName": "E: Daily Event Overview"

}


Poll for Report Instance Status

Most reports are returned within seconds but larger or more complex reports (see warning above) may take longer to prepare.  After running the report, pass the id from the response object above into the /async/report/{id} url to get the status of the report.

 


 WARNING: When retrieving large amounts of data, we highly recommend “chunking” your requests into smaller date ranges as requests that consume too much server memory will fail.  Generally speaking, these requests include millions of rows or excessive amounts of grouping and summarizing.  If you get an error in your report, narrow your date range and try again.


Endpoint

Method


Endpoint


Payload


Response


GET

/v2/b2b/async/report/{id}

None

Async Report Object


Sample Response


{

    "id": 1797,

    "tenantId": 165,

    "reportUuid": "5d9ca7d960309f48c33eec7d",

    "status": "Completed",

    "queryExpression": {

        "collectionName": "Events",

        "findFields": [

            {

                "fieldName": "EventName",

                "include": true

            },

            {

                "fieldName": "EventStartTime",

                "include": true

            },

            {

                "fieldName": "EventEndTime",

                "include": true

            },

            {

                "fieldName": "Capacity",

                "include": true

            },

            {

                "fieldName": "SoldQuantity",

                "include": true

            },

            {

                "fieldName": "AvailableQuantity",

                "include": true

            }

        ],

        "limit": 0

    },

    "dateRangeField": "EventStartTime",

    "startDate": "2020-01-06T00:00:00-0500",

    "endDate": "2020-01-06T23:59:59-0500",

    "filterByOwner": false,

    "createdOn": 1578328911000,

    "createdBy": "Jason Barfield",

    "updatedOn": 1578328911000,

    "reportName": "E: Daily Event Overview"

}


Retrieve the Results

Once the report’s status is “complete,” you can retrieve the results in either a JSON format or CSV format.


Endpoints

Method


Endpoint


Payload


Response


GET

/v2/b2b/async/report/json/{id}

None

JSON-formatted report results

GET

/v2/b2b/async/report/csv/{id}

None

CSV-formatted report results


Sample Responses

JSON-formatted result response


{

    "collectionName": "Events",

    "recordCount": 0,

    "skippedRecordCount": 0,

    "resultFieldList": [{

        "fieldName": "EventName",

        "analyticsDataType": "STRING",

        "values": ["General Admission", "General Admission", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "Divination Lesson", "Divination Lesson", "Divination Lesson", "Divination Lesson", "House Elf Cooking Lesson", "Transfiguration Lessons", "Transfiguration Lessons", "Transfiguration Lessons", "History of Magic", "History of Magic", "History of Magic"]

    }, {

        "fieldName": "EventStartTime",

        "analyticsDataType": "DATE",

        "values": ["2020-01-06T09:00:00-05:00", "2020-01-06T09:00:00-05:00", "2020-01-06T15:30:00-05:00", "2020-01-06T11:30:00-05:00", "2020-01-06T12:30:00-05:00", "2020-01-06T14:30:00-05:00", "2020-01-06T09:30:00-05:00", "2020-01-06T13:30:00-05:00", "2020-01-06T10:30:00-05:00", "2020-01-06T12:00:00-05:00", "2020-01-06T09:00:00-05:00", "2020-01-06T11:00:00-05:00", "2020-01-06T10:00:00-05:00", "2020-01-06T15:00:00-05:00", "2020-01-06T09:00:00-05:00", "2020-01-06T11:00:00-05:00", "2020-01-06T10:00:00-05:00", "2020-01-06T15:30:00-05:00", "2020-01-06T10:15:00-05:00", "2020-01-06T13:00:00-05:00"]

    }, {

        "fieldName": "EventEndTime",

        "analyticsDataType": "DATE",

        "values": ["2020-01-06T21:00:00-05:00", "2020-01-06T21:00:00-05:00", "2020-01-06T16:30:00-05:00", "2020-01-06T12:30:00-05:00", "2020-01-06T13:30:00-05:00", "2020-01-06T15:30:00-05:00", "2020-01-06T10:30:00-05:00", "2020-01-06T14:30:00-05:00", "2020-01-06T11:30:00-05:00", "2020-01-06T13:00:00-05:00", "2020-01-06T10:00:00-05:00", "2020-01-06T12:00:00-05:00", "2020-01-06T11:00:00-05:00", "2020-01-06T16:00:00-05:00", "2020-01-06T10:00:00-05:00", "2020-01-06T12:00:00-05:00", "2020-01-06T11:00:00-05:00", "2020-01-06T17:30:00-05:00", "2020-01-06T12:15:00-05:00", "2020-01-06T15:00:00-05:00"]

    }, {

        "fieldName": "Capacity",

        "analyticsDataType": "INTEGER",

        "values": [10000, 10000, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 50, 50, 50, 50, 50, 50]

    }, {

        "fieldName": "SoldQuantity",

        "analyticsDataType": "INTEGER",

        "values": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

    }, {

        "fieldName": "AvailableQuantity",

        "analyticsDataType": "INTEGER",

        "values": [10000, 10000, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 45, 50, 50, 50, 50, 50, 50]

    }]

}

 

CSV-formatted result response


EventName,EventStartTime,EventEndTime,Capacity,SoldQuantity,AvailableQuantity

General Admission,2020-01-06T09:00:00-05:00,2020-01-06T21:00:00-05:00,10000,0,10000

General Admission,2020-01-06T09:00:00-05:00,2020-01-06T21:00:00-05:00,10000,0,10000

Transfiguration Lessons,2020-01-06T15:30:00-05:00,2020-01-06T16:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T11:30:00-05:00,2020-01-06T12:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T12:30:00-05:00,2020-01-06T13:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T14:30:00-05:00,2020-01-06T15:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T09:30:00-05:00,2020-01-06T10:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T13:30:00-05:00,2020-01-06T14:30:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T10:30:00-05:00,2020-01-06T11:30:00-05:00,45,0,45

Divination Lesson,2020-01-06T12:00:00-05:00,2020-01-06T13:00:00-05:00,45,0,45

Divination Lesson,2020-01-06T09:00:00-05:00,2020-01-06T10:00:00-05:00,45,0,45

Divination Lesson,2020-01-06T11:00:00-05:00,2020-01-06T12:00:00-05:00,45,0,45

Divination Lesson,2020-01-06T10:00:00-05:00,2020-01-06T11:00:00-05:00,45,0,45

House Elf Cooking Lesson,2020-01-06T15:00:00-05:00,2020-01-06T16:00:00-05:00,45,0,45

Transfiguration Lessons,2020-01-06T09:00:00-05:00,2020-01-06T10:00:00-05:00,50,0,50

Transfiguration Lessons,2020-01-06T11:00:00-05:00,2020-01-06T12:00:00-05:00,50,0,50

Transfiguration Lessons,2020-01-06T10:00:00-05:00,2020-01-06T11:00:00-05:00,50,0,50

History of Magic,2020-01-06T15:30:00-05:00,2020-01-06T17:30:00-05:00,50,0,50

History of Magic,2020-01-06T10:15:00-05:00,2020-01-06T12:15:00-05:00,50,0,50

History of Magic,2020-01-06T13:00:00-05:00,2020-01-06T15:00:00-05:00,50,0,50