Dispatch Integration Tutorial
Introduction
Integrating with Piclo for our ‘Dispatch flow’ has a few touch points. This tutorial will guide you through these, starting from fetching Contractual Obligations to receiving a Dispatch Instruction from a System Operator (SO) - so that you can successfully provide Flexible Energy to the Grid in an efficient and fully automated manner.
Prerequisites
- You have machine user credentials and you know how to authenticate
- If not, check here for machine user credentials: https://docs.picloflex.com/#section/Overview/Getting-access
- Check here on how to generate a Bearer token: https://docs.picloflex.com/#tag/authtoken
- You have successful Bids, and hence Contractual Obligations with an upcoming Dispatch (Service) Window
Dispatch Diagram
Steps
1. Fetch Contractual Obligations
The first step of this flow is to fetch Contractual Obligations. This is so that you are aware of the upcoming windows you will be expected to dispatch for. This is a simple get request to the V1 Contractual Obligations endpoint, to fetch all your obligations:
curl --request GET https://api.picloflex.com/obligations/v1/ --header 'Authorization: Bearer XXXXXX'
Note: you can also optionally filter on start/ end date since/to, competition_id and bid_id - if you want to narrow down your search.
If needed, you can use the competition_id field to fetch more details of the ‘parent’ competition that this obligation relates to, for example calling the V1 Competition API:
curl --request GET https://api.picloflex.com/competitions/v1/{the comp ID}/ --header 'Authorization: Bearer XXXXXX'
The obligation also includes the asset ID’s associated with this obligation, which leads us onto the next steps.
2. Fetch Obligated Assets
The Obligated Assets are effectively the Assets that were used in the accepted Bid (which created the Obligation). You may want to cross-reference what these Assets are. You can retrieve the details that Piclo has stored regarding these Assets, by either calling the V1 Asset API, passing each of asset IDs separately:
curl --request GET https://api.picloflex.com/assets/v1/{An obligated asset ID}/ --header 'Authorization: Bearer XXXXXX'
Or, to fetch them all in one request, you can call the V1 Obligated Assets API, passing the Obligation ID:
curl --request GET https://api.picloflex.com/assets/v1/obligations/{the Obligation ID}/ --header 'Authorization: Bearer XXXXXX'
After these first two steps, you should now be aware of any upcoming Dispatch Windows you’re obligated for, and the technical details they entail.
3. Submit Availability Variation
Coming soon 👷🏗️
4. Receive Dispatch Instructions
The “main'' part of this flow is setting up functionality to receive Dispatch Instructions. Piclo relays dispatch instructions to you, the Flex Provider, on behalf of the System Operator.
We do this via webhook, which means you will need to set-up a ‘webhook receiver endpoint’ in order to receive these events. Following that, you will need to subscribe this receiver endpoint to a Dispatch Instruction event with Piclo. More details on how to do that can be found here: https://docs.picloflex.com/#section/Using-our-Webhooks
Note that, for the time being, there are two types of dispatch webhook listed in the documentation. Please subscribe using the fp_dispatch_instruction_collection webhook, unless you’ve specifically been told you need to integrate with the other webhook – we will only deliver notifications through the latter for specific competitions. The usage described in the section below pertains to the fp_dispatch_instruction_collection webhook.
Authenticating webhook notifications
When we receive Dispatch Instructions from a System Operator, we will send a `post` request of a cryptographically signed payload to your subscribed receiver endpoint. You should verify that this http request came from Piclo by calling the webhook Public Key endpoint:
```bash curl --request GET 'https://api.picloflex.com/webhook/v1/public-key/ --header 'Authorization: Bearer XXXXXX' ```
And using this public key to verify the payload, explained here: https://docs.picloflex.com/#section/Using-our-Webhooks/Verifying-and-Decoding-the-Payload
Fetching dispatch instructions
The webhook payload contains a data_url field , which is a URL from which you can fetch the dispatch instructions. The response schema in which dispatch instructions are provided is described here: https://docs.picloflex.com/#tag/dispatch/paths/~1dispatch~1v1~1instructions~1/get – note that you do not need to add any further query parameters: the data_url as delivered by webhook is complete, and will select exactly the relevant dispatch instructions.
Please note that the latter also means that when you receive multiple notifications in succession, but with different data_url s, you need to follow up on each of them, as they will pertain to different sets of dispatch instructions. Furthermore, the field instruction_count in the webhook payload informs you how many instructions to expect from each such notification.
Authenticating dispatch instruction data
Next, in order to verify that a Dispatch Instruction originated from the System Operator, they have the option to supply a value for the `signature` field. Piclo expects this to be some sort of cryptographic signature which will need to be agreed upon “off platform” between yourselves and the System Operator - Piclo just provides the means of doing so.
Finally, once you’ve verified the Dispatch Instruction is legitimate (having verified it’s been sent by the System Operator and in-turn relayed by Piclo), you should act upon the Dispatch Instruction and dispatch your assets. ⚡