Conversions
===========

Nous décrivons ici des règles de conversions permettant de passer
d'une version de LHÉO à une autre. Ces règles de conversions sont
celles qui sont utilisées dans l'outil *LHÉO Studio* qui permet
notamment d'effectuer automatiquement ces conversions.

Passage de 2.2 à 2.3
--------------------

La compatibilité ascendante de 2.2 à 2.3 permet a priori de n'avoir
qu'à changer l'espace de nom pour passer d'une version à
l'autre. Cependant, la conception de la version 2.3 s'est fondée sur
les usages de nombreux éléments ``extra`` et les a transformés en
éléments natifs du langage. Le principe de transformation est donc,
quand c'est possible, de transformer ces éléments ``extra`` en vrais
éléments natifs.

Par ailleurs, lors de l'opération inverse (2.3 vers 2.2), les nouveaux
éléments natifs de 2.3 sont à nouveau transformés en éléments
``extra``: la transformation doit donc être *conversative* dans le
sens où transformer un flux XML 2.2 avec des ``extras`` vers 2.3 puis
à nouveau vers 2.2 avec des ``extras`` doit permettre de retrouver le
même flux (de la même manière, transformer un flux 2.3 vers 2.2 avec
des ``extras`` puis à nouveau vers 2.3 doit permettre de retrouver un
flux identique).

Espace de nom
^^^^^^^^^^^^^

Le contenu de l'attribut ``xmlns="http://www.lheo.org/2.2"`` devient
``http://lheo.gouv.fr/2.3``.

Horodatages et URI
^^^^^^^^^^^^^^^^^^

Opération inverse de :ref:`horodatages`: on examine dans l'ordre les
attributs ``tag``, ``info`` ou ``ref`` à la recherche des attributs
2.3: si on en trouve, on les promeut en tant que *vrai* attribut.

Code CERTIFINFO
^^^^^^^^^^^^^^^

Pas de changement.


Passage de 2.3 à 2.2
--------------------

La règle générale est de déplacer les éléments de 2.3 n'existant pas
en 2.2 dans des éléments ``extra`` et ``extras``. Ces éléments sont
toujours positionnés dans un élément ``extras`` englobant ayant un
attribut ``info`` valant ``conversion2003`` (``2003`` est un entier
indiquant la version 2.3 de LHÉO). Quand un élément est transformé en
``extra``, on reproduit sur cet élément ``extra`` les attributs
présents sur l'élément original. Ainsi:

.. code-block:: xml

    <code-CPF info="intitulé" ref="abcd">..code..</code-CPF>

sera transformé en:

.. code-block:: xml

    <extra info="code-CPF">
        <extra info="intitulé" ref="abcd">..code..</extra>
    </extra>

Transformation de l'espace de nom (C2003-2002-1)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Le contenu de l'attribut ``http://lheo.gouv.fr/2.3`` devient
``xmlns="http://www.lheo.org/2.2"``. Cette transformation est
effectuée sur tout élément où ce contenu d'espace de nom est
rencontré.

.. _horodatages:

Horodatages et URI (C2003-2002-2)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Les trois attributs ``horodatage-creation``,
``horodatage-modification``, ``horodatage-export`` quand ils sont
présents, sont intégrés à l'attribut ``tag``. Les attributs sont
encodés de la manière suivante:

Par exemple:

.. code-block:: xml

  <lheo xmlns=".../2.3" horodatage-creation="2002-05-30T09:00:00"
      horodatage-export="2002-05-30T09:05:00" uri="https://t.com/hello@bla;val=23">
    ...
    <extras>...</extras>
  </lheo>

est transformé en:

.. code-block:: xml

  <lheo xmlns=".../2.2"
      tag="conversion2003;uri@https://t.com/hello%40bla%3Bval=23;horodatage-creation@2002-05-30T09:00:00;horodatage-export@2002-05-30T09:05:00">
    ...
  </lheo>

