Purpose: Orion has three primary types of report, standard or “canned” reports, legacy report builder reports, and report builder reports. Standard reports are pre-created by Orion for all advisors, while both legacy and new report builder reports are created by the advisors for themselves. The first two types use the same process to run through the API, but for the new report builder requests, due to the complexity of that technology, there is a different process.
Simple Use Case: Advisor wants to generate a specific report for a Client to review or to help answer some of their questions. Rather than run this through Orion’s reporting Apps, this will instead be ran through the API into the firm’s custom Advisor Portal and associate to that Client’s report vault.
For any of our reporting options we make these reports available for their use whenever needed. If a client calls and the advisor needs to review the data for a client, they can easily pull up and run their report to get the client the information they need.
Scope and Outputs: Running a standay/canned or legacy report will allow you to easily produce a detailed output for the requested data, but with this option we are not able to run the report to your screen, or HTML format. With the new report builder we are able to run to either option depending on need.
Process Overview:
Standard and Legacy Report Builder Reports
- Get a list of Reports and collect the Report ID
- Get the report details including parameters
- Choose and execute method to generate and retrieve a report
- Run and wait for data
- Run and poll for data when available
New Report Builder Reports
- Get a list of New Report Builder Reports and collect the Report ID
- Get the report details including parameters
- Generate Report
- Get a list of Report Inbox reports
- Download Report from Report Inbox
Standard and Legacy Report Builder Process Steps:
- GET a list of available reports and identify the Report ID for the report that the user wants to run.
- GET the details about the report, including the parameters (returned in the “unstorable” collection).
GET v1/Reporting/Reports/{reportId}/Parameters
NOTE: The parameters must have the values filled in to establish what entity (client, registration, account, etc) and timeframe the report is being run for. The collection of parameters can vary from report to report. If default parameters have been set using the user interface from Orion Connect, these default parameters with automatically be used when generating the report via API.
- There are two common methods for generating and receiving the report data: a) run the report and wait until the report response or b) run the report and poll for when the results are available.
Method A – Run report and wait until the report response
NOTE: While this method is simpler, a report may take a long time to generate based on the complexity and length of the report and the size of the household with the number of accounts. The timeout for the Generate API endpoint is set to 40 minutes. If your environment does not all API connections to be open that long, you should use the other method.
POST the return from step 2 with the completed parameters to v1/Reporting/Reports/{Report ID}/Generate
When this call complete, one of two things will happen:
- If it was successful there will be a location header. When you GET from the location header, it will download the generated PDF.
- If it was unsuccessful there will be a notification sent to the user’s report inbox with information about the problem, including an error code that can be ushered to investigate the problem. This message can be retrieved via the Report Inbox in Orion Connect or with GET v1/Reporting/ReportInbox
Method B – Run report and then poll to determine when the report is available.
POST the return from step 2 with the completed parameters, and set the “runTo” property as follows: “runTo”:
"runTo":{
"storageType":"ReportInbox",
"provider":"Self",
"combinationMethod":"None"
}
POST that object to to v1/Reporting/Reports/{Report ID}/Generate
This will return a response very quickly and include a location header that can be used to poll the status: GET v1/Reporting/Reports/{Report ID}/Generate/{guid}/Status
When running a single report that endpoint will initially return:
{
"status": "Pending Generation",
"reports": [],
"totalReports": 1
}
When the report is complete it will change to be similar to:
{
"status": "Generated",
"reports": [
{
"runFor": {
"entityId": {entityId},
"entity": {entityLevel}
},
"status": "Generated",
"location": ".../v1/Reporting/ReportInbox/{inboxId}/Download"
}
],
"totalReports": 1
}
The location property in the report object can be then used to GET the pdf. Reports run to the user’s report inbox will be available for 4 days.
New Report Builder Process Steps:
- GET a list of available reports and identify the Report ID for the report that the user wants to run.
GET v1/Reporting/Envision/Reports
[
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "string",
"description": "string",
"versionOfReportId": "00000000-0000-0000-0000-000000000000",
"canEdit": true,
"canDelete": true,
"auditedBy": "string",
"auditedDate": "2020-11-18T22:17:37.693Z",
"createdBy": "string",
"createdDate": "2020-11-18T22:17:37.693Z"
}
]
- Get the report details including parameters
GET v1/Reportring/Reports/{reportId}/Parameters
NOTE: The parameters must have the values filled in to establish what entity (client, registration, account, etc) and timeframe the report is being run for. The collection of parameters can vary from report to report. If default parameters have been set using the user interface from Orion Connect, these default parameters with automatically be used when generating the report via API.
{
"id": "00000000-0000-0000-0000-000000000000",
"requiredOptions": [{
"id": "entity",
"$type": "select-entity",
"entity": "Household",
"options": ["Household", "Registration", "Account"],
"optionId": null,
"prompt": "Always"
}, {
"id": "daterange 0",
"$type": "daterange",
"start": {
"date": "2020-11-01",
"expression": "/m",
"dateSource": "Dynamic"
},
"end": {
"date": "2020-11-18",
"expression": "0d",
"dateSource": "Dynamic"
},
"name": "Period",
"dataMustExistOnRangeStartDate": false,
"dataMustExistOnRangeEndDate": false,
"allowStartDateAdjustment": true,
"startDateMethod": "Inception",
"optionId": 0,
"prompt": "Always"
}
],
"additionalOptions": null,
"deliveryOptions": [{
"id": "delivery-method",
"$type": "delivery-method",
"options": [{
"storageType": "DirectDownload",
"displayName": "Direct Download",
"provider": null
}, {
"storageType": "ReportInbox",
"displayName": "Report Inbox: currentusername",
"provider": "0"
}, {
"storageType": "ReportInbox",
"displayName": "Report Inbox: Selected Inbox",
"provider": "3"
}
],
"storageType": "DirectDownload",
"provider": null,
"folderPath": null,
"userIdList": null,
"reportFormat": "Html",
"combinationMethod": "Aggregate",
"archiveReport": false,
"optionId": null
}
],
"hasAdditionalOptions": true,
"reportName": "Asset Category",
"reportDescription": "Report Description",
"parentCategory": "Portfolio",
"category": "Custom Reports",
"runAssignedVersion": false
} - POST the updated parameters to the generate endpoint. Make sure to add the entity IDs to the entity option and update the start and end date.
POST v1/Reporting/Reports/{Report ID}/Generate
{
"id": "00000000-0000-0000-0000-000000000000",
"requiredOptions": [{
"id": "entity",
"$type": "select-entity",
"entity": "Household",
"options": ["Household", "Registration", "Account"],
"optionId": null,
"prompt": "Always",
"entityIds": [11111]
}, {
"id": "daterange 0",
"$type": "daterange",
"start": {
"date": "1/1/2020",
"expression": "/m",
"dateSource": "Static"
},
"end": {
"date": "12/31/2020",
"expression": "0d",
"dateSource": "Static"
},
"name": "Period",
"dataMustExistOnRangeStartDate": false,
"dataMustExistOnRangeEndDate": false,
"allowStartDateAdjustment": true,
"startDateMethod": "Inception",
"optionId": 0,
"prompt": "Always"
}
],
"additionalOptions": null,
"deliveryOptions": [{
"id": "delivery-method",
"$type": "delivery-method",
"options": [{
"storageType": "DirectDownload",
"displayName": "Direct Download",
"provider": null
}, {
"storageType": "ReportInbox",
"displayName": "Report Inbox: currentusername",
"provider": "0"
}, {
"storageType": "ReportInbox",
"displayName": "Report Inbox: Selected Inbox",
"provider": "3"
}
],
"storageType": "DirectDownload",
"provider": null,
"folderPath": null,
"userIdList": null,
"reportFormat": "Html",
"combinationMethod": "Aggregate",
"archiveReport": false,
"optionId": null
}
],
"hasAdditionalOptions": true,
"reportName": "Asset Category",
"reportDescription": "Report Description",
"parentCategory": "Portfolio",
"category": "Custom Reports",
"runAssignedVersion": false
}
- Get a list of reports in the user’s report inbox.
[
{
"id": 0,
"openWith": "string",
"fileName": "string",
"createdDate": "2020-11-23T17:35:15.103Z",
"createdBy": "string",
"editedBy": "string",
"editedDate": "2020-11-23T17:35:15.103Z",
"description": "string"
}
]
- Download report from user’s report inbox by specifying the Report ID from the previous request