# mapping-tools

Ces services permettent de remplacer des valeurs selon une table de correspondance.

Certaines tables de correspondance sont gérées par les services APIL et Terminologie, et sont
donc hébergées sur une machine du département.

Chaque service web de cette instance commence donc par aller chercher la table
dont il a besoin via HTTP.

## Configuration

À partir de la version 2.0.0, l'application à utiliser est `lodex-workers-python`.

Il faut préciser dans le fichier de configuration de l'instance qu'elle utilise
les paquets node:

- `@ezs/basics`
- `@ezs/analytics`

```json
{
    "packages": [
        "@ezs/core@2.5.1",
        "@ezs/analytics@2.0.22",
        "@ezs/basics@1.24.0"
    ]
}
```

Il est impératif d'ajouter, dans la partie `environment` de la configuration,
une variable `TABLE_SERVER_URL` pointant vers la racine du serveur statique des
tables de correspondances.

Par défaut, elle vaut `http://mapping-tables.daf.intra.inist.fr/`

```json
{
  "environnement": {
    "EZS_TITLE": "Mapping tools",
    "EZS_DESCRIPTION": "Outils de mise en correspondance",
    ...
    "TABLE_SERVER_URL": "http://mapping-tables.daf.intra.inist.fr/"
  }
}
```

## Utilisation

