# Web-dumps

Le dépôt [tdm/web-dumps](https://gitbucket.inist.fr/tdm/web-dumps/) contient les
programmes de plusieurs procédures automatiques de collecte et d'enrichissement
de données.

Ces procédures, dont le principe est similaire, sont chacune rangée dans un
répertoire de premier niveau.

```txt
.
├── apil-dumps
├── apil-dumps-config.json
├── corhal-dumps
├── corhal-dumps-config.json
├── halcnrs-dumps
├── halcnrs-dumps-config.json
├── halinria-dumps
└── wos-dumps
```

## Principe

Chaque répertoire est destiné à être déployé dans une instance de l'application
[`lodex-contab`](https://github.com/Inist-CNRS/ezmaster-apps/tree/main/applications/lodex-crontab) sur [ezMaster](https://github.com/Inist-CNRS/ezmaster).

À intervalle régulier, les scripts
[ezs](https://inist-cnrs.github.io/ezs/#/?id=ezs) sont executés. Leur objectif
est en général de télécharger des données, éventuellement de les nettoyer, de
les reformater, et de les enrichir.

Ces intervalles sont paramétrables très finement.

> 📗 Techniquement, il n'est pas requis que ces scripts contiennent une étape de
> collecte des données. Il peut suffire d'avoir un fichier de données à traiter.  
> Ceci dit, ce sera le plus souvent le cas, nous supposerons donc dans la suite
> que cette étape est présente.

Les requêtes exécutées par les scripts peuvent ramener des données différentes à
chaque fois (les données les plus récentes) ou bien les mêmes, en fonction d'un
fichier de paramétrage dont la nature peut varier selon les procédures.

Il y a deux modes à ces procédures:

1. exécution d'un (ou plusieurs) script(s) particulier(s)
2. obtention d'un fichier particulier, en fonction d'une table d'identifiants /
   d'un fichier contenant une requête / ou autre.

Dans le deuxième cas, on n'exécute la procédure que si le fichier dont elle
dépend a changé.

Les procédures étant déployées sur un serveur (avec ezmaster), elles ont
l'avantage de pouvoir durer autant que nécessaire, et ne sont pas contraintes
par l'extinction ou la mise en veille d'un poste de travail à la fin d'une
journée de travail, voire la perte de réseau lors d'un déplacement.

### Configuration

La partie `tasks` de la configuration de l'instance de `lodex-crontab` dans
ezmaster permet de déclencher le traitement.

C'est un tableau JSON d'objets comprenant trois champs:

1. `CronRule`: quand déclencher l'action
2. `Target`: quel fichier on veut obtenir
3. `RunOnStartup`: doit-on déclencher l'action _aussi_ au (re-)démarrage de
   l'instance.

Comme c'est un tableau, on peut spécifier plusieurs tâches dans la même
configuration, ce n'est pas gênant.

#### `CronRule`

Champ au format `crontab` (commande UNIX permettant d'exécuter des programmes à
des moments pré-programmés sur une machine locale).

> 💡 Il est conseillé d'utiliser le site <https://crontab.guru/> pour vérifier à
> quel(s) moment(s) l'action sera déclenchée.

La valeur `0 1 * * *`  signifie: à une heure du matin, tous les jours.

Le zéro du début indique les minutes, le 1 suivant indique l'heure.  
Viennent ensuite le jour (du mois), le mois puis le jour (de la semaine).

L'étoile signifie « _tous_ », alors qu'un intervalle s'écrit avec un tiret.  
Ainsi `0 8-17 * * *` veut dire que l'action se déclenchera tous les jours, à
chaque heure de travail (de 8 heures à 17 heures).  
Le `/` représente un pas: `0 8-17/2 * * *` signifie tous les jours toutes les
deux heures entre 8 heures et 17 heures.  
Pour bien faire, on peut aussi limiter aux jours de la semaine (lundi à
vendredi): `0 8-17/2 * * 1-5`.  
Cette expression peut servir pendant un développement, mais on verra que
`RunOnStartup` est plus pratique pour ça.  

> 📗 Si la procédure a déjà été exécutée au complet, et qu'aucun fichier n'a été
> supprimé ou remplacé, elle ne sera pas rejouée (de toute façon, elle aurait
> fourni les mêmes résultats).

> ⚠️ Il peut y avoir des cas où rejouer une procédure donne des résultats différents.  
> Dans ces cas, il est conseillé d'utiliser le champ `FileName` plutôt que le
> champ `Target` (qu'on préféra dans les cas où rejouer les mêmes scripts donne
> les mêmes résultats).

#### `Target` / `FileName`

`Target` est le chemin du fichier qu'on veut produire.  

Par défaut, c'est le fichier produit par la dernière étape (le dernier script).  
Mais si par exemple on veut éviter cette dernière étape (peut-être parce qu'elle
n'est pas encore efficace ?), on peut remplacer la valeur de target par
le chemin d'un fichier résultant d'une étape précédente.  
Il faut que ce soit le chemin exact à l'intérieur du répertoire de l'instance.  
Les fichiers des étapes suivantes ne seront alors pas regénérés.  

Toutes étapes nécessaires (et seulement elles) sont rejouées jusqu'à produire ce
fichier.  
Cela signifie que si aucun fichier d'une étape précédente (ou le fichier numéroté `00-...`) n'est plus récent que le fichier `Target`, il ne sera pas regénéré.  
Pour forcer la regénération d'un fichier, il suffit de le supprimer.  

> 📗 Ces règles correspondent à celles d'un `Makefile`, car c'est ce qui est
> utilisé.

On peut aussi choisir l'alternative à `Target`, c'est-à-dire `FileName`.  

De cette manière, on exécute inconditionnellement un script ezs (aux moments
sélectionnés par [`CronRule`](#cronrule)).  
C'est intéressant quand on veut lancer à intervalles réguliers une requête dont
on sait que les réponses seront différentes suivant le moment où elle est
lancée, par exemple.

Le champ `FileName` contient le chemin du fichier à exécuter, relativement à la
racine du répertoire WebDav de l'application.

#### `RunOnStartup`

Ce booléen est à `true` par défaut, mais il vaut mieux, une fois la procédure au
point, le positionner à `false`.  
Quand il est vrai, la procédure est lancée à chaque (re-)démarrage de
l'instance, c'est-à-dire aussi quand on met à jour la configuration.  
Ceci dit, quand on utilise `Target`, ne sont jouées que les étapes qui le
nécessitent (le fichier source de l'étape a changé, ou a été supprimé), ce n'est
pas très grave de le laisser à `true` (mais ce n'est pas le cas quand on utilise
`FileName`).  

> 💡 Pour forcer l'exécution d'une étape et des suivantes, il suffit de
> supprimer le fichier résultant de cette étape (dont le nom commence par le
> numéro de l'étape).

### Exemple de configuration complète

```json
{
  "environnement": {
    "CRON_VERBOSE": true,
    "EZS_VERBOSE": false,
    "DEBUG": "ezs",
  },
  "packages": [
    "@ezs/core@2.1.0",
    "@ezs/basics@1.22.3",
    "@ezs/analytics@2.0.2"
  ],

  "files" : {
    "zip": "https://gitbucket.inist.fr/parmentf/giec-wos/archive/doiswos-dumps/doiwos-dumps-1.0.0.zip"
  },
  "tasks": [
    {
      "CronRule": "0 1 * * *",
      "Target": "data/09-corpus-simple-cnrs.json",
      "RunOnStartup": true
    }
  ]
}
```

## Développement

Chaque nom de répertoire doit être en deux parties, séparées par un tiret.  
Ceci pour respecter la nomenclature des instances dans ezmaster.  

### Créer une version

Afin de faciliter le déploiement (et de le limiter à un répertoire), on peut
utiliser les helpers du Makefile (`make version-major`, `make version-minor`, `make
version-patch`).

Ils se chargent de mettre un _tag_ git sur un répertoire et de le pousser sur le
dépôt. Leur seul paramètre est le nom du répertoire.

> ⚠️ **Attention** : Vérifiez que vous êtes bien à la racine du projet avant de lancer la commande.

Exemple:

```bash
$ make version-major doiwos-dumps
Décompte des objets: 1, fait.
Écriture des objets: 100% (1/1), 185 bytes | 185.00 KiB/s, fait.
Total 1 (delta 0), reused 0 (delta 0)
remote: Updating references: 100% (1/1)
To ssh://gitbucket.inist.fr:22222/tdm/web-dumps.git
 * [new tag]         doiwos-dumps@1.0.0 -> doiwos-dumps@1.0.0
Nouvelle version créée: doiwos-dumps@1.0.0
URL à utiliser: https://gitbucket.inist.fr/tdm/web-dumps/archive/doiwos-dumps/doiwos-dumps@1.0.0.zip
```

L'URL fournie sert à la configuration de l'instance, et permet la mise à jour du
programme.

Il suffit de la coller dans la clé `files.zip` de l'instance de `lodex-crontab`.

### Bonnes pratiques

1. Mettre un fichier de configuration d'exemple, au même nom que le répertoire +
`.json` pour qu'on puisse le copier et l'adapter dans la configuration de
l'instance dans ezMaster.  
Cette configuration doit contenir les paquets npm nécessaires à l'exécution des
scripts.  

2. Numéroter les fichiers de données produits en fonction des numéros des étapes
qui les ont produits.

3. Numéroter les scripts ezs selon les étapes qu'ils représentent (un nombre à deux
chiffres au début du nom du fichier, comme pour les données qu'ils produisent).

4. Documenter chaque procédure, dans un README à l'intérieur de son répertoire.