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. Dispatch Instructions are sent by the System Operator to Piclo, which we then pass through to you, the Flexible Service Provider.
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 that can be found here: https://docs.picloflex.com/#section/Using-our-Webhooks.
When we receive a Dispatch Instruction 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 V1 webhook Public Key endpoint:
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
Next, in order to verify that the 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. ⚡