- [v1/halAuthorId/idRef/json](#v1/halauthorid/idref/json)
- [v1/homogenize/documentType/json](#v1/homogenize/documenttype/json)
- [v1/homogenize/publisher/json](#v1/homogenize/publisher/json)
- [v1/homogenize/source/json](#v1/homogenize/source/json)
- [v1/idRef/orcid/json](#v1/idref/orcid/json)
- [v1/inspire-category/meta-category/json](#v1/inspire-category/meta-category/json)
- [v1/inspire-labos/in2p3-labos/json](#v1/inspire-labos/in2p3-labos/json)
- [v1/rnsr/instituts-cnrs/json](#v1/rnsr/instituts-cnrs/json)
- [v1/hospital/affiliations](#v1/hospital/affiliations)

### v1/halAuthorId/idRef/json

Renvoie l'idRef associé au halAuthorId fourni.

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec l'idRef associé au halAuthorId fourni.

#### Paramètres de v1/halAuthorId/idRef/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple de v1/halAuthorId/idRef/json

Avec le halAuthorId <https://data.archives-ouvertes.fr/author/1458607>.

```bash
curl -X POST "http://mapping-tools.tdmservices.intra.inist.fr/v1/halAuthorId/idRef/json" -H  "accept: application/json" -H  "Content-Type: application/json" -d "[{\"id\":0,\"value\":\"https://data.archives-ouvertes.fr/author/1458607\"}]"
```

Sortie:

```json
[
  {
    "id": 0,
    "value": "http://www.idref.fr/190260483/id"
  }
]
```

### v1/homogenize/documentType/json

Homogénéise le type de document d'une notice.

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec la forme canonique du type de document.

#### Paramètres de v1/homogenize/documentType/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple de v1/homogenize/documentType/json

Avec la valeur `"ART"`.

```bash
curl -X POST "http://mapping-tools.tdmservices.intra.inist.fr/v1/homogenize/documentType/json" -H  "accept: application/json" -H  "Content-Type: application/json" -d "[{\"id\":0,\"value\":\"ART\"}]"
```

Sortie:

```json
[
  {
    "id": 0,
    "value": "Article"
  }
]
```

### v1/homogenize/publisher/json

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec la forme canonique de l'éditeur envoyé dans le champ `value`.

#### Paramètres de v1/homogenize/publisher/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple de v1/homogenize/publisher/json

```bash
curl -X POST "https://mapping-tools.services.inist.fr/v1/homogenize/publisher/json" -H  "accept: application/json" -H  "Content-Type: application/json" -d "[{\"id\":0,\"value\":\"Springer Verlag\"}]"
```

Sortie:

```json
[
  {
    "id": 0,
    "value": "SPRINGER"
  }
]
```

### v1/homogenize/source/json

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec la forme canonique de la source envoyée dans le champ `value`.

#### Paramètres de v1/homogenize/source/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple de v1/homogenize/source/json

```bash
curl -X POST "https://mapping-tools.services.inist.fr/v1/homogenize/source/json" -H  "accept: application/json" -H  "Content-Type: application/json" -d "[{\"id\":0,\"value\":\"« Gilets jaunes » Hypothèses sur un mouvement\"}]"
```

Sortie:

```json
[
  {
    "id": 0,
    "value": "\"GILETS JAUNES\" : HYPOTHESES SUR UN MOUVEMENT"
  }
]
```

### v1/idRef/orcid/json

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec les ORCID correspondant à l'idRef envoyé dans le champ `value`.

#### Paramètres de v1/idRef/orcid/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple v1/idRef/orcird/json

```bash
curl -X POST "https://mapping-tools.services.inist.fr/v1/idRef/orcid/json" -H  "accept: application/json" -H  "Content-Type: application/json" -d "[{\"id\":0,\"value\":\"http://www.idref.fr/190260483/id\"}]"
```

Sortie:

```json
[{
    "id": 0,
    "value": "https://orcid.org/0000-0003-1301-3305"
}]
```

### v1/inspire-category/meta-category/json

Prend en entrée du JSON avec deux champs: `id` et `value`.
Le champ `value` doit contenir une catégorie [Inspire](https://inspirehep.net/).
Renvoie un JSON avec une méta-catégorie [IN2P3](https://www.in2p3.cnrs.fr/) dans
le champ `value`.

> **Remarque**: quand on ne trouve pas de méta-catégorie correspondante, la
> valeur est `n/a` (*not available*)

#### Paramètres de v1/inspire-category/meta-category/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple

```bash
cat <<EOF | curl -X POST --data-binary @- "https://mapping-tools.services.inist.fr/v1/inspire-category/meta-category/json?indent=true"
[{ "id": 1, "value": "Experiment-HEP" }, { "id": 2, "value": "Astrophysics"}]
EOF
```

Sortie

```json
[{
    "id": 1,
    "value": "Particules et hadronique"
},
{
    "id": 2,
    "value": "Astroparticule et cosmologie"
}]
```

### v1/inspire-labos/in2p3-labos/json

Prend en entrée du JSON avec deux champs: `id` et `value`.
Le champ `value` doit contenir un code institution de la base
[Inspire](https://inspirehep.net/).
Renvoie un JSON avec un code labo [IN2P3](https://www.in2p3.cnrs.fr/) dans le
champ `value`.

> **Remarque**: quand on ne trouve pas un code labo IN2P3 correspondant, la
> valeur est `n/a` (*not available*)

#### Paramètres de v1/inspire-labos/in2p3-labos/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple

```bash
cat <<EOF | curl -X POST --data-binary @- "https://mapping-tools.services.inist.fr/v1/inspire-labos/in2p3-labos/json?indent=true"
[{ "id": 1, "value": "903453" }, { "id": 2, "value": "910133"}]
EOF
```

Sortie

```json
[{
    "id": 1,
    "value": "GANIL"
},
{
    "id": 2,
    "value": "APC Paris"
}]
```

### v1/rnsr/instituts-cnrs/json

Prend en entrée du JSON avec deux champs: `id` et `value`, et renvoie un JSON
avec un institut du CNRS dans le champ `value`.

> **Remarque**: quand on ne trouve pas d'institut, la valeur est `n/a` (*not
> available*)

#### Paramètres de v1/rnsr/instituts-cnrs/json

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple

```bash
cat <<EOF | curl -X POST --data-binary @- "https://mapping-tools.services.inist.fr/v1/rnsr/instituts-cnrs/json?indent=true"
[{ "id": 1, "value": "200919362L" }, { "id": 2, "value": "200112440X"}]
EOF
```

Sortie

```json
[{
    "id": 1,
    "value": "INEE"
},
{
    "id": 2,
    "value": "STIC"
}]
```

### v1/hospital/affiliations

Prend en entrée du JSON avec deux champs: `id` et `value`, où le champ
`value`est une adresse d'affiliation. Il renvoie un JSON avec l'hôpital
correspondant dans le champ `value`.

> **Remarque**: quand on ne trouve pas d'hôpital, la valeur est `n/a` (*not available*)

#### Paramètres de v1/hospital/affiliations

| nom    | description                                                            |
| :----- | :--------------------------------------------------------------------- |
| indent | `true` ou `false`, indente le JSON résultat ou non (`false` par défaut) |

#### Exemple

Entrée

```json
[
    {"id" :"1","value": "Hop La Pitie Salpetriere, AP HP, Serv Med Interne, Ctr Natl Reference Histiocytoses, Paris, France"},
    {"id" :"2","value": "UMR CNRS 7021, Illkirch Graffenstaden, France"},
    {"id" :"3","value": "Bergonie Inst, Dept Radiat Oncol, Bordeaux, France"},
    {"id" :"4","value": "CHU Besancon, Serv Neurol, 2 Blvd Fleming, F-25030 Besancon, France"},
    {"id" :"5","value": "CHU St Etienne, Ave Albert Raimond, F-42055 St Etienne, France"}
]
```

Sortie

```json
[
  {"id": "1","value": "APHP"},
  {"id": "2","value": "n/a"},
  {"id": "3","value": "Institut Bergonie Bordeaux"},
  {"id": "4","value": "CHU Besancon"},
  {"id": "5","value": "CHU St Etienne"}
]
```
