Newer
Older
This konnector fetches consumptions measures from Grdf Adict 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](https://forge.grandlyon.com/web-et-numerique/llle_project/grdf-adict-konnector).
You should also check Cozy's official documentations for konnectors :
[https://docs.cozy.io/en/tutorials/konnector/getting-started/](https://docs.cozy.io/en/tutorials/konnector/getting-started/)
[https://docs.cozy.io/en/tutorials/konnector/oauth/](https://docs.cozy.io/en/tutorials/konnector/oauth/)
## Grdf Adict Konnector
The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](/proxy/description/) documentation to fully understand all the interactions that will be told below.
All the actions performed by the stack are targetted from pre-registered paramaters, 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 **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description).
- 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 datas, including the pce_id (id of user's meter) that will be needed further to fetch user's datas.
- Konnector starts, fails to find a pce_id in database on first launch therefore decodes the id_token to store the pce_id in db (see [addData](https://docs.cozy.io/en/cozy-konnector-libs/api/#adddata_1)).
- Konnector restarts, this time knowing a pce_id, it fails to fetch datas because the access_token from oauth call has a reduced scope (only scoping for meta data requests).
- Konnector launches a refresh call, the proxy knows to answer it with a _client_credentials_ grant_type call to grdf /access_token.
- Konnector restarts with everyting needed in database to fetch datas and store them in couchdb.
- Further jobs will not need to change scope again and will only ask for refresh tokens.
### Konnector Flow summarized
```plantuml
Start -> Restart: No Pce_id
Restart -> GetData
GetData -> Grdf_Data_Endpoint
GetData <-- Grdf_Data_Endpoint: Token forbidden scope too low
GetData -> Refresh_Call
Refresh_Call -> Proxy
Proxy -> Grdf_Token_Endpoint: client_credential option
Proxy <-- Grdf_Token_Endpoint: new token
GetData <-- Proxy
Restart <-- GetData
Restart -> GetData
GetData -> ProcessData
ProcessData -> StoreData
```
When deleting one's konnector account, src/onDeleteAccount.js is triggered. In order to facilitate a new oauth connection later on. It aims to remove user's consent between its grdf account and the Metropole de Lyon.
To do so, we use the secret credentials stored in account_type grdfgrandlyon.delete (see [cozy offical documentation](https://docs.cozy.io/en/cozy-stack/konnectors-workflow/#secrets-that-are-not-oauth) to know how we create a special account_type secret) to generate an access_token with enough permission to revoke any consents given to the Metropole.
## Launch on standalone
In the project repository type `yarn standalone` to launch the konnector without a cozy stack running.
## Installation
Build the konnector with `yarn build`.
### Install on easy-cozy (development purposes)
`sudo docker cp /home/easy-cozy/fun/grdf-konnector/build/ $container_id:/tmp/grdf-oauth`
`sudo docker-compose exec cozy ./cozy konnectors install grdf-oauth --domain "$alphaDomain" file:///tmp/grdf-oauth $container_id `
### Install on production
Type `yarn deploy` to build on a dedicated branch.
Build branch is stored as a docker image in a registry : [Container Registry](https://forge.grandlyon.com/web-et-numerique/llle_project/grdf-adict-konnector/container_registry).
### Konnector Methods
| Method | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start | Init Function |
| getData | Retrieve data from API |
| processData | Parse data. Remove existing data from DB using hydrateAndFilter, store filtered data and return the list of filtered 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" |
| resetInProgressAggregatedData | Function handling special case.The temporary aggregated data need to be remove in order for the most recent one te be saved. Ex for com.grandlyon.grdf.year : `{ load: 76.712, year: 2020, ... }` need to be replace by `{ load: 82.212, year: 2020, ... }` after grdf data reprocess |