c'est-à-dire une chaîne commençant par ``conversion2003``, un ``;``,
puis la liste des attributs séparés pas ``;``, en séparant la clef de
la valeur par un caractère ``@``. Noter que dans le cas de l'URI, les
caractères ``@`` et ``;`` sont *percent encoded*.

Note: on choisit ici d'encoder les attributs dans un autre attribut au
même niveau plutôt qu'un élément ``extra``, car il n'y a pas d'extra
pour tous les éléments, à la différence des attributs. Il se peut par
conséquent que l'attribut `tag` contienne déjà une valeur. Par
convention, en recopie cette valeur dans la chaîne précédemment créée,
préfixée par ``;tag@``.

Code CERTIFINFO / Code RNCP (C2003-2002-3)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Dans le cas d'un code dépassant 6 positions, le code CERTIFINFO ou
RNCP est placé dans un élément ``extra`` dans les ``extras
info="conversion2003"`` de ``certification`` spécifiques à la
conversion. Par exemple, le bloc suivant:

.. code-block:: xml

  <formation>
    ...
    <certification>
        <code-CERTIFINFO info="v34">987654321</code-CERTIFINFO>
        <code-RNCP>RNCP654321</code-RNCP>
    </certification>
    ...
  </formation>

est transformé en:

.. code-block:: xml

  <formation>
    ...
    <certification>
      <extras info="conversion2003">
        <extra info="code-CERTIFINFO"><extra info="v34">987654321</extra></extra>
        <extra info="code-RNCP"><extra>RNCP654321</extra></extra>
      </extras>
    </certification>
    ...
  </formation>

SIRET du lieu de formation (C2003-2002-4)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Déplacement dans l'élément ``extras infos="conversion2003"`` de
``lieu-de-formation`` de tout le bloc
``SIRET-lieu-formation``. Passage de:

.. code-block:: xml

  <formation>
    ...
    <action>
      ...
      <lieu-de-formation>
        <SIRET-lieu-formation info="note">
          <SIRET>...siret...</SIRET></extra>
          <extras>...extras...</extras>
        </SIRET-lieu-formation>
        ...
      </lieu-de-formation>
      ...
    </action>
    ...
  </formation>

à:

.. code-block:: xml

  <formation>
    ...
    <action>
      ...
      <lieu-de-formation>
        ...
        <extras info="conversion2003">
          <extras info="SIRET-lieu-formation">
            <extras info="note">
                <extra><SIRET>...siret...</SIRET></extra>
                <extras>...extras...</extras>
            </extras>
          </extras>
        </extras>
      </lieu-de-formation>
      ...
    </action>
    ...
  </formation>

Codes UAI (C2003-2002-5)
^^^^^^^^^^^^^^^^^^^^^^^^

Code UAI dans l'organisme de formation responsable
``code-UAI-organisme-formation``, le lieu de formation
``code-UAI-lieu-formation`` et l'organisme formateur
``code-UAI-formateur``:

.. code-block:: xml

  <formation>
    ...
    <organisme-formation-responsable>
      ...
      <code-UAI-organisme-formation>
        <code-UAI>...</code-UAI>
        <extras>...</extras>
      </code-UAI-organisme-formation>
      ...
    </organisme-formation-responsable>
    ...
  </formation>

Déplacement dans les éléments extras au même niveau:

.. code-block:: xml

  <formation>
    ...
    <organisme-formation-responsable>
      ...
      <extras info="conversion2003">
        <extras info="code-UAI-organisme-formation">
          <extras>
            <extra info="code-UAI"><extra>...code UAI...</extra></extra>
            <extras>...extras...</extras>
          </extras>
        </extras>
      </extras>
    </organisme-formation-responsable>
    ...
  </formation>


Codes ELU, CPF, RS (C2003-2002-6)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Les éléments ``code-ELU``, ``code-CPF`` et ``code-RS`` sont placés
dans les éléments ``extras`` les plus proches (dans ``certification``
ou ``code-type-formation``). Exemple:

.. code-block:: xml

  <extras info="conversion2003">
    <extra info="code-CPF"><extra>...code CPF...</extra></extra>
  </extras>

Type de contact (C2003-2002-7)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

L'élément ``type-contact``, présent dans ``contact-formation``,
``contact-session``, ``contact-organisme``, ``contact-formateur`` est
déplacé dans les ``extras`` de ces contacts. Cette opération doit être
faite sur chaque contact (en 2.3 ces éléments sont multi-valués).

Dans ``contact-formation``:

.. code-block:: xml

  <formation>
    ...
    <contact-formation>
      <type-contact>2</type-contact>
      ...
    </contact-formation>
    ...
  </formation>

Transformé en:

.. code-block:: xml

  <formation>
    ...
    <contact-formation>
      ...
      <extras info="conversion2003">
        <extra info="type-contact"><extra>2</extra></extra>
      </extras>
    </contact-formation>
    ...
  </formation>

Même processus dans ``contact-session``, ``contact-organisme``,
``contact-formateur``.

Contact de la session (C2003-2002-8)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Tous les ``contact-session`` sont passés dans un bloc ``extras
info="conversion2003"`` à la fin de l'élément ``session`` englobant.

Multivaluations des contacts (C2003-2002-9)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Tous les ``contact-formation`` au delà d'un seul sont passés dans un
bloc ``extras info="conversion2003"`` à la fin de l'élément
``formation`` englobant.
- Tous les ``contact-organisme`` au delà d'un seul sont passés dans un
bloc ``extras info="conversion2003"`` à la fin de l'élément
``organisme-formation-responsable`` englobant.
- Tous les ``contact-formation`` au delà d'un seul sont passés dans un
bloc ``extras info="conversion2003"`` à la fin de l'élément
``organisme-formation`` englobant.

Dénomination dans les adresses (C2003-2002-10)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``denomination`` passage en ``extra`` avec émission d'un
avertissement pour la potentielle mauvaise adresse.

Option ``--cut-denomination``: transformation des 50 premiers
caractères de cette dénomination dans un élément ``<ligne>``, en
coupant le texte au blanc le plus approprié (ou à 50 pile quand il n'y
a pas de blanc).  Le contenu complet de l'élément dénomination est
stocké dans l'attribut ``ref`` avec la forme:
``conversion2003-action-cut-denomination;CONTENU_ORIGINAL``. Si
l'attribut ``ref`` a déjà un contenu, le processus s'arrête en
affichant une erreur.

Si il y a un élément ``<ligne>`` surnuméraire,
celui-ci est supprimé et positionné en ``<extra>``, avec émission d'un
avertissement.

Note: cette nouvelle "ligne" un peu spécifique n'aurait pas du être
définie avec 255 caractères. Il est difficile d'avoir une adresse
postale avec une telle longueur.

Lieu de formation (C2003-2002-11)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Si il n'y a pas de lieu de formation, créer un lieu vide avec la
  ligne "``à distance``" ou la valeur de l'option
  ``--empty-lieu="XXX"``.
- Si il y a plus d'un seul lieu de formation, par défaut on garde le
    premier. Avec l'option ``--keep-principal``, on garde le lieu où
    l'attribut ``info="principal"`` est défini.

Note: la langue de formation devrait être définie sur trois positions,
afin de permettre l'expression de plus de langues, notamment la langue
des signes.

Organisme formateur (C2003-2002-12)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Si il y a plus d'un seul organisme formateur, par défaut on garde le
    premier. Avec l'option ``--keep-principal``, on garde l'organisme
    où l'attribut ``info="principal"`` est défini.

Multivaluation de langue de formation (C2003-2002-13)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Si il y a plus d'un élément ``langue-formation`` dans l'élément
``action``, les éléments en surplus sont passés dans le bloc ``extras
info="conversion2003"`` de l'action.

URL de la session (C2003-2002-14)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Passage de l'URL de la session ``url-session`` dans le bloc ``extras
info="conversion2003"`` de cette dernière.

Recrutement (C2003-2002-15)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Bloc ``recrutement`` déplacé dans le bloc ``extras
info="conversion2003"`` de ``session``.
- Élément ``modalite-recrutement`` en ``extra``
- Élément ``code-perimetre-recrutement`` en ``extra``
- Élément ``infos-perimetre-recrutement`` en ``extra``
- Élément ``a-distance`` en ``extra``
- Élément ``nb-places`` en ``extra``
- Élément ``heure-debut`` en ``extra``
- Élément ``heure-fin`` en ``extra``
- Élément ``commentaire`` en ``extra``

Enseignements (C2003-2002-16)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Blocs ``enseignement`` déplacés dans le bloc ``extras
info="conversion2003"`` de ``session``.
- Élément ``libelle-enseignement`` en ``extra``
- Élément ``type-enseignement`` en ``extra``
- Élément ``obligatoire`` en ``extra``
- Élément ``commentaire`` en ``extra``

Équipements (C2003-2002-17)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Blocs ``equipement`` déplacés dans le bloc ``extras
info="conversion2003"`` de ``session``.
- Élément ``type-equipement`` en ``extra``
- Élément ``cout-indicatif-equipement`` en ``extra``
- Élément ``commentaire`` en ``extra``

Références à des certifications (C2003-2002-18)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Passage des blocs ``reference-certification`` en ``extras
info="conversion2003"`` des éléments englobants
(``organisme-formateur``, ``session``). Cet élément est également
présent dans ``blocs-competences`` mais cet élément est lui-même dans
un bloc ``extras``.

Les sous-éléments ``reference-code-RNCP``, ``reference-code-RS`` et
``reference-code-CERTIFINFO`` passent en ``extra``.

Blocs de compétences (C2003-2002-19)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Passage des blocs ``blocs-competences`` en  ``extras
info="conversion2003"`` de ``session``.
- Élément ``validation-blocs`` en ``extra``
- Élément ``reference-certification`` en ``extras``
- Élément ``bloc-competences`` en ``extras``
- Élément ``libelle-bloc`` en ``extra``
- Élément ``code-bloc`` en ``extra``


Cycles et Effectifs (C2003-2002-20)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Passage des blocs ``cycle`` en  ``extras
info="conversion2003"`` de ``session``.
- Élément ``type-cycle`` en ``extra``
- Élément ``annee-cycle`` en ``extra``
- Élément ``effectif-minimal`` en ``extra``
- Élément ``capacite-simultanee`` en ``extra``
- Élément ``capacite-cumulee`` en ``extra``
- Élément ``alternance`` en ``extras``
- Élément ``type-alternance`` en ``extra``
- Élément ``rythme-alternance`` en ``extras``
- Élément ``unite-rythme-alternance`` en ``extra``
- Élément ``unites-entreprise`` en ``extra``
- Élément ``unites-centre`` en ``extra``
- Passage de l'élément ``duree-cycle`` en  ``extras
info="conversion2003"`` de ``action``.

Table des financeurs (C2003-2002-21)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Les nouvelles entrées (celles supérieures ou égales à 18), sont
positionnées à 0 (Autre).

Le code original est conservé dans ``ref`` avec le préfixe:
``conversion2003-action-code-financeur;``.


Table des niveaux (C2003-2002-22)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Les ``code-niveau-entree`` et ``code-niveau-sortie`` sont transformés:

- Niveau V (4) <-> Niveau 3 (13)
- Niveau IV (5) <-> Niveau 4 (14)
- Niveau III (6) <-> Niveau 5 (15)
- Niveau II (7) <-> Niveau 6 (16)
- Autres niveaux supérieurs ou égaux à 11: mis à 0
- Niveaux < à 10, inchangés.

Le code original est conservé dans ``ref`` avec le préfixe:
``conversion2003-action-code-niveau;``.