Skip to content

Implementing Reporting with the default plugin

This guide will explain the ways to register and provide OpenADR reports using the default plugin.

If you are not yet familiar with reporting in OpenADR, please refer to the OADR reporting overview and the OpenADR specification, section 8.

Using the plugin, the user simply needs to provide Plaid the information to register reports (i.e. describe what reports it has to the VTN) and send reports (i.e. provide the data, when requested).

Registering reports

When Plaid needs to send a register reports payload to the VTN, it will trigger the registerReports function in the callback to gather the necessary data. This is typically done after the initial registration, and can be re-triggered if requested by the VTN or if the VEN has new information.

The response includes an array of reports that the VEN should register with the VTN. Typically, these reports will be specified by the VTN connection guide and you will follow their guidance for what to include. The content of the response maps to fields in an OpenADR report registration payload. Plaid will the configure your data into OpenADR format and send it to the VTN.

Intervals are individual data point definitions. This is where you define rIds - there can be one or more rIds per report. A common use case for having multiple rIDs per report is when there are multiple devices or sites aggregated under one VEN, and their status needs to be reported individually using unique rIDs. In a report with multiple rIDs, they are included as separate items in the intervalDescriptions array.

If the interval includes usage data, it should include the usageIntervalProperties field. If it is status data, it should not include that field in the interval description.

To re-trigger a report registration, use the register reports endpoint in the Plaid API.

Sending reports

Plaid will keep track of either individual report or repeating report requests and call the queryIntervals function to query the data needed, when it's needed. Plaid will parse the request from the VTN and call queryIntervals once or ongoing accordingly.

The queryIntervals message sent will include information to help the user determine what information to provide:

  • reportSpecifierId: the reportId being referred to in the data request, matching one of the reports that was registered with the VTN
  • rIds: an array of rIds that data is being requested for, matching one or more of the rIds that were registered with the report.
  • startTime and endTime - the data bounds. If equal, just one data point is needed. startTime and endTime are inclusive.
  • granularity - the granularity of data points to provide, within the boundaries described by the report request. For example, if startTime and endTime are a minute apart and granularity is 5 seconds, 13 data points should be sent (because start and end times are inclusive)

Report request / queryIntervals timing

A report request from the VTN will include both a report back duration (how frequently you should send a report, e.g. every 5 minutes) and a granularity. If these are the same, then most of the time the startTime and endTime will be the same - exceptions would be only timing based (e.g. time taken to process the report requests before queryIntervals is triggered means an additional interval needs to be requested).

Plaid will keep track of the latest time reported in the queryIntervals response, and next startTime requested will be latest time + granularity.

queryIntervals response structure

The response to queryIntervals includes an array of reports. Under normal OpenADR operation just one report would be sent per report request, but this arrangement allows flexibility in case reports need to be generated dynamically (if the VTN you are connecting to has specific requirements). An optional field, reportIdentifier can override report ID fields - if excluded Plaid will instead use the values from the report requested (this will be most common).

Within each report, an array of intervals will be sent. Each entry in this array is one data point - a unique combination of rId and time/duration, along with its corresponding value and a data quality indicator. If it is a status data point, the status object should be sent with a response. If a usage data point, this should be ignored.

For concrete examples of queryIntervals and other plugin messages, you can generate sample messages and see the message schemas / generate quicktype casting to inspect and manipulate plugin requests and response messages.

Ad Hoc reports

Sometimes the VEN may have to send report data that hasn't explicitly been requested by the VTN. For example, if data wasn't available at the time the report was requested, updated data can be sent when it becomes available.

To generate an adhoc report and have the VEN send it to the VTN, use the Management API. Note: this functionality was added in v2.3.