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 / Edit Report Template

Edit Report Template

Updated on February 12, 2023

Description

This web service updates a specified report template 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 report template must be owned by you.

The following are limitations you should be aware of:
  • The template cannot be updated if the report is already submitted for processing or is being generated.
  • The maximum number of metrics that you are allowed to specify is the same limit that you have in the user interface.
  • A maximum of 2 million data points are allowed in a report (#properties * #metrics * #time periods).

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

PUT

Resource URL

/reports/templates/(templateId)

Header

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

Authorization Required

Yes

Parameters

Parameter Name Description
templateId Id of the report template

XML Schemas

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

Example Request

The following example updates a report template.

PUT  /reports/templates/23441

<?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 Template." 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