Migrating Forms from Entry to MagicData

Este tutorial explicará como migrar formularios de versiones previas que estaban almacenadas en la tabla de entry y moverlos a almacenamiento de datos magic; así como actualizar cualquier campo mapeado que referencie valores. Para ver un ejemplo más complicado refierase al modulo Geography en iHRIS Common o el sub-modulo Education en el módulo Person en iHRIS Common.

Paso 1: Cambiar el Mecanismo de Almacenamiento de un Formulario

En iHRIS 4.0, se agregaron mecanismos de almacenamiento de datos a los formularios. El método de almacenamiento por defecto es para utilizar las tablas de entry como en las versiones previas de iJRIS. Para sistemas distribuidos es conveniente que algunos formularios se guarden en datos magic para poder manejarlos de manera centralizada más fácilmente y poder actualizarlas por medio de las actualizaciones a los módulos para mantener IDs consistentes en todos los sistemas distribuidos.

Primero debemos cambiar el almacenamiento para los formularios a datos magic en el archivo de configuración del módulo. Para versiones anteriores esta sección se debe agregar. Si desea migrar un formulario que ya tiene un almacenamiento definido, solamente debe cambiarlo a datos magic. Estos cambios estarán bajo la sección de "forms" de su configuración en la ruta: /modules/forms/forms/<form_name>. Esto solamente incluye la nueva sección de almacenamiento. Las secciones de class y display deben estar incluidos en esta formularios. También es necesario actualizar la version para este modulo e incluir ese mismo número de versión en la sección de almacenamiento.

<source lang="xml"> <configurationGroup name="forms" path="/modules/forms">

 <configurationGroup name="forms">
   <configurationGroup name="form_XXXXX">
     <configuration name="storage" values="single">
       <displayName>Storage Mechanism</displayName>
       <description>The storage mechanism for this form.</description>
       <version>X.X.X</version>
       <value>magicdata</value>
     </configuration>
   </configurationGroup>
 </configurationGroup>

</configurationGroup> </source>

Step 2: Save Data From The Previous Storage Mechanism

Now we need to make sure we save any old data before the storage mechanism is changed for the form. For example if the field person.nationality is mapped to the country form and the country form is moving from entry storage to magicdata then you'll need to save the old value so you can change it to the correct new value once the country form has been migrated. This is all done using the pre_upgrade() method for the module class for the given module. A helper method is in I2CE_FormStorage called storeMigrateData() to save this data for later reference.

You'll need to know the version that is being upgraded to so you only save the data at the correct time for this module. In the example code "X.X.X" is used. You'll also need to determine a migrate path to use for everything you'll be upgrading. This is so that everything can be referred to later in one place if you need to access it. It can be any text or even the version number you're upgraded to. It should be under the magic data path of: /I2CE/formsData/migrate_date/XXXXXX.

<source lang="php"> public function pre_upgrade( $old_vers, $new_vers, $new_storage ) {

   if ( I2CE_Validate::checkVersion( $old_vers, "<", "X.X.X" ) ) {
       $migrate_path = "/I2CE/formsData/migrate_data/MyUpgrade";
       I2CE_FormStorage::storeMigrateData( array( "FORM" => array( "FIELD1", "FIELD2" ) ), $migrate_path );
   }
   return parent::pre_upgrade( $old_vers, $new_vers, $new_storage );

} </source>

Step 3: Move Forms To The New Storage Mechanism and Migrate Any Mapped Values

Now the forms need to be migrated to the new storage mechanism and any mapped fields that were stored in the previous step need to be migrated to its new ID. This can all be done in the upgrade() method for the module class. There are two helper methods in I2CE_FormStorage to assist with this: migrateForm() and migrateField().

You'll use the same migrate path that was used in the pre_upgrade() method. You'll also need to create a user object to save the changes. Use the ID of an administrative user. You can repeat the function for every form that needs to be migrated.

<source lang="php"> public function upgrade( $old_vers, $new_vers ) {

   if ( I2CE_Validate::checkVersion( $old_vers, "<", "X.X.X" ) ) {
       $user = new I2CE_User( $user_id, false, false, false );
       $migrate_path = "/I2CE/formsData/migrate_data/MyUpgrade";

       if ( !I2CE_FormStorage::migrateForm( "FORM", "entry", $user, $migrate_path ) ) {
           return false;
       }
       
       if ( !I2CE_FormStorage::migrateField( "FORM", array( "FIELD1" => "FIELD1_MAPPED_FORM", "FIELD2" => "FIELD2_MAPPED_FORM" ),
               $migrate_path, $user ) ) {
           return false;
       }
   }
   return true;

} </source>

Step 4: Check The Migration

When you next access the site it will run the upgrade methods for any modules you have upgraded. When it has finished you will see the old data under magic data at the path: /I2CE/formsData/migrate_data/MyUpgrade (or whatever path you used). You'll also find the forms that are now stored in magic data under /I2CE/formsData/forms/. You'll want to check to make sure any fields that were migrated successfully use the new ID for each mapped value.