Conditional agreements

This guide will help you get started with integration for conditional agreements.

To comply with contractual rules for curtailing the power of a customer resource (e.g. an EV charging site), limit requests from the grid owner must be handled by integrating with the Switch platform. The requests are generated as events within the OpenADR standard. Each event covers a 15-minute delivery period where average resource power levels must be below the specified limit. Each 15-minute delivery period can only contain a single event per resource. Resources must also report their real-time data by sending readings of their active power usage to the Switch API.

Some resources support an advanced mode of curtailing using dynamic limits. Dynamic limits differ from the normal behavior in two ways:

• The limit for a specific delivery period might not be equal to the configured resource limit. It can be set to a higher or equal value, but never lower.

• The delivery limit might change at any time before the delivery period starts. This is done by updating the OpenADR event for the delivery period.

It's highly recommended to first go through the guide on How to send readings, after which steps 1 and 2 of this guide can be skipped.

1. Getting Started

First of all, you'll need to be set up and get accustomed to working with the Switch API. Next you need to create an Organization Client and note the client ID and secret since you will need them further on.

2. Get Access Token

In order to be able to fetch or send readings, you first need a valid access token that will be used to authorize your request to the Switch API.

To accomplish this you will need the previously noted client ID and client secret and use them to retrieve valid access token by following the client credentials flow as described in Client Credentials Flow page. Please note the endpoint for retrieving the token as stated in Token Endpoint page depending on which environment you want to interface with.

When you have your access token ready, proceed with the next step.

3. Get Resource Information

You can use the Get resources endpoint to find information about the resources available in your organization. The ID of a specific resource is needed to handle requests and reports. It's also possible to view the resource information in the Switch app, as described in the Concepts section.

You can find the configured limit by checking the conditionalDeliveryLimit parameter of the Get resources response, or by looking at the Resources page of the Switch app.

Unless the the resource supports dynamic limits (indicated by the flag conditionalUseDynamicDeliveryLimit), this is the limit which will be used for all limit requests.

4. Setup OpenADR Credentials

To fetch limit requests in the form of events, you first need to create a VTN client and secret, as described in the Authentication section of the OpenADR 3 documentation.

Optionally, you can also setup a subscription to use webhooks for events instead of only using HTTP polling, as detailed in the Webhooks section.

In case webhooks are used, keep in mind that to support dynamic power limits the subscription must be for both POST and PUT actions on the event entity.

5. Get Program

When you have an access token for OpenADR ready, you can test it by using the endpoint that searches all programs. The response should contain the basic parameters of the OpenADR 3 program used by Switch, like the example below:

{
    "id": "980",
    "createdDateTime": "2024-10-24T15:04:16.139Z",
    "modificationDateTime": "2024-10-24T15:04:16.139Z",
    "objectType": "PROGRAM",
    "programName": "CondAgree",
    "programLongName": "Conditional Agreement",
    "timeZoneOffset": "PT0S",
    "programDescriptions": [],
    "bindingEvents": false,
    "localPrice": false,
    "payloadDescriptors": [],
    "targets": []
}

6. Create Test Event

You can use the Switch app (QA environment only) to create your own events for test purposes. First, navigate to Conditional agreements/Requests in the top menu. On that page you'll find a button in the top right corner to create manual requests, which will open a dialog:

You can select one or multiple resources to create requests for. All created requests will be listed in the table on the page and will be available as OpenADR events.

7. Get Events

To fetch events, you can use the searches all events endpoint. We provide some code samples as suggestions on how to implement authentication and polling for events. To learn more about the structure of a typical event, visit the payloads page.

Once you've successfully fetched an event you can proceed to the next step.

8. Acknowledge Events

All events must be acknowledged by sending a report back to the VTN using the add a report endpoint. This must be done within 5 minutes after the event was created or the event limit was updated. To learn more about the structure of a typical acknowledgement report, visit the payloads page.

9. Validate Delivery

To verify that the resource power levels was below the event delivery limit, you can check the updated data included in the event, which should be available within 30 minutes of the end of the delivery period (i.e. start time + 15 minutes). As shown in the payload example below, both the validation status and the reading value are included:

{
    "type": "POWER_LIMIT_VALIDATION_STATUS",
    // Status of the validation. Possible values:
    // - ok: validation succeeded (resource was below limit)
    // - not_ok: validation failed (resource was above limit)
    // - unable_to_validate: validation could not run, e.g due to missing readings or a bad configuration
    "values": ["ok"]
},
{
    "type": "POWER_LIMIT_VALIDATION_STATUS_TEXT",
    // Human readable explanation  of the status for debugging purposes.
    "values": ["Validation succeeded."]
},
{
    "type": "POWER_LIMIT_VALIDATION_TIMESTAMP",
    // The time & date when the validation was run.
    "values": ["2023-10-20T12:25:00Z"]
},
{
    "type": "POWER_LIMIT_VALIDATION_READING",
    // The reading value that was used for validation. Might be an average of several readings.
    "values": [14000]
}

10. End-to-End Testing

When all previous steps are completed, you should be ready for a full test procedure. This typically involves on-site verification of enforced limits of e.g. EV chargers, based on a test event created by the grid owner. When the testing is completed, the resource may be approved for normal operation.