Dispatch Automation
Dispatches are signals from the Leap platform about a grid event. A dispatch event is a request for an individual meter or group of meters to curtail (or export in some cases) energy during a defined time period. A Leap dispatch notification could contain one or many of these unique dispatch events within it.
Responding to dispatches in a timely and consistent manner is essential to achieving high performance during grid events and maximizing revenue potential.
Dispatch automation with Leap enables you to integrate once and scale to all available markets and programs. While there may be some differences between programs, Leap simplifies implementation by providing a common dispatch notification structure so that your event processing logic can be leveraged across all markets and programs.
Storing Leap Meter IDs a Prerequisite for Dispatch Automation
Unless you are manually managing a small number of meter IDs manually, you will need to integrate with the Meter Enrollment endpoint in order to complete dispatch automation. See the Ensure readiness for dispatch events section of the Sync Meter Inventory guide and review use case A (storing meter ID), use case B (tracking enrollment status), and optionally use case C (syncing market group mapping).
Dispatch Structure
A dispatch has two top-level components:
- Recipient: The Meter or Group responsible for responding to the dispatch event
- Timeslot(s): The dispatch time period as well as additional details about the service required during that time period
Recipient (Meter or Market Group)
You can choose to receive dispatches at the meter or market group level:
Group Dispatching Considerations:
- You must keep your internal groups in-sync with Leap. As described in the Sync Meter Updates guide, you can use the market_group_id in the meters API endpoints to guide the provisioning process in your system.
- The dispatch event notification will include both the group ID and the list of your meter IDs which are part of that group. The energy curtailment awarded should be distributed across this group of meters.
Timeslots
A timeslot describes the details of a dispatch. It includes the start and end time, energy quantity, and other metadata. Additional details on these fields can be found later in this guide.
{
"meter_id": "afce893d-ea68-487f-9f8c-778b1881f60a",
"timeslots": [
{
"meter_event_id": "f4cfced0-16f4-4fb7-b72e-5ff939ae541e",
"start_time": "2022-06-02T00:00:00Z",
"end_time": "2022-06-02T01:00:00Z",
"cancelled": false,
"energy_kw": 4.000,
"performance_compensation_cap": "up-to-site-load",
"priority": 2,
"is_voluntary": false,
"dispatch_event_types": [
"day-ahead",
"capacity-test"
],
"programs": [
"DRAM"
]
}
]
}
Notification Methods
There are multiple options for receiving these dispatch notifications. The Leap API provides both push and pull models below:
- Webhook Push Notifications - Leap pushes notifications to your webhook endpoint as soon as they are available
- Dispatch Event Polling - You poll the relevant Leap dispatch endpoint on a regular basis checking for new updates
Webhook Push Recommended
The webhook approach is recommended over polling as it is most efficient and more easily enables participation in real-time markets. It also allows for sending yourself test dispatch events via the trigger notification endpoints making it easier to test your integration.
Endpoints
The endpoints available to support these two methods are summarized below:
- Webhook Push - Meter-Level Push & Group-Level Push
- Get/Set/Delete your webhook URL
- Trigger test notification to your webhook URL
- Event Polling
- Search Meter-Level Dispatches - For retrieving dispatch events broken out at an individual meter/site level
- Search Group Dispatches - For retrieving dispatch events by groups of aggregated meters/sites
Types of Test Events
Capacity Test
- Scheduled by: Leap or program operator based on program requirements
- This is a real event that impacts revenue. This is not a test event like the Communication Test or Integration Test events below.
- Dispatch notification field:
capacity-test
within dispatch_event_types array of timeslots object - Partner action: This is a high priority event that should be responded to in order to prove capacity to the market. Capacity performance will be used in settlement calculations.
Communication Test
- Scheduled by: Partner on Dispatch Tab in Partner Portal
- This is meant to be run by operations teams whenever something changes in the end-to-end integration setup (e.g. integration update, control system or customer device software upgrades) or whenever a new season starts (for programs that do not run year-round) in order to verify that everything is working properly and devices are responding.
- This is supported for the webhook, dispatch API polling, and email notifications. Events are stored in the Leap dispatch database and will show up on the Dispatch Tab in the Portal and in the Dispatch API.
- Dispatch notification field:
communication_test
=true
- Partner action: Leap recommends that partners process these communication test events just like real dispatch events so the end-to-end flow can be tested. If you do not want end customer devices to take action, these events can be cancelled after scheduling is confirmed. Cancelling these events allows for confirmation that the event was scheduled correctly but it does not confirm responsiveness of the devices.
Integration Test
- Scheduled by: Partner via trigger test notification endpoint
- This is meant to be run by technical teams when making updates to the Leap dispatch integration or downstream systems.
- Only supported for webhook dispatch integrated partners. These test events are not stored by Leap.
- Dispatch notification field:
integration_test_notification
=true
- Partner action: Dependent on partner testing goals.
Dispatch Event Processing
Dispatch events could come from a variety of sources depending on the program. For example, these could be triggered by a program operator due to grid stress or emergency, or simply as a test to validate performance. They could also be created by Leap as a way to validate performance for capacity payments. Or it could be a market award given as the result of clearing in a wholesale energy marketplace.
Regardless of the source, it is important to respond in a timely and consistent manner to ensure good performance and maximize revenue. The sections below provide guidance on how best to process these incoming event notifications.
Market & Program-Agnostic Integrations
It is recommended to keep your dispatch integration and event processing generic across markets and programs to enable expansion to new programs and revenue streams without requiring any integration updates or code changes.
For this reason, the dispatch information and logic provided in this guide is intended to be applicable for all markets and programs. Where there are significant and relevant differences in behavior between markets/programs, those are noted accordingly.
Example Code Recipes
The recipes below walk through example dispatch event processing code as outlined in the remainder of this guide.
Multiple Events Within a Notification
Within the meter_dispatches
(webhook) or results
(event polling) arrays in the dispatch notifications will be objects that include the meter/group IDs along with their associated event timeslots
array. Always assume each array could have multiple objects within it (e.g. multiple meter ID/timeslots objects within the notification and multiple timeslot objects within each timeslots
array).
New, Modified, & Canceled Events
A unique dispatch event is indicated by the meter_event_id
or market_group_event_id
field in the notification. There could be many different dispatch events included within a single webhook push notification or Search Dispatches response, each of which could indicate a new, modified, or canceled event.
New Events
Sent via webhook push (or by polling the Leap dispatch API) as soon as they are available. Depending on the program and itβs expected advance notice period, a dispatch could be sent days in advance or seconds before the start time.
Modified Events
Modifications to events can happen occasionally and your integration needs to be able to handle and process these event updates. In these cases a new dispatch event notification will be sent with the same meter_event_id
or market_group_event_id
. Any of the fields that changed from the original event notification should be updated. Some examples of modified dispatch notifications include:
- Increased
energy_kw
value - Updated
end_time
for event
Some Event Modification Examples
In California (CAISO), it is possible to get a day-ahead award for less than the full nomination kW value and then in the hour-ahead (HASP) market get a modified dispatch event notification increasing the kW value of that award. In this case, the updates to the dispatch notification would be the
energy_kw
anddispatch_event_types
fields.In the Texas (ERCOT) ERS program, the end time for these emergency events is not known at the start of an event so in these cases Leap will use your ERS accepted time periods to determine the next point at which you are no longer obligated to curtail energy. If the event ends ahead of that, an updated dispatch notification will be sent indicating the UTC time that the event ended (this update will show a new end time that could be up to a few minutes in the past given that the event just ended). If the emergency event is still ongoing, a new event will be created prior to each contiguous time period you are obligated to participate in.
In the California (CAISO) ELRP program, similar to the ERS program above, the emergency event could end in the middle of an ongoing event in which case an updated dispatch notification will be sent indicating the UTC time that the event ended (this update will show a new end time that could be up to a few minutes in the past given that the event just ended).
Early Termination vs. Cancellation
For the early termination of ongoing events as described in the above ERS and ELRP examples, the
cancelled
field will still be set to false. Thiscancelled
flag is only set to true if the event needs to be cancelled before it begins as described in the next section below.
Canceled Events
Cancellations are denoted with the cancelled boolean field when needed and would indicate the meter_event_id
or market_group_event_id
to be cancelled. Cancellations are rare and only happen if an event needs to be cancelled before it starts. Examples of this could be a capacity test that was mistakenly scheduled or an emergency event that was called and is no longer needed. Note that if an event has already started but needs to end prematurely (e.g. emergency event is over), an event update (see Modified Events above) will be sent out with an updated end_time
and the cancelled
flag will remain false.
When receiving a webhook push notification or polling the Dispatch API, it is important to look at this
cancelled
field to determine if an event that was previously scheduled has been cancelled and no longer needs to be responded to. Note that when polling the v2 Dispatch API, all events will be provided in the response even if they have since been cancelled whereas in v1.1 cancelled events were removed completely from these responses.
Key Event Fields
Beyond checking the meter_event_id
or market_group_event_id
and looking for cancelled or modified events, base dispatch event logic is determined by:
- Which
meter_id
ormarket_group_id
is being dispatched - What is the event
start_time
andend_time
- What is the expected
energy_kw
power in KW to be curtailed/exported for the duration of the event (if your technology can directly control this)
Power vs. Energy
The
energy_kw
field name can be confusing but as noted above, this indicates the power in KW to be curtailed/exported for the duration of the event. Seestart_time
andend_time
below to determine the event duration.
Null Energy kW Value
The energy value for an event may be
null
for voluntary pay-for-performance programs, like CAISO ELRP, that do not have an expected or nominated energy value for the program. In these cases, it is expected that you curtail or export as much as you are able to up to theperformance_compensation_cap
limit as outlined in Dispatch Strategy C below.
start_time
& end_time
considerations:
- The ISO 8601 standard in the UTC timezone is used throughout the Leap API to indicate start and end times
- Note: In California (CAISO), day-ahead market events are provided in 1-hour increments so for longer duration events, multiple sequential 1-hour timeslots may need to be aggregated together depending on how you schedule and push out events to your end customer devices
Overlapping Events & Event Consolidation
It is possible to receive overlapping dispatches for certain timeslots if events are triggered for different reasons or for multiple programs so ensure that your implementation can process and combine these overlapping time periods appropriately. For example, a CAISO DRAM award could be received from 5-6pm and an ELRP event called from 5-9pm. Check out Test Case 6 in the Test Cases guide for additional CAISO, CA DSGS, and NYISO overlapping examples.
When combining events and deciding how to respond appropriately, it is suggested that you use one or more of the dispatch strategies below.
Dispatch Strategies & Additional Event Fields
Depending on your technology and customer experience requirements, you may choose to implement one or combine multiple of these strategies below.
Strategy A: Maximize revenue by responding to all events
Strategy B: Prioritize events when max event duration constraints exist
Strategy C: Increase revenue when controlling onsite batteries
Strategy D: Gain flexibility when prioritizing along with outside factors
Strategy A: Maximize revenue by responding to all events
When no event duration constraints exist, you can simply use the above mentioned key event fields to respond to all events and maximize revenue.
Strategy B: Prioritize events when max event duration constraints exist
Use the priority
field to choose the most lucrative time periods when max event duration constraints exist. It is possible that a customer meter or group of meters could receive multiple same-day events as well as overlapping events. If your technology or customer experience constraints do not allow for responding to events for more than a certain number of consecutive hours or total hours in a day, you can use this field to prioritize which timeslots to respond to:
priority
- A numerical value indicating the priority of the event (with 1 being the highest priority). Leap will weigh partner penalties against program revenue and assign this priority to dispatch events based on the best revenue outcomes for our partners. It is recommended to use this field when prioritizing which events to respond to as Leap will update this program priority ranking over time as new programs are added or program revenue expectations change.
See the Dispatch Event & Program Prioritization guide in the Leap Knowledge Center (requires partner portal credentials) for an example prioritization scenario and a breakdown of
priority
values per program within each of the regional markets.
Strategy C: Increase revenue when controlling onsite batteries
When controlling battery discharge rates, use the performance_compensation_cap
to determine when discharging beyond the specified energy_kw
will be compensated for:
performance_compensation_cap
- Indicates if over-performance is compensated for. Many programs pay for over-performance (and penalize for under-performance) so it is generally recommended to curtail/export as much as you can (within technology & customer experience constraints) and you can use this field to optimize when to go beyond the nomination or awarded value. The possible values for this field are:up-to-nomination
- Dispatching beyond nomination value will not be compensatedup-to-site-load
- Dispatching up to a site load of 0 kW (curtailing all site load) will be compensated forgrid-exports-allowed
- Dispatching beyond a site's load (negative site load) and exporting energy to the grid will be compensated for
See the Dispatch Event & Program Prioritization guide in the Leap Knowledge Center (requires partner portal credentials) for a breakdown of performance_compensation_cap
values per program within each of the regional markets.
Strategy D: Gain flexibility when prioritizing along with outside factors
When daily response flexibility is needed, energy curtailment can be reduced or events can be ignored when the is_voluntary
field is set to true. While is it recommended to use the priority
field for prioritization decisions, the is_voluntary
field can be used to adjust responses for certain conditions (e.g. battery state of charge is low due to outside factors):
is_voluntary
- Indicates whether the dispatch is voluntary or a commitment. Pay-for-performance events, with no energy commitment to achieve, are categorized as true. If a dispatch event constitutes a market or program commitment or carries penalties for non-performance, this is set to false.
See the Dispatch Event & Program Prioritization guide in the Leap Knowledge Center (requires partner portal credentials) for a breakdown of is_voluntary
values per program within each of the regional markets.
Optional Event Data for Logging
The additional parameters below are provided in the dispatch message for informational purposes and can either be ignored or logged in your internal systems. Additional detail on these and the other timeslot object parameters above are described in the applicable API reference docs.
dispatch_event_types
-
Used for any programs that have different compensation structures for different types of dispatch events. The event type(s) will be listed in this array. Most programs have a single compensation structure and will be listed with a value of
standard
. -
To see the dispatch event type value per program, check out the regional tables at the bottom of the Event Prioritization guide (requires Partner Portal credentials).
-
Possible values for the CAISO DRAM/CCA programs:
capacity-test
- This is a high priority event that should be responded to in order to prove capacity to the market. Capacity performance will be used in settlement calculations.day-ahead
,hour-ahead
,15m
, and5m
- These indicate market awards received in the CAISO day-ahead and real-time markets. Note that day-ahead and hour-ahead market awards should be expected in CAISO but 15m and 5m markets are optional and would need to be opted into.
A common event update scenario in CAISO is for a capacity-test to be scheduled and then later this same timeslot gets picked up in the day-ahead market. In this case, the initial event notification would list
capacity-test
in this array and then when the event gets updated later with the market award, theday-ahead
value would get added as well.Another CAISO event update scenario is getting a partial kW award in the
day-ahead
market and then later getting additional kW awarded in thehour-ahead
market. In the latter case, the updated event notification would have the increased total energy kW award and list bothday-ahead
andhour-ahead
values in this array.
programs
- Indicates one or more programs that this event was called for. Programs could have different advance notice expectations or market rules (e.g. exports are allowed in the CAISO ELRP program).
Program Names
Program name values used for dispatching are outlined in the Event Prioritization guide and do not always match the program names used in the Meters API
participation
object.
New Fields in Dispatch Notifications
New fields may be added to these dispatch JSON objects over time as market/program requirements change. These additional fields are not considered breaking changes and therefore would be released under the existing API version so it is important to ensure your implementation can handle any new key/value pairs gracefully.
Updated about 1 month ago