diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 23129b2872cbffe4ee7f53544af8945ae95f5cde..089db7c75c8c5b1f42e65d4d039f4ec9317aee61 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -9,12 +9,27 @@ variables:
stages:
- build
+ - deploy
build_master:
stage: build
+ tags:
+ - build-push-to-registry
only:
- master
script:
- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
- docker build -t registry.forge.grandlyon.com/web-et-numerique/llle_project/self-data-technical-doc .
- - docker push registry.forge.grandlyon.com/web-et-numerique/llle_project/self-data-technical-doc
\ No newline at end of file
+ - docker push registry.forge.grandlyon.com/web-et-numerique/llle_project/self-data-technical-doc
+
+deploy_master:
+ stage: deploy
+ tags:
+ - cozy
+ only:
+ - master
+ script:
+ - cd /root/self-data-technical-doc
+ - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
+ - docker-compose pull
+ - docker-compose up -d doc-self-data
\ No newline at end of file
diff --git a/docs/ecolyo/application/services.md b/docs/ecolyo/application/services.md
index 71bad7d5029f15e7b4524d6dd51217882caabc4c..9dd6dde8a4df76df7fb002c525992b57a490780d 100644
--- a/docs/ecolyo/application/services.md
+++ b/docs/ecolyo/application/services.md
@@ -1,19 +1,26 @@
!!! warning ""
:construction: Section under Construction :construction:
-## Cron Services - Monthly Report
+## Cron Services
In order to build an automated task within our cozy-stack, we can create *services* which are javascript files called from a trigger job.
-On Ecolyo, we add a trigger that is launched every month with a *cron* attribute. On that trigger we link a .js script then we instanciate this script with cozy-client.
+For instance on Ecolyo, to schedule a mail that alert the user a new **monthly report** is available in the application, we add a trigger that is launched every month with a *cron* attribute. On that trigger we link a .js script then we instanciate this script with cozy-client.
+### Manifest config example
-### Service.js
+
-### Manifest Config
+File location is determined after the build, see [here](https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo/-/tree/build/services/monthlyReport).
-
+!!! note "Cron"
+ See the cron definition at [cozy-stack](https://docs.cozy.io/en/cozy-stack/jobs/#cron-syntax).
+
+### Services
+
+Located under **src\targets\services**
+
+#### Monthly report notification
-!!! note "Cron Definition"
- [cozy-stack](https://docs.cozy.io/en/cozy-stack/jobs/#cron-syntax)
+Fetches metadata to customize the mail (Public name, instance url).
-### Testing
\ No newline at end of file
+Send mail containing a link to the user instance so that he can be warned about the update of its monthly report and visualize it.
diff --git a/docs/ecolyo/functionalities/challenge.md b/docs/ecolyo/functionalities/challenge.md
index 2c6a9345d84c58047e3cf5f80de04397548d3e58..dbff100220856c89df9f969b98ddcd1316a1b72b 100644
--- a/docs/ecolyo/functionalities/challenge.md
+++ b/docs/ecolyo/functionalities/challenge.md
@@ -5,6 +5,7 @@ This section explain all the functionnalities in the challenge part
## Quiz
+A quiz includes 4 basic questions and one custom question.
### Basic Question
All basics Questions are created in the quizEntity.json. We have to add :
@@ -13,9 +14,12 @@ All basics Questions are created in the quizEntity.json. We have to add :
- description => Explain the question
- source => Source of the explanaition
+This questions and answers are in random order.
+
In the question page the user have to select an answer and click validate.
Then, he sees the right answer and a modal with the explanation and the source. After this modal, he goes to the next question.
Depends on the answer, the question result state is set either correct or incorrect.
+If it is a right answer, the quiz result is incremented by one.
### Custom Question
@@ -27,6 +31,8 @@ We get all this information to determine the custom question (All information ar
Then, he generate two randoms answers following the right answer.
A user can stop during a quiz and picks up where he left off. To define where the user left off, we have to check if at least one of the question result status is unlocked.
+
+Once the custom question is answered, the quiz state is set to done. Then, the user sees his result and his earned stars. He can also retry or go back to the challenge page.
## Exploration
Exploration is a feature which in the user got to do an action in order to help him to discover all features of this app.
diff --git a/docs/ecolyo/getting_started/launch_local_application.md b/docs/ecolyo/getting_started/launch_local_application.md
index 311263ae67f4bdda3b6e040e76a802c80b79b497..615851b422341a2491484b596fc3f97d73e189e3 100644
--- a/docs/ecolyo/getting_started/launch_local_application.md
+++ b/docs/ecolyo/getting_started/launch_local_application.md
@@ -194,7 +194,7 @@ First update the Bearer and cozysessid information from the script:
```
To obtain your own Bearer and cozysessid you need to have the application launched and display the web console (F12) in your navigator and select the Network tab. Just select one request and retrieve information for Request Header:
-
+
Next launch the script :
diff --git a/docs/ecolyo/konnectors/enedis.md b/docs/ecolyo/konnectors/enedis.md
index 34669c2102edad427059faadd7e44a7ab416928e..b3db55bd8f665a6ea91cd8aa46bd7b32edb2115d 100644
--- a/docs/ecolyo/konnectors/enedis.md
+++ b/docs/ecolyo/konnectors/enedis.md
@@ -19,15 +19,11 @@ On its first launch, following the Oauth Client Connect authentification.
- The account has now an access_token and an id_token from the oauth call
!!! info ""
-id*token is only given when requesting the token endpoint in \_authorization_code* grant_type.
-This token holds several meta datas, including the pce_id (id of user's meter) that will be needed further to fetch user's datas.
+ id token is only given when requesting the token endpoint in \_authorization_code grant_type.
+ This token holds several meta datas, including the usage_point_id (id of user's meter) that will be needed further to fetch user's datas.
-- Konnector starts, fails to find a pce_id in database on first launch therefore decodes the id_token to store the pce_id in db (see [addData](https://docs.cozy.io/en/cozy-konnector-libs/api/#adddata_1)).
-- Konnector restarts, this time knowing a pce_id, it fails to fetch datas because the access_token from oauth call has a reduced scope (only scoping for meta data requests).
-- Konnector launches a refresh call, the proxy knows to answer it with a _client_credentials_ grant_type call to grdf /access_token.
-- Konnector restarts with everyting needed in database to fetch datas and store them in couchdb.
-
-- Further jobs will not need to change scope again and will only ask for refresh tokens.
+- Konnector starts, if no usage_point_id are found in database or fields then proceed as a first launch. Store the usage_point_id in oauth_callback_result in db (see [addData](https://docs.cozy.io/en/cozy-konnector-libs/api/#adddata_1)).
+- Konnector finds usage_point_id when starting but token is expired. Proceed to refresh token and restart konnector with usage_point_id in fields params (see *Troubleshooting when asking for refresh token* section at the end of the page).
## Enedis API
diff --git a/docs/ecolyo/konnectors/grdf.md b/docs/ecolyo/konnectors/grdf.md
index 8966c0133ae3f594e622003302732ed965dd2293..81f1af6b3008d696e54a0bd7206655431f2b2bb4 100644
--- a/docs/ecolyo/konnectors/grdf.md
+++ b/docs/ecolyo/konnectors/grdf.md
@@ -32,13 +32,28 @@ This token holds several meta datas, including the pce_id (id of user's meter) t
- Further jobs will not need to change scope again and will only ask for refresh tokens.
-### Flow summarized
-
-
+### Konnector Flow summarized
+
+```plantuml
+ Start -> Restart: No Pce_id
+ Restart -> GetData
+ GetData -> Grdf_Data_Endpoint
+ GetData <-- Grdf_Data_Endpoint: Token forbidden scope too low
+ GetData -> Refresh_Call
+ Refresh_Call -> Proxy
+ Proxy -> Grdf_Token_Endpoint: client_credential option
+ Proxy <-- Grdf_Token_Endpoint: new token
+ GetData <-- Proxy
+ Restart <-- GetData
+ Restart -> GetData
+ GetData -> ProcessData
+ ProcessData -> StoreData
+```
!!! info "to do"
-:construction: Request PCE's frequency :construction:
-Grdf owns different type of meters, some are read twice a year (every six months therefore called 6M), others are 1M or 1D
+ :construction: Add request PCE's frequency :construction:
+
+ Grdf owns different type of meters, some are read twice a year (every six months therefore called 6M), others are 1M or 1D. Ecolyo could warn the user if its meter is not suited for the application use.
## Launch on standalone
diff --git a/docs/proxy/description.md b/docs/proxy/description.md
index 5aedd75634a9ff055617e26379a71a0a3bc398a4..e2201012bc94b6ce19f952c2c4cd599b5edbf019 100644
--- a/docs/proxy/description.md
+++ b/docs/proxy/description.md
@@ -2,7 +2,7 @@
:construction: Section under Construction :construction:
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](../ecolyo/konnectors/enedis.md) and [grdf konnector](../ecolyo/konnectors/grdf.md) 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.
@@ -13,126 +13,7 @@ To access customer data, one must first obtain customer authorization. This auth
These APIs implement Oauth 2.0 protocol, it requires authentication from the customer along with its given consent.
-### 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
-
-Regarding Enedis, two endpoints are exposed:
-
-#### /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).
-
-#### /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.
-
-### 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.
-
-#### /oauth2/realms/externeGrdf/authorize
-
-#### /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.
-
-#### Optional: Revoke Consent
-
-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}
-
+See both **[Enedis](./use_cases/enedis.md)** and **[Grdf](./use_cases/grdfadict.md)** use cases before going further.
### Cozy Oauth Protocol
!!! info "cozy oauth flow documentation"
@@ -223,7 +104,16 @@ With that in mind, the proxy is now the one calling the auth and token provider
#### Proxy flow
-stack -> proxy/auth -> provider/auth -> proxy/redirect -> stack -> proxy/token -> provider/token
+```plantuml
+ Stack -> Proxy: calls
+ Proxy -> Provider: calls
+ Proxy <-- Provider: responds with oauth code on proxy/redirect
+ Stack <-- Proxy: redirect to user instance
+ Stack -> Proxy: calls
+ Proxy -> Provider: calls for token or refresh
+ Proxy <-- Provider: responds
+ Stack <-- Proxy: token
+```
## Proxy Code Explained
diff --git a/docs/proxy/use_cases/enedis.md b/docs/proxy/use_cases/enedis.md
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..732bc1d5dd4d62a054ad5b27cc730d55c65d9687 100644
--- a/docs/proxy/use_cases/enedis.md
+++ b/docs/proxy/use_cases/enedis.md
@@ -0,0 +1,101 @@
+### 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
+
+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 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..632afca48a3c9c9eaadc03f8e0fc8420ca9701e5 100644
--- a/docs/proxy/use_cases/grdfadict.md
+++ b/docs/proxy/use_cases/grdfadict.md
@@ -0,0 +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}**
diff --git a/mkdocs.yml b/mkdocs.yml
index df5d7b9ceeccef81f1b0f3bc2ee629dca03bd0ea..d53128aad3b98cdb5ade2b308badc17c69e67f07 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,6 +14,8 @@ theme:
markdown_extensions:
- admonition
+ - plantuml_markdown:
+ server: http://www.plantuml.com/plantuml
- attr_list
- pymdownx.emoji
@@ -23,7 +25,31 @@ extra_css:
nav:
- Home: index.md
- Pilote:
- - Introduction: pilote/index.md
+ - Pilote - TS - Back:
+ - Index: pilote/Pilote - TS - Back/index.md
+ - Application:
+ - Deploy: pilote/Pilote - TS - Back/application/deploy.md
+ - Getting Started:
+ - Launch the application on local: pilote/Pilote - TS - Back/getting_started/launch_local_application.md
+ - Setup your environment: pilote/Pilote - TS - Back/getting_started/setup_your_environment.md
+ - Project Architecture: pilote/Pilote - TS - Back/project_architecture/architecture.md
+ - Pilote - TS - Front:
+ - Index: pilote/Pilote - TS - Front/index.md
+ - Application:
+ - Deploy: pilote/Pilote - TS - Front/application/deploy.md
+ - Getting Started:
+ - Launch the application on local: pilote/Pilote - TS - Front/getting_started/launch_local_application.md
+ - Pilote - TS - Usager:
+ - Application:
+ - Deploy: pilote/Pilote - Usager/application/deploy.md
+ - Doctypes: pilote/Pilote - Usager/application/doctypes.md
+ - Gitflow: pilote/Pilote - Usager/application/gitflow.md
+ - Scaffolding: pilote/Pilote - Usager/application/scaffolding.md
+ - Services: pilote/Pilote - Usager/application/services.md
+ - Store: pilote/Pilote - Usager/application/store.md
+ - Getting Started:
+ - Launch local doctypes: pilote/Pilote - Usager/getting_started/launch_local_doctypes.md
+ - Launch local services: pilote/Pilote - Usager/getting_started/launch_local_services.md
- Ecolyo:
- Introduction: ecolyo/index.md
- Getting started: