From 5b3f8a760e063ea7db16d8d93dde638eb51c2044 Mon Sep 17 00:00:00 2001
From: Bastien DUMONT <bdumont@grandlyon.com>
Date: Tue, 1 Mar 2022 11:25:57 +0100
Subject: [PATCH] fix : several links
---
docs/konnectors/egl.md | 249 +++++++++++++++---------------
docs/konnectors/enedis.md | 8 +-
docs/konnectors/grdf.md | 4 +-
docs/proxy/description.md | 2 +-
docs/proxy/use_cases/enedis.md | 206 ++++++++++++------------
docs/proxy/use_cases/grdfadict.md | 66 ++++----
6 files changed, 267 insertions(+), 268 deletions(-)
diff --git a/docs/konnectors/egl.md b/docs/konnectors/egl.md
index 7e435b5..109e32f 100644
--- a/docs/konnectors/egl.md
+++ b/docs/konnectors/egl.md
@@ -1,125 +1,124 @@
-## EGL Konnector
-
-This konnector fetches consumptions measures from EGL API.
-The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo".
-
-You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/egl-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/)
-
-API Url for Development : [https://agence-rec.eaudugrandlyon.com](https://agence-rec.eaudugrandlyon.com/)
-
-API Url for Production : [https://agence.eaudugrandlyon.com/ws](https://agence.eaudugrandlyon.com/ws)
-
-## Authentication
-
-In order to authenticate to the EGL API we have to request the following route
-
-Method : **POST**
-
-Authentication Route : **/connect.asp**
-
-```json
-"headers":
-{
- {
- "AuthKey": <your-auth-key>,
- "Content-Type": "application/x-www-form-urlencoded"
- }
-}
-```
-
-```json
-"body":
-{
- "mode": "formdata"
- {
- "login": <your-login>,
- "pass": <your-password>
- }
-}
-```
-
-Once you've sent this request the API should answer with a code 100 if everything is ok and provides you a valid **token** and **num_abt** that you will use later in order to get data.
-
-```json
-{
- "codeRetour": 100,
- "libelleRetour": "Connecté",
- "resultatRetour": {
- "num_abt": toto,
- "list_num_abt": [toto, tata]
- "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
- }
-}
-```
-
-## Fetch Data
-
-In order to get data from the EGL API we have to request the following route :
-
-Method : **POST**
-
-Data Route : **/getAllAgregatsByAbonnement.aspx**
-
-```json
-
-"body":
-{
- "mode": "formdata"
- {
- "token": "897555754A703055397897456568776E32704C3953514F5R",
- "num_abt": 1895683,
- "date_debut": MM/JJ/YYYY,
- "date_fin": MM/JJ/YYYY
- }
-}
-```
-
-The dates must be valid dates otherwise you'll get an error
-
-The answer will provide you an array of data day by day with the value got by the water meter 'ValeurIndex' at this moment.
-
-```json
-{
- "codeRetour": 100,
- "libelleRetour": "L'opération a réussi",
- "resultatRetour": [
- {
- "DateReleve": "2020-07-01T00:00:00+02:00",
- "TypeAgregat": "R",
- "ValeurIndex": 562362
- },
- {
- "DateReleve": "2020-07-02T00:00:00+02:00",
- "TypeAgregat": "R",
- "ValeurIndex": 562432
- }
- ]
-}
-```
-
-Daily data is calculated by substracting current valeurIndex day with previous day.
-### TypeAgregats
-
-- "R" means the real value
-- "A" means an anomaly
-- "D" means a water meter changing
-- "V" means data has been estimated on a period
-- "X" marks the start and end of "V" estimated data
-- "T" means pending data
-
-If you're looking for more information about the API, checkout the [complete API documentation](/documents/egl-api-doc.pdf)
-
-### 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 |
-| authenticate | Authentication method. Requires login, password, baseUrl and ApiAuthKey. |
-| storeData | Save data in the right doctype db and prevent duplicated keys |
-| format | Format data for DB storage and remove bad data (former "T" typeagregats remain in response even if the data was added later, leading to duplicated data) |
-| 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.egl.year : `{ load: 76.712, year: 2020, ... }` need to be replace by `{ load: 82.212, year: 2020, ... }` after egl data reprocess |
+## EGL Konnector
+
+This konnector fetches consumptions measures from EGL API.
+The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo".
+
+You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/egl-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/)
+
+- API Url for Development : [https://agence-rec.eaudugrandlyon.com](https://agence-rec.eaudugrandlyon.com/)
+- API Url for Production : [https://agence.eaudugrandlyon.com/ws](https://agence.eaudugrandlyon.com/ws)
+
+## Authentication
+
+In order to authenticate to the EGL API we have to request the following route
+
+Method : **POST**
+
+Authentication Route : **/connect.asp**
+
+```json
+"headers":
+{
+ {
+ "AuthKey": <your-auth-key>,
+ "Content-Type": "application/x-www-form-urlencoded"
+ }
+}
+```
+
+```json
+"body":
+{
+ "mode": "formdata"
+ {
+ "login": <your-login>,
+ "pass": <your-password>
+ }
+}
+```
+
+Once you've sent this request the API should answer with a code 100 if everything is ok and provides you a valid **token** and **num_abt** that you will use later in order to get data.
+
+```json
+{
+ "codeRetour": 100,
+ "libelleRetour": "Connecté",
+ "resultatRetour": {
+ "num_abt": toto,
+ "list_num_abt": [toto, tata]
+ "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+ }
+}
+```
+
+## Fetch Data
+
+In order to get data from the EGL API we have to request the following route :
+
+Method : **POST**
+
+Data Route : **/getAllAgregatsByAbonnement.aspx**
+
+```json
+
+"body":
+{
+ "mode": "formdata"
+ {
+ "token": "897555754A703055397897456568776E32704C3953514F5R",
+ "num_abt": 1895683,
+ "date_debut": MM/JJ/YYYY,
+ "date_fin": MM/JJ/YYYY
+ }
+}
+```
+
+The dates must be valid dates otherwise you'll get an error
+
+The answer will provide you an array of data day by day with the value got by the water meter 'ValeurIndex' at this moment.
+
+```json
+{
+ "codeRetour": 100,
+ "libelleRetour": "L'opération a réussi",
+ "resultatRetour": [
+ {
+ "DateReleve": "2020-07-01T00:00:00+02:00",
+ "TypeAgregat": "R",
+ "ValeurIndex": 562362
+ },
+ {
+ "DateReleve": "2020-07-02T00:00:00+02:00",
+ "TypeAgregat": "R",
+ "ValeurIndex": 562432
+ }
+ ]
+}
+```
+
+Daily data is calculated by substracting current valeurIndex day with previous day.
+### TypeAgregats
+
+- "R" means the real value
+- "A" means an anomaly
+- "D" means a water meter changing
+- "V" means data has been estimated on a period
+- "X" marks the start and end of "V" estimated data
+- "T" means pending data
+
+If you're looking for more information about the API, checkout the [complete API documentation](/documents/egl-api-doc.pdf)
+
+### 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 |
+| authenticate | Authentication method. Requires login, password, baseUrl and ApiAuthKey. |
+| storeData | Save data in the right doctype db and prevent duplicated keys |
+| format | Format data for DB storage and remove bad data (former "T" typeagregats remain in response even if the data was added later, leading to duplicated data) |
+| 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.egl.year : `{ load: 76.712, year: 2020, ... }` need to be replace by `{ load: 82.212, year: 2020, ... }` after egl data reprocess |
diff --git a/docs/konnectors/enedis.md b/docs/konnectors/enedis.md
index 2bf0677..887f56e 100644
--- a/docs/konnectors/enedis.md
+++ b/docs/konnectors/enedis.md
@@ -7,12 +7,12 @@ You should also check Cozy's official documentations for konnectors :
## Enedis 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.md) documentation to fully understand all the interactions that will be told below.
+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 authentification.
-- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description.md).
+- 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 ""
@@ -24,8 +24,8 @@ This token holds several meta datas, including the usage_point_id (id of user's
## Enedis API
-API Url for Production : [https://gw.prd.api.enedis.fr](https://gw.prd.api.enedis.fr)
-API url for Development : [https://gw.hml.api.enedis.fr](https://gw.hml.api.enedis.fr)
+- API Url for Production : [https://gw.prd.api.enedis.fr](https://gw.prd.api.enedis.fr)
+- API url for Development : [https://gw.hml.api.enedis.fr](https://gw.hml.api.enedis.fr)
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:
diff --git a/docs/konnectors/grdf.md b/docs/konnectors/grdf.md
index b1eab9b..43ea91c 100644
--- a/docs/konnectors/grdf.md
+++ b/docs/konnectors/grdf.md
@@ -7,7 +7,7 @@ You should also check Cozy's official documentations for konnectors :
## 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.md) documentation to fully understand all the interactions that will be told below.
+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.
@@ -15,7 +15,7 @@ All the actions performed by the stack are targetted from pre-registered paramat
On its first launch, following the Oauth Client Connect authentification.
-- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description.md).
+- 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 ""
diff --git a/docs/proxy/description.md b/docs/proxy/description.md
index d5d089a..89d255e 100644
--- a/docs/proxy/description.md
+++ b/docs/proxy/description.md
@@ -1,5 +1,5 @@
This section of documentation refers to the Oauth protocols working hand in hand with our custom proxy and the cozy-stack.
-To fully understand its whereabouts, you should also look at the [enedis konnector](/konnectors/enedis.md) and [grdf konnector](/konnectors/grdf.md) documentation.
+To fully understand its whereabouts, you should also look at the [enedis konnector](/konnectors/enedis/) and [grdf konnector](/konnectors/grdf/) documentation.
!!! info "proxy code source"
Feel free to check the proxy [code](https://forge.grandlyon.com/pocs/cozy/cozy-oauth-proxy) at all time when reading this documentation.
diff --git a/docs/proxy/use_cases/enedis.md b/docs/proxy/use_cases/enedis.md
index 8cc8f46..54c1697 100644
--- a/docs/proxy/use_cases/enedis.md
+++ b/docs/proxy/use_cases/enedis.md
@@ -1,104 +1,104 @@
-### Enedis Data Connect
-
-!!! info "enedis documentation"
- Create an account on https://datahub-enedis.fr/ to explore all the services exposed by Enedis.
-
- [Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger.
-
- [Api healthcheck](https://datahub-enedis.fr/data-connect/ressources/etat-des-services/).
-
-Regarding Enedis, two endpoints are exposed:
-
-#### Authorize
-##### /dataconnect/v1/oauth2/authorize
-
-<table>
- <colgroup>
- <col width="30%">
- <col width="70%">
- </colgroup>
- <thead>
- <tr class="header">
- <th>Paramater</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>client_id</td>
- <td>Unique identifier of the Application</td>
- </tr>
- <tr>
- <td>response_type</td>
- <td>Authorization scenario requested. It will always be "code" as Enedis implemented a code grant authorization</td>
- </tr>
- <tr>
- <td>state</td>
- <td>Security parameter allowing to maintain the state between the request and the redirection. ** Maximum length of 100 characters ! **</td>
- </tr>
- <tr>
- <td>duration</td>
- <td>Duration of the consent requested by the application, ISO 8601 format. It cannot exceed 3 years</td>
- </tr>
- </tbody>
-</table>
-
-!!! important "Important"
- The response targets the redirect-uri registered with Enedis (the redirect-uri is our proxy and the response will be explained in details further below when explaining the proxy endpoints mechanics).
-
-#### Token
-##### /v1/oauth2/token
-
-<table>
- <colgroup>
- <col width="30%">
- <col width="70%">
- </colgroup>
- <thead>
- <tr class="header">
- <th>Paramater</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>redirect_uri</td>
- <td>URI defined when the application was created. Must be secured in https</td>
- </tr>
- <tr>
- <td>content-type</td>
- <td>application/json</td>
- </tr>
- <tr>
- <td>grant_type</td>
- <td>Authorization type to get an access token. This must be set to “authorization_code” when using an authorization code, and to “refresh_token” when using a refresh token</td>
- </tr>
- <tr>
- <td>client_id</td>
- <td>Unique identifier of the Application</td>
- </tr>
- <tr>
- <td>client_secret</td>
- <td>Secret of the client application, associated with its client_id</td>
- </tr>
- <tr>
- <td>refresh_token</td>
- <td>Refresh token returned to the previous POST request to the /token endpoint</td>
- </tr>
- <tr>
- <td>code</td>
- <td>Authorization code returned to the GET request of /authorize endpoint</td>
- </tr>
- </tbody>
-</table>
-
-On success, response will contain **access_token** or **refresh_token**, **usage_point_id** among other things. All informations will be stored by the cozy-stack in a cozy-accounts database.
-
-#### Consent Handling
-
-Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
-User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
-
-If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
-
+### Enedis Data Connect
+
+!!! info "enedis documentation"
+ Create an account on [https://datahub-enedis.fr/](https://datahub-enedis.fr/) to explore all the services exposed by Enedis.
+
+ [Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger.
+
+ [Api healthcheck](https://datahub-enedis.fr/data-connect/ressources/etat-des-services/).
+
+Regarding Enedis, two endpoints are exposed:
+
+#### Authorize
+##### /dataconnect/v1/oauth2/authorize
+
+<table>
+ <colgroup>
+ <col width="30%">
+ <col width="70%">
+ </colgroup>
+ <thead>
+ <tr class="header">
+ <th>Paramater</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>client_id</td>
+ <td>Unique identifier of the Application</td>
+ </tr>
+ <tr>
+ <td>response_type</td>
+ <td>Authorization scenario requested. It will always be "code" as Enedis implemented a code grant authorization</td>
+ </tr>
+ <tr>
+ <td>state</td>
+ <td>Security parameter allowing to maintain the state between the request and the redirection. ** Maximum length of 100 characters ! **</td>
+ </tr>
+ <tr>
+ <td>duration</td>
+ <td>Duration of the consent requested by the application, ISO 8601 format. It cannot exceed 3 years</td>
+ </tr>
+ </tbody>
+</table>
+
+!!! important "Important"
+ The response targets the redirect-uri registered with Enedis (the redirect-uri is our proxy and the response will be explained in details further below when explaining the proxy endpoints mechanics).
+
+#### Token
+##### /v1/oauth2/token
+
+<table>
+ <colgroup>
+ <col width="30%">
+ <col width="70%">
+ </colgroup>
+ <thead>
+ <tr class="header">
+ <th>Paramater</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>redirect_uri</td>
+ <td>URI defined when the application was created. Must be secured in https</td>
+ </tr>
+ <tr>
+ <td>content-type</td>
+ <td>application/json</td>
+ </tr>
+ <tr>
+ <td>grant_type</td>
+ <td>Authorization type to get an access token. This must be set to “authorization_code” when using an authorization code, and to “refresh_token” when using a refresh token</td>
+ </tr>
+ <tr>
+ <td>client_id</td>
+ <td>Unique identifier of the Application</td>
+ </tr>
+ <tr>
+ <td>client_secret</td>
+ <td>Secret of the client application, associated with its client_id</td>
+ </tr>
+ <tr>
+ <td>refresh_token</td>
+ <td>Refresh token returned to the previous POST request to the /token endpoint</td>
+ </tr>
+ <tr>
+ <td>code</td>
+ <td>Authorization code returned to the GET request of /authorize endpoint</td>
+ </tr>
+ </tbody>
+</table>
+
+On success, response will contain **access_token** or **refresh_token**, **usage_point_id** among other things. All informations will be stored by the cozy-stack in a cozy-accounts database.
+
+#### Consent Handling
+
+Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
+User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
+
+If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
+
Ecolyo can warn the user that the service is unable to continue and ask to give new consent.
\ No newline at end of file
diff --git a/docs/proxy/use_cases/grdfadict.md b/docs/proxy/use_cases/grdfadict.md
index 632afca..f11db60 100644
--- a/docs/proxy/use_cases/grdfadict.md
+++ b/docs/proxy/use_cases/grdfadict.md
@@ -1,33 +1,33 @@
-### Grdf Adict
-
-!!! info "grdf documentation"
- Visit https://site.grdf.fr/web/grdf-adict/technique to explore all the services exposed by Grdf.
- > Prod endpoints are: https://sofit-sso-oidc.grdf.fr/openam/
-
-Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
-
-!!! warning "Oauth connexion still in Beta"
- Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
-
-#### Authorize
-##### /oauth2/realms/externeGrdf/authorize
-
-#### Token
-##### /oauth2/realms/externeGrdf/access_token
-
-
-The */access_token* endpoint can be called with two different *grant_type* parameter.
-
- - *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
- - *client_credentials* gives only the access token allowing us to request the data service.
-
- The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
-
-#### Consent Handling
-
-Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
-##### Optional: Revoke consent from external applications
-
-It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
-
-**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
+### Grdf Adict
+
+!!! info "grdf documentation"
+ Visit [https://sites.grdf.fr/web/portail-api-grdf-adict/documentation-grdf-adict](https://sites.grdf.fr/web/portail-api-grdf-adict/documentation-grdf-adict) to explore all the services exposed by Grdf.
+ > Prod endpoints are: [https://sofit-sso-oidc.grdf.fr/openam/](https://sofit-sso-oidc.grdf.fr/openam/)
+
+Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
+
+!!! warning "Oauth connexion still in Beta"
+ Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
+
+#### Authorize
+##### /oauth2/realms/externeGrdf/authorize
+
+#### Token
+##### /oauth2/realms/externeGrdf/access_token
+
+
+The */access_token* endpoint can be called with two different *grant_type* parameter.
+
+ - *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
+ - *client_credentials* gives only the access token allowing us to request the data service.
+
+ The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
+
+#### Consent Handling
+
+Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
+##### Optional: Revoke consent from external applications
+
+It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
+
+**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
--
GitLab