announcement

During the current lapse in appropriations, EPA intends to keep the ENERGY STAR website, tools, and resources available, however they will not be updated regularly. Many services may not be available during this time.

Web Service Documentation / Categories / Reporting Services / Add Report Template

Add Report Template

Updated on February 12, 2023

Description

This web service creates a report template in your account based on the template name and set of metrics provided in the XML request. This web service returns the unique identifier to the report template and a link to the corresponding web service to retrieve it. In addition, a unique identifier to the corresponding report and link to the web service to retrieve it are also returned.

The following are limitations you should be aware of:
  • The maximum number of metrics that you are allowed to specify is the same limit that you have in the user interface.

The list of metrics are specified by their unique identifiers and will be configured in the report template based on the order provided in the XML request with the exception of the 4 metrics listed below. The 4 metrics listed below are always included as the first 4 metrics in the report template even if they are not explicitly specified.
  • Property Id (id 448)
  • Property Name (id 443)
  • Parent Property Id (id 449)
  • Parent Property Name (id 1301)

Version

25.0

HTTP Method

POST

Resource URL

/reports/templates

Header

Field Name Value Comments
Authorization Basic credentials
Content-Type application/xml

Authorization Required

Yes

Parameters

None

XML Schemas

Request/Response Schema Name
Request reportTemplate.xsd
Response response.xsd

Example Request

The following example adds a report template.

POST  /reports/templates

<?xml version="1.0" encoding="UTF-8"?>
<reportTemplate>
     <name>Energy Report 2022</name>
     <metrics>
          <id>448</id>
          <id>443</id>
          <id>449</id>
          <id>1301</id>
          <id>1264</id>
          <id>1265</id>
     </metrics>
</reportTemplate>

Example Responses

The following example shows the results when you call this web service.

<?xml version="1.0" encoding="UTF-8"?>
<response status="Ok">
     <links>
          <link id="23441" httpMethod="GET" link="/reports/template/23441" linkDescription="This is the GET url for this Template." hint="Energy Report 2022"/>
          <link id="2345" httpMethod="GET" link="/reports/2345" linkDescription="This is the GET url for this Report." hint="Energy Report 2022"/>
     </links>
</response>

The following example shows the results when you call this web service and attempt to specify more than the allowed number of metrics.

<?xml version="1.0" encoding="UTF-8"?>
<response status="Error">
     <errors>
          <error errorNumber="-200" errorDescription="A maximum of 50 metrics is allowed."/>
     </errors>
</response>
TEST