Procédure d'exploitation suite à la création ou la modification d'une ontologie
###############################################################################

Au préalable à la création ou à la modification d'une ontologie, les index Elasticsearch correspondant aux ontologies doivent être créés ou mis à jour.


Création d'une ontologie
========================

Suite à la création d'une nouvelle ontologie, les index Elasticsearch doivent être mis à jour selon la procédure suivante:

* Dans le cas d'une création, il suffit de créer un nouveau mapping dans les index concernés.

Ex : Ajout d'une propriété Licence dans tous les index unit (unit* signifiant tous les index unit unit_0, unit_1 etc ...)

Commandes à lancer sur une des partitions hébergeant le cluster elasticsearch "data" :

.. code-block:: bash

    curl -XPUT "http://localhost:9200/unit*/_mapping/typeunique?update_all_types" -d'
    {
          "properties": {
        "Licence": {
          "type": "text"
        }
          }
    }'

Pour verifier sur un ou tous les index ``unit`` :

.. code-block:: bash

    curl -XGET "http://localhost:9200/unit_0/_mapping/?pretty=true"

.. code-block:: bash

    curl -XGET "http://localhost:9200/unit*/_mapping/?pretty=true"


Changement de type d'une ontologie existante
============================================

Dans ce cas, le changement de type dans elasticsearch n'est pas possible. Il faut donc créer un nouvel index ElasticSearch avec un nouveau mapping, puis reindexer l'ancien index dans ce dernier.


On récupère d'abord l'ancien index

.. code-block:: bash

    curl -XGET 'localhost:9200/unit_1/_mapping?pretty=true'

On créé un fichier json et on y copie les données obtenues ( ne conserver que la balise "mappings" : { ...} et son contenu).
On modifie le mapping en changeant le type des propriétés choisies.
On créé un nouvel index on lui passant en paramètre le fichier du nouveau mapping .

.. code-block:: bash

    curl -XPUT "http://localhost:9200/new_unit_1" -H 'Content-Type: application/json' -d @newmapping.json

Verifier l'index :

.. code-block:: bash

    curl -XGET 'localhost:9200/new_unit_1/_mapping/'


On reindexe unit_1 vers le nouvel index new_unit_1

.. code-block:: bash

    curl -XPOST 'localhost:9200/_reindex' -H 'Content-Type:application/json' -d '{
        "source" : {
            "index" : "unit_1"
        },
        "dest" : {
            "index" : "new_unit_1",
            "version_type": "external"
        }
    }'

On efface l'alias de l'ancien index unit_1

.. code-block:: bash

    curl -XDELETE 'localhost:9200/unit_1/_alias/unit_1'

et on l'affecte au nouvel index new_unit_1

.. code-block:: bash

    curl -XPUT 'localhost:9200/new_unit_1/_alias/unit_1'

.. warning:: les index elasticsearch de :term:`VITAM` sont créés par tenant. Il faudra refaire l'opération ci-dessus pour chaque tenant.

.. note:: En cas du changement des mappings elasticsearch, il faudra veiller à ce qu'ils soient en cohérence avec l'ontologie.

L'ontologie externe suite à la montée de version de :term:`VITAM`
#################################################################

Lors de la montée de version, les ontologies externes en cours d'exploitation par :term:`VITAM` ne sont pas touchées, et seront mergées avec les ontologies internes de :term:`VITAM`.

Le fichier du référentiel de l'ontologie se trouve désormais dans ``deployment/environments/ontology/VitamOntology.json``

La procédure de merge manuelle du référentiel de l'ontologie avant chaque montée de version n'est plus nécessaire. Depuis la version 3.4.0 de :term:`VITAM`, le vocabulaire externe de l'ontologie est géré automatiquement avec le vocabulaire interne.

Lors du lancement du procédure de mise à jour de :term:`VITAM`, une phase préliminaire de vérification et validation sera faite pour détecter des éventuelles conflits entre les vocabulaires internes et externes.

Afin d'assurer que la montée de version de :term:`VITAM` passera sans affecter le système , cette vérification s'exécute dans les phases préliminaires de l'ansiblerie, avant la phase de l'installation des composants :term:`VITAM`, (en cas d'échec à cette étape, la solution logicielle déjà installé ne sera pas affectée).

Le script ansible qui fait le check est situé dans : ``deployment/ansible-vitam/roles/check_ontologies/tasks/main.yml``, le rôle vérifie que le composant d'administration fonctionnelle ``vitam-functional-administration`` est bien installé et démarré,
ensuite la tâche ansible ``Check Import Ontologies`` réalise un import à blanc en mode ``Dry Run`` du référentiel de l'ontologie et remonte des éventuelles erreurs d'import.

.. caution:: En cas d'echec de vérification, autrement dit, en cas de présence de conflits entre les deux vocabulaires, l'exploitant adaptera son vocabulaire et veillera à éviter des moindres conflits.

L'exploitant pour vérifier ses corrections en cas d'erreurs, pourra toutefois lancer la commande depuis le dossier `deployment`, depuis une instance hébergeant le composant ``vitam-functional-administration``:

.. code-block:: bash

    curl -XPOST -H "Content-type: application/json" -H "X-Tenant-Id: 1" --data-binary @environments/ontology/VitamOntology.json 'http://{{ hostvars[groups['hosts_functional_administration'][0]]['ip_admin'] }}:{{ vitam.functional_administration.port_admin }}/v1/admin/ontologies/check'

.. caution:: Dans le cadre d’une montée de version, se référer également au :term:`DMV`.