Documentation

Supported features for OpenADR 2.0a BOG, OpenADR 2.0b BOG, and OpenADR 3.1 BOG

Overview

The OpenADR VEN provides native Niagara 4 integration with utility demand response programs through three BOG (Building Object Galleon) modules: OpenADR 2.0a BOG, OpenADR 2.0b BOG, and OpenADR 3.1 BOG.

All three modules are pull-based Virtual End Nodes (VENs) that connect to a utility's Virtual Top Node (VTN) to receive Demand Response (DR) events and price signals. They are deployed as .bog files in the Niagara 4 Workbench.

Choose the version that matches your utility's OpenADR standard — 2.0a for legacy XML/SIMPLE-profile systems, 2.0b for full Profile B (registration, reporting, and opt schedules over SOAP/XML), or 3.1 for modern REST-based systems using OAuth 2.0 and JSON (implements the OpenADR 3.1.0 spec, with self-registration, reporting, and multi-program following). Each product section below covers its features, configuration slots, requirements, installation, and licensing.

OpenADR 2.0a BOG

2.0a

OpenADR 2.0a Simple profile VEN for Niagara 4.10+

General

Feature Details
OpenADR Standard 2.0a — Simple profile
Architecture Pull-based (no registration phase)
Distribution Format .bog file for Niagara 4
Platform Niagara 4.10+

Transport & Authentication

Feature Details
Protocol HTTP POST (no XMPP)
Authentication NONE, BASIC
Content Type XML (manual parsing, no JAXB)
Endpoint /OpenADR2/Simple/EiEvent

Event Handling

Feature Details
Polling oadrRequestEvent → oadrDistributeEvent → oadrCreatedEvent
Event State Machine PENDING → ACTIVE → COMPLETED / CANCELLED
Multi-Event Processing Handles multiple events in a single response
Individual Response Codes Per-event response codes (200, 450–463)
Modification Number Validation Monotonic ordering check (E1_0392)
State Transition Validation Prevents illogical transitions (E1_0384)
Inconsistent Event Detection Detects disappeared-and-reappeared events (E1_0370)

Targeting & Filtering

Feature Details
venID Targeting ✅
resourceID Targeting ✅
groupID Targeting ✅
partyID Targeting ✅
Market Context Filtering Optional matching (E1_0285)
VTN ID Validation Optional, returns error 452 on mismatch (E1_0390)

Timing & Randomization

Feature Details
Randomization Offsets x-oadrStartAfter / x-oadrStopAfter
Adjacent Event Detection Back-to-back event awareness (E1_0292)

Opt-Out

Feature Details
Async Opt-Out Supports optOut after initial optIn (E1_0280)

Configuration Slots

Slot Description
vtnUrl VTN server endpoint URL
venId VEN identifier for the VTN (default "VEN-001")
vtnId Expected VTN id; blank accepts any VTN
pollIntervalSec Seconds between polls, 60-3600 (default 300)
authType "NONE" or "BASIC" (default "NONE")
authUsername / authPassword HTTP Basic auth credentials
autoAcknowledge Auto-acknowledge events (default true)
optType Default response "optIn" / "optOut" (default "optIn")
resourceId / groupId / partyId Event targeting filters (blank = accept all)
logToConsole Debug logging to console (default false)
licenseKey License key for activation

Status Outputs

Slot Description
eventActive A DR event is currently active
signalLevel 0=Normal, 1=Moderate, 2=High, 3=Emergency
eventId / eventStatus Current event id and state (none / pending / active / completed / cancelled)
connectionState IDLE / POLLING / PROCESSING / ERROR / STOPPED / DISABLED
eventStart / eventEnd ISO 8601 event start / end times
activeEventCount / pendingEventCount Active / pending event counts
lastPollTime / lastPollSuccess Last poll timestamp and success flag
lastEventResponse Summary of last acknowledgment sent to the VTN
statusTrace Human-readable status / error message
productCode Station product code (used for licensing)
licenseStatus / licenseMessage License state and message
demoTimeRemaining / version Demo countdown and build version

System Requirements

Feature Details
Niagara Version 4.10 or later
Java Bundled with Niagara (JVM 11 compatible)
Memory Minimal — runs within the Niagara process
Network Outbound HTTPS to the VTN endpoint
Distribution .bog file imported via Workbench

Installation

Import the .bog file into a Niagara 4 station:

  1. Open Niagara Workbench and connect to the target station.
  2. Navigate to the desired folder under Config.
  3. Right-click → Import → From BOG File, and select the .bog file.
  4. The OpenADR20aVEN program component appears.

Configure & Enable

  • Set vtnUrl and venId.
  • If the VTN requires Basic auth, set authType = BASIC with authUsername / authPassword.
  • Optionally set event targeting (resourceId / groupId / partyId) and the default optType.

