enedis-sge.md

This konnector fetches consumption measures from Enedis SGE SOAP API. 

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/)

# Enedis SGE Konnector

!!! warning "This konnector is in a POC state"

## Enedis context

The API used by this konnector are the one used by all energy providers (edf, total...), this one is supposed to have a high availability. Contrary to enedis oauth konnector, this is a regular auth konnector.

## Technical overview

### Lib used 

- xml2js: Lib allowing easy parsing to json
- easy-soap-request: Lib making soap request

### WSO2

For now enedis API are proxied by WSO1 api manager. You can find documentation and devportal [here](https://apis.grandlyon.fr/devportal).

### Scaffolding 

- Aggregate.js: file holding method responsible for month and year aggregation 
- parsing.js: contain all methods for xml to json parsing and data formatting
- request.js: hold SGE query methods 
- types.js: file containing type definition to allow js type check.
- index.js: main file where default konnector methods are launch (start, ...)

### ts-check

In order to have better comfort while coding, we have enable ts-checking with vs-code. The verification is based on js-doc, please take time to maintain the js-doc.

!!! note "ts-check"
    The ts-check is none blocking. It will only put information in vs-code ide.


### Konnector Methods
| Method | Description |
| ------ | ------ |
| start | Main method of konnector. Handle global flow and init method with provided params |
| getDataStartDate | Retrieve user contract *startDate* in order to request an accurate time range of data |
| getData | Get daily data |
| getMaxPowerData | Get daily Max Power data |
| getHalfHourData | Get half-hour data |
| processData | Given a doctype, parse and format data before storing and aggregating |
| processStartDate | Save startDate and process queries time range |
| storeData | Save data to user's cozy |
| agregateMonthAndYearData | Sum daily data for months and years |

## Dataflow

### Overview

[Lien du schema](https://whimsical.com/sge-tech-DxbYM8DdajRjTr6WZat1bV)

### Authentication

**TODO: Write this part when full implementation will be done.**

Information required: 

- Name
- Surname
- PointID (PDL)
- Full address 

### Fetch Data

In order to get data from the SGE API we have to request the following route :

1. Get user contract startDate

Method : **POST**

Data Route : **enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**

```xml
<soapenv:Body>
    <v2:consulterDonneesTechniquesContractuelles>
        <pointId>${pointId}</pointId>
        <loginUtilisateur>${userLogin}</loginUtilisateur>
        <autorisationClient>true</autorisationClient>
    </v2:consulterDonneesTechniquesContractuelles>
</soapenv:Body>
```

2. Get daily data
3. Get Max Power data
4. Get Half-hour data

The same endpoint is used to get the data. The soap body is the following:

Method : **POST**

Data Route : **enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**

```xml
<soapenv:Body>
    <v2:consulterMesuresDetaillees>
        <demande>
            <initiateurLogin>${userLogin}</initiateurLogin>
            <pointId>${pointId}</pointId>
            <mesuresTypeCode>${mesureType}</mesuresTypeCode>
            <grandeurPhysique>${unit}</grandeurPhysique>
            <soutirage>true</soutirage>
            <injection>false</injection>
            <dateDebut>${startDt}</dateDebut>
            <dateFin>${endDt}</dateFin>
            <mesuresCorrigees>false</mesuresCorrigees>
            <accordClient>true</accordClient>
        </demande>
    </v2:consulterMesuresDetaillees>
</soapenv:Body>
```