Migrating Forms from Entry to MagicData

This tutorial will explain how to migrate forms from previous versions that were stored in the entry table and move them to magic data storage as well as update any mapped fields that referenced the values.

Step 1: Change a Form's Storage Mechanism

In iHRIS 4.0, storage mechanisms were added to forms. The default storage method is to use the entry tables as in previous versions of iHRIS. For distributed systems you may want to have some forms be stored in magic data so they can be managed centrally more easily and can be updated by module updates to keep consistent IDs across all the distributed systems.

First we need to change the storage for the form to magic data in the module configuration file. For earlier versions this section needs to be added. If you're migrating a form that already has storage defined, you just need to change the storage to be magic data. These changes will be under the "forms" section of your configuration at the path: /modules/forms/forms/<form_name>. This just includes the new storage section. The class and display sections should already be there for this form. You'll also need to update the version for this module and include that same version number in the storage section.

<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>