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 Market Group Event Notification

{
  "integration_test_notification": false,
  "communication_test": false,
  "group_dispatches": [
    {
      "market_group_id": "11aa7aae-24e5-455f-91e9-e0f5f145f2ae",
      "meter_ids": [
        "abae2779-e392-4f00-b0cf-32e716204f78",
        "bbae2779-e392-4f00-b0cf-32e716204f78"
      ],
      "timeslots": [
        {
          "market_group_event_id": "114751e8-c0df-4d69-8a4f-9e7cebef1f84",
          "start_time": "2023-06-04T23:00:00Z",
          "end_time": "2023-06-05T00:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "up-to-site-load",
          "priority": 2,
          "is_voluntary": false,
          "dispatch_event_types": [
            "day-ahead"
          ],
          "programs": [
            "CCA"
          ],
          "energy_kw": 8.500,
          "nomination_kw": 11.000
        }
      ]
    }
  ]
}

🚧

Multiple Events Within a Notification

Within the group_dispatches (webhook). 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).

Event Processing

Key Event Fields

To schedule events, most implementations only require the following fields. With this information, you can schedule the curtailment or export of energy from customer devices at the appropriate time and for the expected length of time (whenever possible).

1. market_group_event_id (or meter_event_id) - To understand if this is for a new or existing event
   1. When receiving existing event IDs, see the 'Updates to Existing Events' section below
2. meter_ids (or market_group_id) - To lookup which customer devices need to have their schedule updated
3. start_time & end_time - To understand the start time and duration of the event
   1. The ISO 8601 standard in the UTC timezone is used throughout the Leap API to indicate start and end times
   2. 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 stackable programs so ensure that your implementation can process and combine these overlapping time periods appropriately. For example, a CAISO CCA 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.

Updates to Existing Events

If an event notification comes in with an already received meter_event_id or market_group_event_id, check the fields below to see what, if anything, has changed for the event:

1. Cancelled Event - cancelled would be set to "true"
   1. 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.
2. Modified Event - Modifications to events can happen occasionally and your integration needs to be able to handle and process these event updates. Any of the fields that changed from the original event notification should be updated. Some examples of modified dispatch notifications include:
   1. Increased energy_kw value
   2. Updated end_time for event

📘

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). 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).

In the PJM Capacity program (for both real and capacity test events), the end time is not known at the start of an event so in these cases Leap will use the latest possible end time of 10pm ET. 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).

🚧

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.

Event Power & Energy

The energy_kw field provides the power in kW to be curtailed/exported for the duration of the event (if your technology can directly control this). Most partner integrations simply ignore or log this value and curtail/export as much as possible to maximize grid support and revenue. Leap will work with your team to right-size your meter nomination_kw (expected curtailable kW) per program based on technology type and performance.

🚧

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 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.

Example Code Recipes

The recipes below walk through example dispatch event processing code:

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 to 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 CCA program:

  • 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.