Web-dumps

Le dépôt 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.

.
├── 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 sur ezMaster.

À intervalle régulier, les scripts 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).
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

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

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