Migration périphérique

De manière générale, si vous utilisiez déjà Pims dans une version précédente, il est souvent nécessaire de migrer les données. Pour cela

1. Connectez-vous à la BD PimsDB, avec PgAdmin par exemple, en utilisant le user pims_db_user (cf. chapitre Config postgresql)
2. Exécuter un ou plusieurs fichiers de migration (voir ci-dessous) de la même façon que l'on exécute ePimsModel.sql (cf chapitre postgresql ).

La base de données ePims est versionnée depuis ePims 4.0M2. Pour connaitre la version de votre BD, exécuter la requête SQL suivante:

select max(model_version) from admin_infos 

Selon la version affichée, vous devez exécuter tous les scripts Data_Migration ayant un suffixe supérieur. Par exemple, si vous avez la version 4, vous devez exécuter les scripts:

• Data_migration-5.sql
• Data_migration-6.sql (cf chapitre suivant pour les spécificités de la version 6)

Pour les versions précédentes de la BD dans lesquelles il n'y avait pas de numéro de version enregistré, la correspondance entre les versions ePims et les scripts sont

• ePims version 2.x ⇒ BD version 0, vous devez exécuter les scripts à partir de Data_migration-1.sql
• ePims version 3.3 ⇒ BD version 1, vous devez exécuter les scripts à partir de Data_migration-2.sql

Attention, le passage en version 6 de la BD, certaines étapes spécifiques doivent être suivies suite à une modification importante autour de la gestion des fichiers attachés aux données.

1. Incohérence attached_file.path:

Exécuter la commande suivante afin de vérifier si il y a des incohérences entre le path et le type des fichiers enregistrés dans la base

      select * from attached_file
      where attached_file.path not like ('%/' || attached_file.file_type || '/')

Si c'est le cas, faire les modifications manuellement afin

• de lever cette incohérence dans la base
• de modifier le PIMS_ROOT pour qu'il soit correcte si les données n'ont pas été archivées.

Une incohérence est possible pour les installations d'ePims qui ont été réalisé avec des versions antérieures à la version 3.0 d'ePims !! Par exemple, dans le cas où le path fini par 'demande_analyse' au lieu de 'analyse_request', exécuter :

      update attached_file
      set path = regexp_replace(path, '/demande_analyse/', '/'||file_type || '/')
      where id in (
              select attached_file.id from attached_file, study_attached_file
              where attached_file.path not like ('%/' || attached_file.file_type || '/')
              and study_attached_file.file= attached_file.id
      )

2. Ajouter le langage procédural

Pour certaines modifications, il est nécessaire d'ajouter le support du langage plpgsql à la BD pims. Normalement toute installation postgresql supporte ce langage procédural. Cette commande doit être exécuter en tant que superuser

      CREATE LANGUAGE plpgsql;

3. Exécuter le script de migration : Exécuter le script Data_migration-6.sql qui :

• crée les tables file_tags, tag, file_link
• ajoute archived et size_mo dans la table attached_file
• renseigne la table file_link avec les anciennes valeurs de study_attached_file et sample_attached_file
• positionne attached_file.archived à vrai pour les entités archivées
• associe les fichiers non associés à un échantillon ou à une étude (seuls deux cas possibles) à l'étude référencé dans le path du fichier. Ce path DOIT alors être de la forme (sinon c'est un problème dans la BD …) …/<std_nomenclature>/file_type.
• pour les fichiers associés aux échantillons modifies le path (de /samples/… à samples/data/…)
• pour les fichiers associés aux études modifies le path (de /<std_nomenclature>/… à /<std_nomenclature>/data/…)
• supprime les tables study_attached_file et sample_attached_file

et qui migre acquisition_result dans attached file :

• renseigne les tables file_link et attached_file à partir des tables acquisition_result - acquisition - protocol_application

4. Vérifier les orphelins de la table attached_file

Afin de s'assurer qu'il n'y a pas d'enregistrement d'attached_file associé à aucune entité, exécuter :

      select * from attached_file where attached_file.id NOT IN (
              select distinct fl.attached_file from file_link as fl
      )

Si il existe de tels fichiers, il est alors nécessaire de corriger manuellement les erreurs…. et au final

• de créer le file_link adéquat
• de copier les fichiers dans le nouvel emplacement
• de modifier le path d'attached_file

5. Suppression des dernières tables - colonnes après les ultimes vérifications

Exécuter le script Data_migration-6final.sql qui :

• supprime la colonne ayant permit de faire le lien entre attached_file (issue de acquisition_result) et acquisition référencé dans file_link
• supprime les tables migrées (study_attached_file, sample_attached_file et acquisition_result)
• supprime la colonne result d'acquisition ( remplacé par FileLink …)
• supprime la colonne file_type d'attached_fie (remplacé par le lien avec Tag)

Pour la version 4.0 (à partir de la 4.0RC1) le répertoire de données d'ePims à subit une modification dans sa structure (par exemple les fichiers de données de spectroscopie ne sont plus contenu dans les dossier [étude]/raw mais dans [étude]/samples/data/RAW). Afin de faire migrer le répertoire dans la bonne structure un programme a été créé : ePimsRoot-pre4.0-migration.jar .

Ce programme s'utilise en ligne de commande (shell sous UNIX ou “Démarrer ⇒ Exécuter ⇒ cmd” sous Windows). Il nécessite d'avoir Java 1.5 d'installé sur la machine qui va l'exécuter.

java -jar ePimsRoot-pre4.0-migration.jar -pimsroot [chemin vers le répertoire ePims] -v

Un fichier de logs sera créé automatiquement dans le dossier où s'exécute le programme, son nom étant ePimsRoot-pre4.0-migration.log. Nota : Sous LINUX il faut faire attention à l'utilisateur qui exécute le programme. Il doit être le même que l'utilisateur auquel sera identifié ePims pour gérer son dossier source (ou ce dernier doit avoir des droits supérieur).

Pour fonctionner ce programme doit avoir la liste des noms de répertoires utilisés pour l'organisation actuelle du répertoire racines d'ePims. Cette liste est celle définie dans le fichier eP-Core.properties lors de l'installation d'ePims. Par défaut il utilise les valeurs suivantes :

PIMS_REPOSITORY_1=a
PIMS_REPOSITORY_2=b
PIMS_REPOSITORY_3=c
PIMS_REPOSITORY_4=d
PIMS_REPOSITORY_5=e
STUDY_RAW_DIR=raw
STUDY_SPECTRA_DIR=spectra
STUDY_RESULTS_DIR=results
STUDY_SAMPLES_DIR=samples
STUDY_SEARCH_DIR=search
STUDY_ANALYSIS_REQUEST_DIR=analysis_request
STUDY_OTHER_DIR=others
STUDY_CARDS_DIR=forms
STUDY_SCANS_DIR=scans
STUDY_ANNOTATIONS_DIR=annotation

Si ces valeurs ne correspondent pas à votre installation d'ePims vous devez spécifier au programme d'autre valeurs. Pour ce faire il faut créer un fichier texte contenant les propriétés qui changent par rapport aux valeurs par défaut. Par exemple :

PIMS_REPOSITORY_1=repo1
PIMS_REPOSITORY_2=repo2
STUDY_SPECTRA_DIR=mgf

(Nota, cas spécial pour les repository : redéfinir un PIMS_REPOSITORY annule toute les valeurs des autres repository par défaut. Dans l'exemple précédent le programme ira chercher les repository dans les dossier repo1/, repo2/ mais pas dans c/ d/ e/ même si PIMS_REPOSITORY_3 4 et 5 n'ont pas été redéfinis).

Il faut utiliser l'argument -properties suivi du chemin d'accès au fichier que vous avez écrit.
Exemple :

java -jar ePimsRoot-pre4.0-migration.jar -pimsroot [chemin vers le répertoire ePims] -v -properties /temp/properties_file.txt

Les propriétés UNDEF_DIR_NAME, PIMS_SHARE, PIMS_SYSTEM, PIMS_ARCHIVE, PIMS_ARCHIVE_FILE ne sont pas utilisées par le programme de migration. Si vous les incluez dans le fichier listant les nouvelles valeurs, le programme affichera une erreur : ERROR in given properties file. Element [propriété] isn't recognize as a valid property.. Si [propriété] est une de celle non utilisée, ne vous inquiétez pas, cela ne posera pas de problème pour la migration.

java -jar pimsRoot-pre4.0-migration.jar -pimsroot dir [-v] [-noLogFile] [-properties file]

• -h, --help
  • Affiche les infos sur les arguments et les valeurs par défaut utilisées par le programme.

• -pimsroot dir
  • Pour donner le chemin et le nom du dossier source d'ePims.

• -v, --verbose
  • Pour afficher les logs dans la console

• -noLogFile
  • Pour empécher le programme de créer un fichier de logs. ATTENTION Si vous utilisez ce paramètre vous n'aurez pas de trace de ce que le programme fera et des éventuelles erreurs (sauf dans la console si vous avez utilisé l'argument -v mais la console à généralement une taille définie qui ne vous permettras peut-être pas de remonter tout les logs).

• -properties file
  • Pour définir un fichier listant les nouvelles propriétés à utiliser par le programme.
  • Le fichier doit être de la forme :

PROPERTY1=VALUE1
PROPERTY2=VALUE2
etc...