Adjust pollIntervalSec as needed (default 300s), enable the program to begin polling, and wire the output slots into your control logic.

Licensing

This module requires a license bound to the Niagara station Host ID, product type 2.0a-bog. Licenses are RSA-SHA256 signed and validated at runtime. A license is perpetual by default, or can be issued with an optional expiration date for time-limited terms.

Free Trial

Includes a 2-hour demo mode per station restart that requires no license — download and test immediately. The timer resets whenever the Niagara station is restarted.

Activating a License

Each installation is bound to the station Product Code, shown on the read-only productCode output slot when the VEN starts:

  1. Start the VEN — it enters 2-hour demo mode automatically.
  2. Copy the value from the productCode slot.
  3. Redeem an account credit for a license key against that Product Code.
  4. Paste the key into the licenseKey configuration slot.
  5. Confirm licenseStatus becomes valid.

The licenseStatus slot reports demo, valid, invalid, or expired (on expiry the VEN stops polling and connectionState becomes DISABLED). A license generated for one station will not validate on another.

Sign up to start with a free trial. Licenses are purchased per Host ID, with volume discounts for enterprise deployments.

OpenADR 2.0b BOG

2.0b

OpenADR 2.0b Profile B VEN for Niagara 4.10+

General

Feature Details
OpenADR Standard 2.0b — Profile B
Architecture Pull-based (with registration phase)
Distribution Format .bog file for Niagara 4
Platform Niagara 4.10+

Transport & Authentication

Feature Details
Protocol HTTP POST (SOAP/XML, no XMPP)
Authentication BASIC
Content Type XML (JAXB binding)
Transport Security Mutual TLS (RSA & ECC), XML signing

Registration

Feature Details
Party Registration oadrCreatePartyRegistration
Re-registration Handles VTN-initiated re-registration
Cancel Registration oadrCancelPartyRegistration (VEN or VTN initiated)
Report Advertisement oadrRegisterReport advertised at registration

Event Handling

Feature Details
Polling oadrPoll → oadrDistributeEvent → oadrCreatedEvent
Event State Machine PENDING → ACTIVE → COMPLETED / CANCELLED
Multi-Event Processing Handles multiple events, priority-based selection
Event Modification Honors modification-number ordering
Signal Intervals ISO-8601 durations, per-interval signal values

Reporting

Feature Details
Report Registration oadrRegisterReport metadata advertisement
Report Delivery oadrUpdateReport — one-shot, periodic, and telemetry usage
VTN-Initiated oadrCreateReport / oadrCancelReport handling
Configurable Granularity defaultGranularitySec slot

Opt Schedules

Feature Details
Opt In / Opt Out oadrCreateOpt / oadrCancelOpt
Scheduled Opts Opt schedules with effective periods

Targeting & Filtering

Feature Details
venID Targeting ✅
resourceID Targeting ✅
groupID Targeting ✅
partyID Targeting ✅
Market Context Filtering ✅

Configuration Slots

Slot Description
vtnUrl VTN server endpoint URL
venId VEN identifier for registration (default "VEN-001")
vtnId Expected VTN id; blank accepts any VTN
pollIntervalSec Seconds between polls, 60-3600 (default 300)
authType "NONE" or "BASIC" (default "NONE")
authUsername / authPassword HTTP Basic auth credentials
autoAcknowledge Auto-acknowledge events (default true)
optType Default response "optIn" / "optOut" (default "optIn")
resourceId / groupId / partyId Event targeting filters (blank = accept all)
reportEnabled Enable EiReport telemetry (default false)
venName Human-readable VEN name for registration/reporting
defaultGranularitySec Default reporting sample interval, seconds (default 10)
logToConsole Debug logging to console (default false)
licenseKey License key for activation

Status Outputs

Slot Description
eventActive A DR event is currently active
signalLevel 0=Normal, 1=Moderate, 2=High, 3=Emergency
eventId / eventStatus Current event id and state (none / pending / active / completed / cancelled)
connectionState IDLE / REGISTERING / REGISTERED / POLLING / PROCESSING / ACTIVE / ERROR / STOPPED / DISABLED
eventStart / eventEnd ISO 8601 event start / end times
activeEventCount / pendingEventCount Active / pending event counts
lastPollTime / lastPollSuccess Last poll timestamp and success flag
lastEventResponse Summary of last acknowledgment sent to the VTN
registered Party registration completed with the VTN
reportState / reportsRegistered Reporting state and registration flag
activeReportCount / lastReportSent Active report count and last report summary
statusTrace Human-readable status / error message
productCode Station product code (used for licensing)
licenseStatus / licenseMessage License state and message
demoTimeRemaining / version Demo countdown and build version

