Asset Integration Tutorial

Introduction

Integrating with Piclo Flex to manage your Assets can help ensure your Asset details are up-to-date, and put you in a good position to bid into upcoming Competitions. This tutorial will guide you through the actions you can perform on Assets, namely: Create, Update and Fetch.

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 for generating a Bearer token: https://docs.picloflex.com/#tag/authtoken

Actions

1. Create an Asset

A POST request to the V1 Assets create endpoint containing a JSON representation of an Asset resource adds a new Asset in Piclo Flex with those attributes.

All the fields marked as 'required' in the Assets API fields reference must be included to successfully add a new Asset. Be aware that either postcode or latitude and longitude must be included. You can also include any of the optional fields.

Please note further Asset information may be required from an System Operator, which can be added at a later point (see 3. Update your Asset).

You also need to reference your “Flex Provider ID”. This was likely given to you with your machine user credentials, or can be retrieved from the V1 Flex Provider endpoint. Sometimes this is referred to as your "Org ID".

Assets you create via the API will be treated as real Assets on Piclo Flex. Use the archived value for the status field for test Assets to ensure they're excluded from Competition qualification.

curl --request POST https://api.picloflex.com/assets/v1/ \ 
–header 'Content-Type: application/json' –header 'Authorization: Bearer XXXX' \
–data '{"provider": "<YOUR_ORG_ID>", "ref": "asset001","name": "My First Asset", "status": "archived", "asset_category": "renewable", "asset_type": "onshore_wind", "voltage_level": "22.00", "country_code": "GB", "postcode": "SW1A 1AA"}'

A JSON representation of the newly created Asset will be returned, with the read-only id, created and modified fields added and default values for any optional fields that weren't included in the request populated by Piclo Flex.

2. Read your Asset

a. Fetch one

The id field in the response in the previous ‘Create’ step is Piclo Flex's internal reference for your Asset. A specific Asset can be read with a GET request to the V1 Assets fetch by ID endpoint:

curl --request GET https://api.picloflex.com/assets/v1/{Asset ID}/ --header 'Authorization: Bearer XXXXXX'

The response will contain the same Asset representation you saw previously at the ‘Create’ step.

b. Fetch all

Alternatively, you can retrieve all of your Assets registered in Piclo Flex with one call. This can be done by calling the V1 Assets fetch all endpoint (optionally adding some filter parameters if you wish):

curl --request GET https://api.picloflex.com/assets/v1/ --header 'Authorization: Bearer XXXXXX'

The returned JSON contains a list of Asset resources, each representing one of your organisation's Assets as defined in Piclo Flex. If you don’t have any Assets registered in Piclo Flex, an empty list will be returned.

3. Update your Asset

An Asset can be updated with a PATCH request to the V1 Assets update endpoint. Updates can be partial, i.e. you can provide just the fields you want to change.

For example, changing the connection_status from planned to energised:

curl --request PATCH https://api.picloflex.com/assets/v1/{Asset ID}/ –data '{"connection_status": "energised"}' –header 'Content-Type: application/json' –header 'Authorization: Bearer XXXXX'

The response will contain the full Asset representation including the change you've just made.

4. Planned Assets

It’s worth noting that the tutorial has focussed on “Flex Assets” so far. All of the above operations can also be performed on a “Planned Asset” through the V1 Planned Asset API.

Conceptually, a Planned Asset is very similar to a “Flex Asset”. However, the key difference is that a Planned Asset doesn’t exist yet. A Planned Asset needs to be created against a Competition - stating the competition_reference and operator_name for which the Planned Asset is for. Also, we don't require quite so many details about a Planned Asset.