Skip to content
Snippets Groups Projects
Select Git revision
  • renovate/devdependencies-(non-major)
  • renovate/major-react-monorepo
  • master default
3 results
Blame Permalink
enedis.md 9.69 KiB

Enedis Konnector

:::warning DEPRECATED This section of documentation is not relevant anymore, enedis data connect has been replaced with enedis sge :::

This konnector fetches consumption measures from Enedis API. This is an Oauth Konnector, meaning the authentication performed to access all data is made following an Oauth2 protocol. You can clone the project here.

You should also check Cozy's official documentations for konnectors :

The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the proxy documentation to fully understand all the interactions that will be told below.

All the actions performed by the stack are targeted from pre-registered parameters, here is the list of all parameters needed by the stack to perform the Oauth protocol and allow the konnector to fetch data. On its first launch, following the Oauth Client Connect authentication.

  • The cozy stack calls the authentication_endpoint and start the oauth protocol, see proxy doc.
  • The account has now an access_token and an id_token from the oauth call

:::info id token is only given when requesting the token endpoint in _authorization_code grant_type. This token holds several meta data, including the usage_point_id (id of user's meter) that will be needed further to fetch user's data. :::

  • Konnector starts, if no usage_point_id are found in database or fields then proceed as a first launch. Store the usage_point_id in oauth_callback_result in db (see addData).
  • Konnector finds usagepoint_id when starting but token is expired. Proceed to refresh token and restart konnector with usage_point_id in fields params (see _Troubleshooting when asking for refresh token section at the end of the page).

Enedis API

Once you've finished the Oauth protocol and have a valid token, you can go fetch the data. Currently we use the two following endpoints in Ecolyo:

Method : GET

Route : /v4/metering_data/consumption_load_curve

Method : GET

Route : /v4/metering_data/daily_consumption Method : GET

Route : /v4/metering_data/daily_consumption_max_power

"params":
{
    "usage_point_id": "<your-usage-point-id>",
    "start": "YYYY-MM-DD",
    "end": "YYYY-MM-DD",
}
"headers":
{
    "Accept": "application/json",
    "Authorization": "Bearer xxxxxxxxxxx"
}

For more information about Datahub-Enedis API, checkout the Datahub documentation.

Konnector Methods

Method Description
start Init Function
getDailyData Retrieve data from the API. Format: { value: "Wh", "date": "YYYY-MM-DD" }"
startLoadDataProcess Check if history is loaded. If not, call several time the api to retrieve 1 month of history for load data. If yes only call once the api
launchLoadDataProcess Launch process to handle load data
getLoadData Retrieve data from the API. Format: { value: "W", "date": "YYYY-MM-DD hh:mm:ss" }
processData Parse data. Remove existing data from DB using hydrateAndFilter, store filtered data and return the list of filtered data
aggregateMonthAndYearData Aggregate data from daily data to monthly and yearly data
aggregateHourlyData Aggregate data from load data (every 30 min) to Hourly data
storeData Save data in the right doctype db and prevent duplicated keys
formateData Format data for DB storage and remove bad data
buildAggregatedData Retrieve and remove old data for a specific doctype and return an array of aggregated data
buildDataFromKey Format an entry for DB storage using key and value. For year doctype: key = "YYYY". For month doctype: key = "YYYY-MM"
getMaxPower Retrieve data from the maxpower API. Format: { value: "kVA", "date": "YYYY-MM-DD" }
isHistoryLoaded Function checking if the history is loaded
resetInProgressAggregatedData Function handling special case.The temporary aggregated data need to be remove in order for the most recent one to be saved. Ex for com.grandlyon.enedis.year : { load: 76.712, year: 2020, ... } need to be replace by { load: 82.212, year: 2020, ... } after enedis data reprocess

Troubleshooting when asking for refresh token

When a token expires, the konnector will encounter an error when fetching user data, leading to a refresh token request.

Since refresh token requests restart the Konnector, it was decided to add the usage_point_id into the start fields when asking for a refresh token (see line 97).

:::info restart to refresh token

// Line 85
await cozyClient.fetchJSON(
  'POST',
  `/accounts/enedisgrandlyon/${accountId}/refresh`
);

// Line 97
fields.usage_point_id = usage_point_id;

// Line 98
return start(fields, cozyParameters, false);

:::

In fact the usage_point_id still remains in the account collection, but on restart, the konnector loses this._account context leading to an error when searching for usage_point_id in account.

Half-hour data issue

When requesting the load curve api while the half-hour data is not activated, we may have an error response 404 with a message "no data found", which makes the whole data fetching process crash. So instead of making it crash we just log this particular error and avoid the konnector to crash. So we added a condition in line 227, in the checkConsentForLoadCurve function :

if (
  (err.statusCode === 404 || err.code === 404) &&
  err.message.search('no_data_found') > 0
) {
  log('info', 'Handling half-hour error on connection');
  return false;
}