li-harvest-hal
===============

## Présentation ##

Objectif du module :
- Récupérer l'ensemble des notices HAL (France) pour une période de temps donnée.
Ce module a quelques spécificités :
- Un seul docObject factice en entrée, le rôle est d'initialiser les traitements.
- Un seul docObject en sortie également. Ce docObject de sortie a une structure permettant d'enchaîner les traitements avec le module li-carto.


### Fonctionnement ###

Le module effectue les opérations suivantes :

- Récupération en entrée d'un `docObject`, ainsi que d'une callback `cb`.
- Vérifier si un moissonnage avec les mêmes paramètres été déjà effectué.
- Construire le query de recherche dans l’API Hal a partir du fichier query.json.
- Appels à l'API pour l'interrogation/parcours des résultats.
- Vérification des résultats et écriture sur disque des fichiers TEI-HAL.
- Scroller les résultats de l’API Hal si le nombre des résultats est supérieur à 10K.
- Gestion du backpressure durant l’écriture sur disque.
- Gestion des erreurs. (quand l’API ne répond pas par exemple).

### Installation ###

Commande d'Installation :
```bash
npm install
```

🚧 **Note importante** : la variable d'environnement `$CORPUSES_ROOT` doit être définie. Elle correspond au chemin du répertoire dans lequel seront stockés les fichiers moissonnés.

### Vérification du fonctionnement ###

Commande d'exécution des tests unitaires :
```bash
npm test
```

## Exemple d'un docObject accepté en entrée ###

```
{
corpusName: "hal",
cartoType: "conditor:pubmed",
corpusResources: "/applis/corhal/loadistex/corpus-resources",
corpusOutput: "/applis/corhal/corpusOutput"
}
```

## Exemple d'un docObject accepté en sortie ###

```
{
corpusName: "hal",
cartoType: "conditor:pubmed",
corpusResources: "/applis/corhal/loadistex/corpus-resources",
corpusOutput: "/applis/corhal/corpusOutput",
corpusRoot: "/data/hal-20211121-to-20211121"
}
```

### Arborescence ###

```
.
├── node_modules
│   └── ...
├── config/
│   ├── config.js           // Fichier de configuration, du proxy et url de l'api
│   │
│   └── query.json          // Les paramètres de recherche de query
├── lib/
│   └── utils.js            // Des fonctions 'utils' utilisées dans index.js
├── test
│   ├── dataset             // Ensemble des docObjects utilisés pour les tests
│   │   └── ...
│   └── run.js              // Ensemble des tests à effectuer
├── .eslintrc.json          // Configuration pour eslint
├── .gitignore
├── README.md               // Le fichier que vous lisez actuellement
├── index.js                // Script principal contenant la méthode doTheJob
└── package.json            // Fichier contenant les dépendances NPM
```

## Le fichier query.json ###

Le fichier config/query.json contient l'ensemble des paramètres de recherche à utiliser pour l'interrogation de l'api HAL

```
{
    "fq": [""],         // Liste des filtres a utiliser pour limiter les résultats retournés.
    "fl": "",           // La liste des champs a retourner dans la recherche, séparés par ,
    "q": "",            // La requête.
    "rows": "",         // Le nombre de réponses à retourner.
    "sort": "",         // Pour trier les résultats.
    "cursorMark": "*"   // Curseur utilisé pour parcourir plusieurs milliers de résultats.  
}
```

## Le fichier config.js ###

Le fichier config/config.js de configuration 

```
{
    "halApi":"",        // L'adresse url de l'api Hal
    "maxRetry":2       // Nombre des retries en cas d'échec lors de l'interrogation de l'api HAL
}
```

### Codes d'erreur ###

| Code              | Signification                                         | Note(s) |
| ----------------- | ------------------------------------------------------| ------- |
| FolderExistError  | Harvest folder already exist.                         |
| FetchError        | API-HAL request error.                                |
| NoResultFound     | No result found to harvest.                           |
| MissingEnvironmentVariable | A required environment variable must be set  |