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
  • Webhook example
  • Dispatch API example
• 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
  • Webhook example
• 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 and dispatch_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. This cancelled 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:

1. Which meter_id or market_group_id is being dispatched
2. What is the event start_time and end_time
3. 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. See start_time and end_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 the performance_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 compensated
  • up-to-site-load - Dispatching up to a site load of 0 kW (curtailing all site load) will be compensated for
  • grid-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, and 5m - 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, the day-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 the hour-ahead market. In the latter case, the updated event notification would have the increased total energy kW award and list both day-ahead and hour-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.