From 40dd46fb5910d50534036249f9a50092d53f932a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20PAILHAREY?= <rpailharey@grandlyon.com>
Date: Tue, 5 Mar 2024 08:13:37 +0000
Subject: [PATCH] doc: epgl earliest data fetched
---
docs/konnectors/egl.md | 253 +++++++++++++++++++++--------------------
1 file changed, 128 insertions(+), 125 deletions(-)
diff --git a/docs/konnectors/egl.md b/docs/konnectors/egl.md
index fad1deb..e516b82 100644
--- a/docs/konnectors/egl.md
+++ b/docs/konnectors/egl.md
@@ -1,125 +1,128 @@
-# EGL Konnector
-
-[EGL repository](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/egl-konnector).
-
-This konnector fetches consumption 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 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": "xxxxxxxxxxx"
- }
-}
-```
-
-## 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/DD/YYYY",
- "date_fin": "MM/DD/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 subtracting 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 to 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
+
+[EGL repository](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/egl-konnector).
+
+This konnector fetches consumption 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 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": "xxxxxxxxxxx"
+ }
+}
+```
+
+## Fetch Data
+
+!!! warning "The earliest data that can be fetched is November 2022 (not 3 years) due to migration from EGL to EPGL"
+
+
+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/DD/YYYY",
+ "date_fin": "MM/DD/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 subtracting 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 to 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 |
--
GitLab