Web Service Documentation / Categories / Reporting Services / Custom Reporting API Guide

Custom Reporting API Guide

How the APIs are organized

The Custom Reports APIs are organized around two important components that you should be familiar with:

• Template
• Report

These 2 components when combined together form a Custom Report which allows you to interface with the Custom Reporting feature within the Portfolio Manager user interface.

Template

A template is the primary component. It consists of a name (i.e., My Energy Report for 2022) and a set of metrics. The unique identifier to this component will be referred to as the templateId. You interface with a template when you perform any of the following actions on a custom report:

• update the name
• update the set of metrics

Report

A report is the secondary component -- it cannot exist without a corresponding template. A report consists of a timeframe (i.e., specific period ending date, date range, etc.) and a set of properties. The unique identifier to this component will be referred to as the reportId. You interface with a report when you perform any of the following actions on a custom report:

• update the reporting timeframe
• update the set of properties
• generate the report
• check the report's status
• download the report results

Quick Reference Guide

Below is a quick reference guide to common custom reporting functionality.

Creating and Generating a New Custom Report

Step	Method	REST URI	Description
1.	GET	/reports/metrics?groupIds=(groupIds)	Get a current list of available metrics to report on. This step can be skipped if you already know the list of metrics that you want to include in your report template.
2.	POST	/reports/templates	Create a report template by providing a name and set of metrics. A templateId and reportId are returned.
3.	PUT	/reports/(reportId)	Specify a reporting timeframe and set of properties using the reportId returned in the previous call.
4.	POST	/reports/(reportId)/generate	Generate the report using the reportId.
5.	GET	/reports/(reportId)/status	Check the report's status using the reportId until the report is finished generating.
6.	GET	/reports/(reportId)/download?type=(type)	Download the report results (if the report is finished generating) using the reportId. The report is streamed as a file. An Excel or XML file is streamed back and is not part of the XML response body.

Updating the List of Metrics in an Existing Custom Report

Step	Method	REST URI	Description
1.	GET	/reports/(reportId)	Get the templateId (if not known already) by retrieving the corresponding report component using the reportId.
2.	PUT	/reports/templates/(templateId)	Update the report template with a set of metrics using the templateId.
3.	POST	/reports/(reportId)/generate	Generate the report using the reportId.
4.	GET	/reports/(reportId)/status	Check the report's status using the reportId until the report is finished generating.
5.	GET	/reports/(reportId)/download?type=(type)	Download the report results (if the report is finished generating) using the reportId. The report is streamed as a file. An Excel or XML file is streamed back and is not part of the XML response body.

Updating the List of Properties and Timeframe in an Existing Custom Report

Step	Method	REST URI	Description
1.	GET	/reports/templates/(templateId)	Get the reportId (if not known already) by retrieving the corresponding template component using the templateId.
2.	PUT	/reports/(reportId)	Update the report with a list of properties and timeframe using the reportId.
3.	POST	/reports/(reportId)/generate	Generate the report using the reportId.
4.	GET	/reports/(reportId)/status	Check the report's status using the reportId until the report is finished generating.
5.	GET	/reports/(reportId)/download?type=(type)	Download the report results (if the report is finished generating) using the reportId. The report is streamed as a file. An Excel or XML file is streamed back and is not part of the XML response body.