From 94d8f021db47938e705b52b51931c58126f34c89 Mon Sep 17 00:00:00 2001
From: Yoan VALLET <ext.sopra.yvallet@grandlyon.com>
Date: Wed, 19 May 2021 16:27:16 +0200
Subject: [PATCH] review services for ecolyo
---
docs/ecolyo/application/services.md | 46 -----------
.../functionalities/usage_events_tracking.md | 72 ++++++++++++++----
.../services/aggregator_usage_events.md | 18 +++++
docs/ecolyo/services/index.md | 19 +++++
.../services/monthly_report_notification.md | 26 +++++++
.../services}/monthly-service.png | Bin
mkdocs.yml | 4 +
7 files changed, 125 insertions(+), 60 deletions(-)
delete mode 100644 docs/ecolyo/application/services.md
create mode 100644 docs/ecolyo/services/aggregator_usage_events.md
create mode 100644 docs/ecolyo/services/index.md
create mode 100644 docs/ecolyo/services/monthly_report_notification.md
rename docs/{ecolyo/application => img/services}/monthly-service.png (100%)
diff --git a/docs/ecolyo/application/services.md b/docs/ecolyo/application/services.md
deleted file mode 100644
index 9fba35a..0000000
--- a/docs/ecolyo/application/services.md
+++ /dev/null
@@ -1,46 +0,0 @@
-## 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.
-
-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
-
-
-
-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).
-
-## Ecolyo services
-
-Located under **src\targets\services**
-
-### Monthly report notification
-
-#### Definition of the service
-The service will run the 3rd of each month at 10.00 am, as defined in the manifest:
-
-```
-"monthlyReportNotification": {
- "type": "node",
- "file": "services/monthlyReportNotification/ecolyo.js",
- "trigger": "@cron 0 0 10 3 * *"
- }
-```
-#### Main responsabilities of the service
-
-The service is reponsible of sending a mail to user to warn him about the availability of a new information in the Analyse.
-
-Main steps are the following:
- - Check the "sendReportNotification" attribute in the com.grandlyon.ecolyo.profile doctype. If true, service will continue, else it will stop.
- - Fetches metadata to customize the mail (Public name, instance url).
- - Build the mail.
- - Send the mail.
-
-### Sending mail
-
-Doc of cozy for sendmail worker: https://docs.cozy.io/en/cozy-stack/workers/#sendmail-worker
-
-!!! Send mail in local
- In local you can use the mail hog tools to see the mail sent by the stack using http://cozy.tools:8025/
\ No newline at end of file
diff --git a/docs/ecolyo/functionalities/usage_events_tracking.md b/docs/ecolyo/functionalities/usage_events_tracking.md
index 4f9acef..dd28afb 100644
--- a/docs/ecolyo/functionalities/usage_events_tracking.md
+++ b/docs/ecolyo/functionalities/usage_events_tracking.md
@@ -2,31 +2,75 @@
This section explains how the application is tracking usage events. Here are the main step:
-- All events are stored in the instance db
-- A service is responsible of the calculation of ANONYMIZED indicators. These indicators are then sent to a remote docType.
+- All events are stored during the use of the application in the doctype **com.grandlyon.ecolyo.usageevents**
+- A service is responsible of the aggregation of these events to create ANONYMIZED indicators. These indicators are then sent to a remote docType.
## Usage events collection
-Here are the list of collected usage event:
+During the use of the application we stored some events link to an user action. Here are the list of collected usage events:
| Category | Type | Target | Result | Context | Description |
| ----------- | ------------------------------ | -------------- | -------------------- | --------------------- | ----------------------------------------- |
| Connection | ConnectionEvent | | | "desktop" or "mobile" | User connects to the application. |
-| Navigation | NavigationEvent | Page | | | User navigates to a targeted page. |
-| Konnector | KonnectorConnectEvent | Konnector | "success" or "error" | | User connects a konnector. |
-| Konnector | KonnectorRefreshEvent | Konnector | "success" or "error" | | User refreshes a konnector. |
-| Challenge | ChallengeLaunchEvent | Challenge id | | | User launches a challenge. |
-| Challenge | ChallengeEndEvent | Challenge id | | | User ends a challenge. |
-| Duel | DuelLaunchEvent | Duel id | | Challenge id | User launches a duel. |
-| Duel | DuelEndEvent | Duel id | | Challenge id | User ends a duel. |
-| Quiz | QuizEndEvent | Quiz id | starsNumber | Challenge id | User ends a quiz. |
-| Exploration | ExplorationEndEvent | Exploration id | | Challenge id | User ends an exploration. |
-| Action | ActionChangeEvent | Action id | | Challenge id | User change action's ecogesture. |
-| Action | ActionEndEvent | Action id | | Challenge id | User ends a action. |
+| Navigation | NavigationEvent | Page_name | | | User navigates to a targeted page. |
+| Konnector | KonnectorConnectEvent | Konnector_slug | "success" or "error" | | User connects a konnector. |
+| Konnector | KonnectorRefreshEvent | Konnector_slug | "success" or "error" | | User refreshes a konnector. |
+| Challenge | ChallengeLaunchEvent | Challenge_id | | | User launches a challenge. |
+| Challenge | ChallengeEndEvent | Challenge_id | | | User ends a challenge. |
+| Duel | DuelLaunchEvent | Duel_id | | Challenge_id | User launches a duel. |
+| Duel | DuelEndEvent | Duel_id | | Challenge_id | User ends a duel. |
+| Quiz | QuizEndEvent | Quiz_id | starsNumber | Challenge_id | User ends a quiz. |
+| Exploration | ExplorationEndEvent | Exploration_id | | Challenge_id | User ends an exploration. |
+| Action | ActionChangeEvent | Action_id | | Challenge_id | User change action's ecogesture. |
+| Action | ActionEndEvent | Action_id | | Challenge_id | User ends a action. |
| Profile | ProfileSetEvent | | | | User fills in its profile. |
| Consumption | ConsumptionCompareEvent | | | Fluid / TimeStep | User compares its consumption. |
| Consumption | ConsumptionChangeTimeStepEvent | TimeStep | | Fluid | User changes timeStep of its consumption. |
| Consumption | ConsumptionInteracteEvent | | | Fluid / TimeStep | User selects a consumption on the chart. |
+All events are stored with the *aggregated* flag to false to allow the identification of new events.
+
## Usage events aggregator service
+## Functionnalities
+
+The service will retrieve all new events by filter on the *aggregated* flag to **false** and the event date before than today.
+For each aggregator type we will defined the right calculation to apply to create the appropriate indicator:
+
+- calculation of the session time indicator based on ConnectionEvent
+- calculation of the period between 2 different challenges based on the ChallengeLaunchEvent
+- calculation of the period between the first connection and the first challenge based on ChallengeLaunchEvent and ConnectionEvent
+- calculation of an indicator based on a single event
+- calculation of an aggregated indicator to sum an event type per days.
+
+Once the indicators is calculated we will:
+
+1. post the indicator to the remote doctype
+2. push the event used to calculate the indicator to a array, which will be used to identify all events taken into account during the process.
+
+At the end of the service, the service will change the *aggregated* flag to **true** for all events present in the array.
+
+More technical information are available [here](/ecolyo/services/aggregator_usage_events.md)
+
+## Remote doctype
+
+All indicator are post to a remote doctype, which will allow the application to read a defined external API. This doctype is created by Cozy itself.
+Here are the actual structure of this remote doctype:
+```
+{
+ source: string
+ name: string
+ startDate: string
+ endDate: string
+ value?: number
+ groups: { [key: string]: string }
+}
+```
+with:
+
+- source: contains "ecolyo" value.
+- name: contains the indicator type
+- startDate and endDate: used to defined a period or if not relevant, it contains both the date of the events.
+- value: contains aggreated value (example: number of page viewed on a day).
+- groups: contains all other attribute useful for the indicator (example: context, target, result)
+
diff --git a/docs/ecolyo/services/aggregator_usage_events.md b/docs/ecolyo/services/aggregator_usage_events.md
new file mode 100644
index 0000000..55d8c7b
--- /dev/null
+++ b/docs/ecolyo/services/aggregator_usage_events.md
@@ -0,0 +1,18 @@
+# Definition of the service
+The service will run each day at [TO BE DEFINED], as defined in the manifest:
+
+```
+"aggregatorUsageEvents": {
+ "type": "node",
+ "file": "services/aggregatorUsageEvents/ecolyo.js",
+ "trigger": "[TO BE DEFINED]"
+ }
+```
+# Main responsabilities of the service
+
+The service is responsible of :
+
+1. Collecting all new events from the **com.grandlyon.ecolyo.usageevents**
+2. Aggregated them to indicators
+3. Send indicators to the remote doctype
+
diff --git a/docs/ecolyo/services/index.md b/docs/ecolyo/services/index.md
new file mode 100644
index 0000000..10c51c3
--- /dev/null
+++ b/docs/ecolyo/services/index.md
@@ -0,0 +1,19 @@
+In order to build an automated task within our cozy-stack, we can create *services* which are javascript files called from a trigger job.
+
+For instance on Ecolyo, to schedule a mail that alert the user that 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.
+
+# Configuration
+## Manifest
+The service should be described in the manifest.webapp file. it should defined the type, the file and the trigger. See more information in the official doc of Cozy [here](https://docs.cozy.io/en/howTos/dev/services/)
+
+Here is an exemple of service declaration in the ecolyo manifest:
+
+
+
+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).
+
+# Ecolyo services
+Service code are located under **src\targets\services**.
\ No newline at end of file
diff --git a/docs/ecolyo/services/monthly_report_notification.md b/docs/ecolyo/services/monthly_report_notification.md
new file mode 100644
index 0000000..8465862
--- /dev/null
+++ b/docs/ecolyo/services/monthly_report_notification.md
@@ -0,0 +1,26 @@
+# Definition of the service
+The service will run the 3rd of each month at 10.00 am, as defined in the manifest:
+
+```
+"monthlyReportNotification": {
+ "type": "node",
+ "file": "services/monthlyReportNotification/ecolyo.js",
+ "trigger": "@cron 0 0 10 3 * *"
+ }
+```
+# Main responsabilities of the service
+
+The service is reponsible of sending a mail to user to warn him about the availability of a new information in the Analyse.
+
+Main steps are the following:
+ - Check the "sendReportNotification" attribute in the com.grandlyon.ecolyo.profile doctype. If true, service will continue, else it will stop.
+ - Fetches metadata to customize the mail (Public name, instance url).
+ - Build the mail.
+ - Send the mail.
+
+# Sending mail
+
+Doc of cozy for sendmail worker: https://docs.cozy.io/en/cozy-stack/workers/#sendmail-worker
+
+!!! Send mail in local
+ In local you can use the mail hog tools to see the mail sent by the stack using http://cozy.tools:8025/
\ No newline at end of file
diff --git a/docs/ecolyo/application/monthly-service.png b/docs/img/services/monthly-service.png
similarity index 100%
rename from docs/ecolyo/application/monthly-service.png
rename to docs/img/services/monthly-service.png
diff --git a/mkdocs.yml b/mkdocs.yml
index 3c9d52d..25de77b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -47,6 +47,10 @@ nav:
- Services: ecolyo/application/services.md
- Gitflow: ecolyo/application/gitflow.md
- Deploy: ecolyo/application/deploy.md
+ - Services:
+ - Description: ecolyo/services/index.md
+ - Monthly report notification: ecolyo/services/monthly_report_notification.md
+ - Aggregator usage events: ecolyo/services/aggregator_usage_events.md
- Functionalities:
- Initialization: ecolyo/functionalities/initialization.md
- Consumption: ecolyo/functionalities/consumption.md
--
GitLab