SOAP
===============
Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices en utilisant le protocole [SOAP](https://fr.wikipedia.org/wiki/SOAP). Chaque session se passe en 5 étapes avec un script `bash` dédié pour chacune de ces étapes :
| Étapes | Scripts |
| ------ | ------- |
| Connexion à l’API | `WosConnect.sh` |
| Interrogation de l’API | `WosQuery.sh` |
| Téléchargement des notices | `WosRetrieve.sh` |
| Déconnexion | `WosClose.sh` |
| Extraction des notices | `WosDecode.sh` |
Dans le cas particulier d’une recherche à partir d’une liste de DOIs, on utilise le script `WosSearchByDoi.sh` qui fait à la fois l’interrogation de l’API et le téléchargement des notices, remplaçant ainsi les scripts `WosQuery.sh` et `WosRetrieve.sh`.
Ces scripts ont besoin pour fonctionner de trois programmes qui sont généralement présents dans les distributions Unix/Linux :
- `base64`
- `curl`
- `xmllint`
En plus, le dernier script a besoin du programme C `decode_wos` dont le programme source, `decode_wos.l`, doit être compilé avec `flex` et `gcc`.
Pour les scripts communiquant avec l’API, c’est-à-dire les 4 premiers, toutes les informations renvoyées par le programme `curl` sur la sortie standard ou sur l’erreur standard sont conservées dans deux fichiers, respectivement `WosApiOut.txt` et `WosApiErr.txt`.
## WosConnect.sh
Ce script permet la connexion à l’API WoS à l’aide d'un nom d’utilisateur et un mot de passe. En cas de succès, le script renvoie un identifiant de session (*SID*) à utiliser lors des étapes suivantes. Par souci de sécurité, il n’y a pas d’option pour le mot de passe en ligne de commande. Il sera demandé par la suite de façon plus sûre.
### Usage
```bash
WosConnect.sh -u utilisateur [ -j cookie_jar ]
WosConnect.sh -h
```
### Options
```txt
-h affiche cette aide
-j indique le nom du fichier qui recevra les cookies (“cookies.txt”
par défaut)
-u indique le nom de l’utilisateur (login).
```
## WosQuery.sh
Ce script permet l’interrogation de l’API WoS à l’aide d’une requête en utilisant l’identifiant *SID*. Par défaut, l’interrogation se fait sur l’ensemble des bases WoS et retourne un numéro de requête (*queryId*), le nombre de notices trouvées, le nombre total de notices dans les bases WoS interrogées ainsi que 5 notices complètes. Il est possible de limiter la recherche à certaines bases WoS avec l’option “-b” et on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f”.
À noter que quelque soit le nombre de notices trouvées, on ne peut en télécharger que 100 000 au maximum. Au-delà, il faut faire plusieurs requêtes en indiquant, avec l’option “-p”, des périodes de temps successives. Les dates de début et de fin de période correspondent aux dates auxquelles les notices sont ajoutées à la base.
Pour les personnes faisant une veille continue sur WoS, il est également possible de demander à ne considérer que les notices des 1, 2 ou 4 dernières semaines, toujours avec l’option “-p”.
### Usage
```bash
WosQuery.sh -s sid -q requête [ -p (début:fin|[124]week) ]
[ -b [WOS:]base ]* [ -f champs ]* [ -t CH:[AD] ]
[ -n notices ] [ -j cookie_jar ] [ -i ]
WosQuery.sh -h
```
### Options principales
```txt
-h affiche cette aide
-p limite la recherche dans la base de données à la période indiquée
sous forme aaaa-mm-jj:aaaa-mm-jj (e.g., “2000-01-01:2020-07-31”)
ou sous forme “1week”, “2week” ou “4week”
-q fournit la requête à envoyer (entre simples ou doubles quotes si
elle contient des espaces ou des caractères spéciaux)
-s indique le jeton d’authentification “SID” obtenu avec le programme
d’authentification à l’API WoS
```
### Autres options
```txt
-b limite la recherche à une ou plusieurs bases (e.g. “WOS:SCI”).
Cette option est répétitive et “WOS:” est facultatif (par défaut,
la recherche se fait sur l’ensemble du WoS)
-f limite les champs présents dans les notices téléchargées. Cette
option est répétitive (par défaut, tous les champs sont présents)
-i ajoute dans la réponse de l’API la liste des identifiants WoS des
notices retournées (5 par défaut ou valeur de l’option “-n”)
-j indique le nom du fichier qui recevra les cookies (“cookies.txt”
par défaut)
-n indique le nombre de notices, entre 1 et 100, à retourner (5 par
défaut)
-t trie les résultats sur un champ (nom abrégé à 2 majuscules) de
façon croissante (A) ou décroissante (D) ou par pertinene (RS)
forcément décroissante
```
## WosRetrieve.sh
Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant l’identifiant *SID* et le numéro de requête (*queryId*) obtenu à l’étape précédente. En cas d’interruption du transfert, il est possible de reprendre le téléchargement là où il s'est arrêté en indiquant un nouveau numéro de départ (option “-o”). Au cas où un paquet de notices a une taille trop élevée et se retrouve tronqué, vous pouvez relancer le téléchargement avec un nombre de notices plus petit (l’option “-t”). De même, si vous recevez un message signalant une limitation de la bande passante (*bandwidth throttling*), vous pouvez modifier le délai entre deux itérations (1 seconde par défaut) avec la variable d’environnement `WOS_DELAY`. Par exemple, pour passer à un délai de 3 secondes :
```bash
export WOS_DELAY=3
```
### Usage
```bash
WosRetrieve.sh -s sid -q queryId -n nb_notices -r résultat
[ -f champs ]* [ -t CH:(A|D) ] [ -i ]
[ -o offset ] [ -T taille ] [ -j cookie_jar ]
WosRetrieve.sh -h
```
### Options
```txt
-f limite les champs présents dans les notices téléchargées. Cette
option est répétitive (par défaut, tous les champs sont présents)
-h affiche cette aide
-i ajoute dans la réponse de l’API la liste des identifiants WoS des
notices retournées (5 par défaut ou valeur de l’option “-n”)
-j indique le nom du fichier qui recevra les cookies (“cookies.txt”
par défaut)
-n indique le nombre total de notices WoS à télécharger (la valeur
maximale est donnée par le programme envoyant la requête à l’API
WoS)
-o indique à partir de quel numéro (offset), on veut télécharger les
notices, en particulier pour reprendre un téléchargement après un
problème de connexion (1 par défaut)
-q indique le numéro de la requête “queryId” dont on veut télécharger
les résultats
-r indique le nom du fichier résultat (pour la sortie standard, utiliser
le tiret “-” comme argument de l’option)
-s indique le jeton d’authentification “SID” obtenu avec le programme
d’authentification à l'API WoS
-t trie les résultats sur un champ (nom abrégé à 2 majuscules) de
façon croissante (A) ou décroissante (D) ou par pertinence (RS)
-T indique le nombre de notices à télécharger à chaque itération
(100 par défaut)
```
## WosSearchByDoi.sh
Ce script permet à la fois l’interrogation de l’API WoS à partir d’une liste de DOIs et le téléchargement des notices trouvées en utilisant l’identifiant *SID*. Fondamentalement, les options sont les mêmes que pour le script `WosQuery.sh`. La seule différence, c’est qu’on a un fichier avec les DOIs en entrée et un fichier de résultats en sortie.
### Usage
```bash
WosSearchByDoi.sh -s sid -d (fichier|-) -r (résultats|-) [ -f champs ]*
[ -T taille ] [ -j cookie_jar ] [ -i ]
WosSearchByDoi.sh -h
```
### Options principales
```txt
-d indique le nom du fichier avec la liste des DOIs à chercher. Si on
a un tiret “-” en argument, la liste de DOIs est lue sur l’entrée
standard
-h affiche cette aide
-r indique le nom du fichier résultat (pour la sortie standard, utiliser
le tiret “-” comme argument de l’option)
-s indique le jeton d’authentification “SID” obtenu avec le programme
d‘authentification à l‘API WoS
-T indique le nombre de notices à télécharger à chaque itération
(100 par défaut)
```
#### Autres options
```txt
-f limite les champs présents dans les notices téléchargées. Cette
option est répétitive (par défaut, tous les champs sont présents)
-i ajoute dans la réponse de l’API la liste des identifiants WoS des
notices retournées à chaque itération
-j indique le nom du fichier qui recevra les cookies (“cookies.txt”
par défaut)
```
## WosClose.sh
Ce script permet de terminer une session d’interrogation de l’API WoS, après une ou plusieurs itérations de reqêtes et de téléchargements. À noter que l’identifiant de session (*SID*) a une durée de vie limitée, donc, la session s’arrêtera de toute façon.
### Usage
```bash
WosClose.sh -s sid [ -j cookie_jar ]
WosClose.sh -h
```
### Options
```txt
-h affiche cette aide
-j indique le nom du fichier qui recevra les cookies (“cookies.txt”
par défaut)
-s indique le jeton d’authentification “SID” obtenu avec le programme
d’authentification à l'API WoS
```
## WosDecode.sh
Que se soit en utilisant le script `WosRetrieve.sh` ou le script `WosSearchByDoi.sh`, le fichier de résultats est souvent la concaténation de plusieurs fichiers. Dans chacun de ses fichiers, les notices sont encodées au sein de l’élément `records`. Le script `WosDecode.sh` permet de remettre les notices au format XML et d’en faire un fichier « bien formé ». Il utilise le programme C `decode_wos` qu’il faut compiler à partir du fichier source `decode_wos.l` .
Ce script peut traiter plusieurs fichiers en même temps soit en les listant avec l’option “-f”, soit en les envoyant par l’entrée standard, soit par un mixte des deux. Par exemple, si on a 3 fichiers (`fic1.xml`, `fic2.xml` et `fic3.xml`) que l’on veut réunir en un seul fichier final, on peut utiliser les commandes suivantes qui donnent toutes le même résultat.
```bash
WosDecode.sh -f fic1.xml -f fic2.xml -f fic3.xml
WosDecode.sh -f fic1.xml,fic2.xml,fic3.xml
WosDecode.sh -f "fic1.xml fic2.xml fic3.xml"
cat fic1.xml fic2.xml fic3.xml | WosDecode.sh -f -
cat fic2.xml | WosDecode.sh -f fic1.xml,-,fic3.xml
```
### Usage
```bash
WosDecode.sh -f (fichier[,fichier]*|-) [ -p programme ] [ -s sortie ]
WosDecode.sh -h
```
### Options
```txt
-f indique le nom du ou des fichiers à traiter. Cette option est
répétitive. Vous pouvez également utiliser une liste de fichiers
séparés par des virgules (mais sans espace) ou mettre un tiret
si les données sont envoyées sur l’entrée standard
-h affiche cette aide
-p indique où trouver le programme “decode_wos” s’il n’est pas dans
un des répertoires donnés par la variable $PATH
-s indique le nom du fichier de sortie. Sinon, les données sont
envoyées sur la sortie standard
```
## decode_wos
Programme C qui permet d’ajouter des sauts de ligne dans les fichiers reçus de l’API WoS tout en décodant les entités caractères de façon à avoir des notices individualisées au format XML. Comme chaque notice est sur une ligne, il devient alors possible de les filtrer et de les réunir en un seul fichier.
### Compilation
Le programme source, `decode_wos.l`, est un fichier [Lex](https://fr.wikipedia.org/wiki/Lex_(logiciel) qui se compile avec `flex` et `gcc`. Les différentes étapes sont :
```bash
flex -t decode_wos.l > decode_wos.c
gcc -c -o decode_wos.o decode_wos.c
gcc decode_wos.o -lfl -o decode_wos
```
Sous MacOs, la dernière commande est :
```bash
gcc decode_wos.o -ll -o decode_wos
```
Vous pouvez déplacer le programme `decode_wos` dans un des répertoires donnés par la variable globale `$PATH` ou indiquer sa position au script `WosDecode.sh` avec l’option “-p”.
besagni