Skip to content
Snippets Groups Projects
Commit 40dd46fb authored by Rémi PAILHAREY's avatar Rémi PAILHAREY :fork_knife_plate:
Browse files

doc: epgl earliest data fetched

parent 54f2508a
No related branches found
No related tags found
No related merge requests found
Pipeline #94397 passed
Stage: build
Stage: deploy
Hide whitespace changes
Inline Side-by-side
Showing
with 128 additions and 125 deletions
docs/konnectors/egl.md
+ 128
− 125
View file @ 40dd46fb
# 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 |
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment