egl.md

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.

You should also check Cozy's official documentations for konnectors : https://docs.cozy.io/en/tutorials/konnector/getting-started/

API Url for Development : https://agence-rec.eaudugrandlyon.com

API Url for Production : 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

"headers":
{
	{
		"AuthKey": <your-auth-key>,
		"Content-Type": "application/x-www-form-urlencoded"
	}
}

"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.

{
  "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

"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.

{
  "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

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