System Requirements

Feature Details
Niagara Version 4.10 or later
Java Bundled with Niagara (JVM 11 compatible)
Memory Minimal — runs within the Niagara process
Network Outbound HTTPS to the VTN endpoint (mutual TLS optional)
Distribution .bog file imported via Workbench

Installation

Import the .bog file into a Niagara 4 station:

  1. Open Niagara Workbench and connect to the target station.
  2. Navigate to the desired folder under Config.
  3. Right-click → Import → From BOG File, and select the .bog file.
  4. The OpenADR20bVEN program component appears.

Configure & Enable

  • Set vtnUrl and venId (the VEN registers automatically).
  • Set authType / authUsername / authPassword for Basic auth.
  • Set venName, and enable reportEnabled if telemetry reporting is required.

Adjust pollIntervalSec as needed (default 300s), enable the program to begin polling, and wire the output slots into your control logic.

Licensing

This module requires a license bound to the Niagara station Host ID, product type 2.0b-bog. Licenses are RSA-SHA256 signed and validated at runtime. A license is perpetual by default, or can be issued with an optional expiration date for time-limited terms.

Free Trial

Includes a 2-hour demo mode per station restart that requires no license — download and test immediately. The timer resets whenever the Niagara station is restarted.

Activating a License

Each installation is bound to the station Product Code, shown on the read-only productCode output slot when the VEN starts:

  1. Start the VEN — it enters 2-hour demo mode automatically.
  2. Copy the value from the productCode slot.
  3. Redeem an account credit for a license key against that Product Code.
  4. Paste the key into the licenseKey configuration slot.
  5. Confirm licenseStatus becomes valid.

The licenseStatus slot reports demo, valid, invalid, or expired (on expiry the VEN stops polling and connectionState becomes DISABLED). A license generated for one station will not validate on another.

Sign up to start with a free trial. Licenses are purchased per Host ID, with volume discounts for enterprise deployments.

OpenADR 3.1 BOG

3.1

OpenADR 3.1 VEN (implements the 3.1.0 spec) for Niagara 4.13+

General

Feature Details
OpenADR Standard OpenADR 3.1.0 (REST/JSON)
Architecture Pull-based (REST/JSON)
Distribution Format .bog file for Niagara 4
Platform Niagara 4.13+

Transport & Authentication

Feature Details
Protocol REST/JSON HTTP (GET/POST)
Authentication OAuth 2.0 client_credentials grant
Token Caching In-memory token cache with pre-emptive refresh (30s skew)
401 Retry Retries once on 401 before failing
Public VTN Mode No-auth mode when credentials are blank

Program & Event Resolution

Feature Details
Program Discovery Resolves program by name (or takes first available)
Multi-Program Following Follows several programs at once via a comma-separated programName
Event Fetching Paged GET with skip/limit (max 50 per page)
Target Filtering Server-side ?targets= CSV filter
Event Selection Priority timeline — higher-priority events punch through and split lower-priority ones

Self-Registration (optional)

Feature Details
VEN Registration Optionally self-registers via POST /vens (VEN_VEN_REQUEST) on first poll
Resource Registration Registers one or more resources via POST /resources (VEN_RESOURCE_REQUEST)
Idempotent Reuses an existing ven/resource by name — safe across restarts, never duplicates
Scopes Requests write_vens / read_ven_objects automatically when enabled

Interval Timing

Feature Details
dtstart / duration ISO-8601 format
Contiguous Chaining Back-to-back intervals when no explicit start
Infinity Sentinel P9999Y duration support
"Now" Sentinel Real-time interval resolution

Randomization

Feature Details
randomizeStart Uniform random offset within [-max, +max] window

Signal Types

Feature Details
Primary Numeric Main numeric payload value
Alert Payload String-based alert signals
String Payload Arbitrary string payloads
Sub-Interval Serial Types PRICE, EXPORT_PRICE, GHG multi-value splitting
Payload Summary TYPE=value;TYPE2=value2 format for all payloads

Reporting & Errors

Feature Details
3.1.0 Reports eventID + clientName + resource payloads
OAuth Errors RFC 6749 error response parsing
API Errors Zalando problem+json format parsing

Configuration Slots

Slot Description
vtnUrl VTN base URL (REST API root)
clientId / clientSecret OAuth2 client credentials (leave both blank for a public VTN)
scope Base OAuth2 scope (default "read_targets"); write_reports / write_vens are added automatically when reporting or self-registration is enabled
programName Program the VEN follows (comma-separated to follow several; blank = first available)
venName VEN name reported to (and registered with) the VTN (default "VEN-001")
resourceName Resource this VEN represents (optional)
registerEnabled Self-register the VEN and its resources with the VTN (default false)
resourceNames Comma-separated resource names to register (blank = resourceName, else venName)
pollIntervalSec Seconds between polls (default 300)
targets Comma-separated target strings for server-side filtering
reportEnabled Post reports back to the VTN — requests write_reports scope (default false)
logToConsole Debug logging to console (default false)
licenseKey License key for activation

Status Outputs

Slot Description
eventActive A DR event is currently active
signalType Active signal type (SIMPLE, PRICE, EXPORT_PRICE, GHG, or alert)
signalValue Primary numeric payload value of the active interval
signalText Text value for alert/string signals
payloadSummary Readable summary of all payloads on the active interval
eventId / programId Event and program identifiers
eventStatus none / pending / active / completed
intervalStart / intervalEnd RFC 3339 bounds of the active interval
eventStart / eventEnd RFC 3339 event start / end times
activeEventCount / pendingEventCount Active / pending event counts
connectionState IDLE / POLLING / ERROR / DISABLED
lastPollTime / lastPollSuccess Last poll timestamp and success flag
reportState / lastReportSent Reporting state and last report summary
statusTrace Human-readable status / error message
productCode Station product code (used for licensing)
licenseStatus / licenseMessage License state and message
demoTimeRemaining Demo countdown
version Implemented spec version (e.g. 3.1.0)

System Requirements

Feature Details
Niagara Version 4.13 or later
Java Bundled with Niagara (JVM 11 compatible)
Memory Minimal — runs within the Niagara process
Network Outbound HTTPS to the VTN OAuth2 and API endpoints
Distribution .bog file imported via Workbench

Installation

Import the .bog file into a Niagara 4 station:

  1. Open Niagara Workbench and connect to the target station.
  2. Navigate to the desired folder under Config.
  3. Right-click → Import → From BOG File, and select the .bog file.
  4. The OpenADR30VEN program component appears.

Configure & Enable

  • Set vtnUrl (the REST API base URL).
  • Set OAuth2 clientId / clientSecret (leave both blank for a public VTN).
  • Set programName to the program the VEN should follow; optionally set targets for server-side filtering.

Adjust pollIntervalSec as needed (default 300s), enable the program to begin polling, and wire the output slots into your control logic.

Licensing

This module requires a license bound to the Niagara station Host ID, product type 3.1-bog. Licenses are RSA-SHA256 signed and validated at runtime. A license is perpetual by default, or can be issued with an optional expiration date for time-limited terms.

Free Trial

Includes a 2-hour demo mode per station restart that requires no license — download and test immediately. The timer resets whenever the Niagara station is restarted.

Activating a License

Each installation is bound to the station Product Code, shown on the read-only productCode output slot when the VEN starts:

  1. Start the VEN — it enters 2-hour demo mode automatically.
  2. Copy the value from the productCode slot.
  3. Redeem an account credit for a license key against that Product Code.
  4. Paste the key into the licenseKey configuration slot.
  5. Confirm licenseStatus becomes valid.

The licenseStatus slot reports demo, valid, invalid, or expired (on expiry the VEN stops polling and connectionState becomes DISABLED). A license generated for one station will not validate on another.

Sign up to start with a free trial. Licenses are purchased per Host ID, with volume discounts for enterprise deployments.

Feature Comparison

Feature 2.0a BOG 2.0b BOG 3.1 BOG
Standard 2.0a Simple 2.0b Profile B OpenADR 3.1.0
Transport HTTP POST (XML) HTTP POST (SOAP/XML) REST (JSON)
Authentication NONE / BASIC BASIC OAuth 2.0
Architecture Pull, no registration Pull, with registration Pull, OAuth2
Event Format XML (manual parse) XML (JAXB) JSON (manual parse)
Event Polling oadrRequestEvent oadrPoll / distribute GET with pagination
Event State Machine PENDING→ACTIVE→COMPLETED PENDING→ACTIVE→COMPLETED Interval-based timing
Multi-Event ✅ ✅ (priority-based) ✅ (priority-based)
Registration N/A ✅ ✅ (optional self-register)
Target Filtering venID/resourceID/groupID/partyID venID/resourceID/groupID/partyID Server-side ?targets= CSV
Market Context ✅ ✅ N/A
Randomization Start/stop offsets Start/stop offsets Uniform randomizeStart
Opt-Out Async opt-out Opt schedules (in/out) N/A (no opt for 3.1 pull)
Reporting ❌ ✅ (register / update) ✅ (3.1.0 reports)
Signal Types Simple only Simple + economic signals Numeric, alert, string, sub-intervals
Error Format OpenADR response codes OpenADR response codes problem+json
Min Platform Niagara 4.10+ Niagara 4.10+ Niagara 4.13+