Customisation Migration to V5

Version Relevance: V5

Issue: I want convert my V4.10 customisation to V5. What is the best procedure to follow.

Jan 31st, 2015

Feedback: This is the sort of folder structure we recommend starting with. .....

Folder Structure

Copy the following files to it:

Folder File Source Notes
Company     Container for the project.
V410     Container for the original of V4.10 customisation.
V410 OpenVisionV410.lbs Copy the up-to-date OpenVision.lbs from the V4.1 master Vision\Custom folder. It may be named differently. Original V4.10 Customisation master library.
V500     Container for the stages of V500 conversion.
1-MigratedProgUser ProgUser.db ServerFolder\ProgCode.db created during data migration from ProgCode.usa by the V4to5Upgrade.lbs tool. This will only be present if you have custom file classes in your V4.10 customisation.
2-OpenVisionConvO$6.1 Stage1.lbs Copied from V410 above and renamed then opened in Omnis Studio V6.1 so it is converted to V6.1 format. This contains all of the original customisation.
3-V4to5OpenVision Stage2.lbs Copy from Vision\Upgrading\V4to5OpenVision.lbs and rename. This special version of OpenVision contains all standard V4.1 file classes and is needed to maintain references to fields in custom classes before they are converted to columns. This library is where all the conversion will take place.
4-OpenVision Stage3.lbs Copy from Vision\Custom\OpenVision.lbs and rename. This is the destination for classes converted in Stage2.lbs above.
5-MergedNewOpenVision OpenVisionV500.lbs Copied from Stage3.lbs above and renamed. When conversion is fully completed this is the final V5.00 master library that will be copied to the Vision/Custom folder.
5-MergedNewOpenVision ProgUser.db Created by the CMS from the customised classes in OpenVisionV500.lbs above. Will be destined for the optServerFolder of the V5 installation.

Procedure, step-by-step (if you do not have custom file classes, skip stages 2 to 11):

  1. Prepare the customisation folder tree as illustrated and noted in the table above.
  2. Open Vision in the Design Omnis Studio 6.1. Logon to the migrated data.
  3. Copy V500\1-MigrateProgUser\ProgUser.db and V500\2-OpenVisionConvO$61\Stage1.lbs to the Vision\Custom folder.
  4. In Vision operate File -- Advanced -- Custom Features Utility to open the custom libraries.
  5. Operate File -- Advanced -- Change Management System.
  6. Read the CMS data file. The new custom schema and table classes will be listed.
  7. Select all lines listed.
  8. Select the library STAGE1 in the drop-down toolbar list.
  9. Click on the "Copy classes to the selected Library" tool.
  10. When complete, close windows and then close the VISION library.
  11. Cut the Vision\Custom\Stage1.lbs and paste into Company\V500\2-OpenVisionConvO$6.1\.
  12. In Omnis Studio Design manually open the libraries Company\V500\2-OpenVisionConvO$6.1\Stage1.db and Company\V500\3-V4to5OpenVision\Stage2.db. STAGE1 and STAGE2 libraries will be listed in the Omnis Studio browser.
  13. You should rename all the old custom report classes that substitute for standard classes in STAGE1 by appending a prefix to the classname, say "_V4". This is important because in STAGE2 all new custom report classes that substitute for standard classes will need to have their original names, and you will want both old and new classes coexisting in STAGE2. Substituted reports can not be converted as is. They must be re-customised from the new master standard classes.
  14. Now you have to manually copy all customisation classes from STAGE1 to STAGE2. Start with file classes only (needed to retain field references). Include new schema and table classes, if any. DO NOT copy oCustom1 which will need to be converted method by method, if it contains customisation.
  15. When complete, close the STAGE1 library. STAGE2 should contain no #??? references (use Find to check).
  16. STAGE2 is now the single library where conversion is carried out. When custom classes have been converted, they should be copied to STAGE3 which is the ultimate target of fully converted classes. Never copy a file class into STAGE3 (* see below).
  17. When everything is done, copy Company\V500\4-OpenVision\Stage3.db to Company\V500\5-MergedNewOpenVision\ and rename to OpenVisionV500.lbs.

Notes on the conversion process in STAGE2:

  1. The copy of Vision.lbs you are using should be a duplicated installation specific for the Customer site being worked on. It should also NOT have a optServerFolder set in Terminal.inf so that you can be sure it acts only on local folders. For instance you may want to add Dynamic Queries to Statements.db.
  2. Work on STAGE2 should be done while logged-on to Vision. This is because only with VISION open will the Interface Manager be available for task methods and so that superclasses will be available.
  3. You will probably want to copy classes to VISION for testing, so it should be logged into the company data appropriate for customisation.
  4. If there are custom schema classes you should check relationship columns are of the correct matching data type. Many Number 0dp or Short Number 0db key columns have changed in V5 to Integer 32bit. This is needed as some engines will error on a join if the datatypes miss-match: Note that if you do change schema class columns you will need later (after customisation is completed and fully applied) to synchronise the database from File -- Advanced -- Reset Data Files. Note that in V5 column names must be case-insensitive-unique within the totality of the main database.
  5. Also, if there are custom schemas, you should make use of the features of cCustomDataChanges to impose custom relationships. You should also check the $GetIndexesList in any custom table classes to make sure appropriate indexes are maintained for custom tables.
  6. There are two types of custom reports: Standard substitutes and Custom window driven. Standard substitutes reports must be reconstructed completely from a duplicate of the new standard report. You can generally establish what standard class was originally used from the $MasterClass report method (if created in V4.10) or from object names on the report that typically prefix with the original class name, or close to it. Custom window driven reports can typically be converted directly, replacing all CRB field references with instance variable references, and of course modifying the window driving code appropriately.
  7. For very complex report that derive from Dynamic Query driven reports it can be quicker to convert the report from it's V4.1 version by:
    1. Removing $mainfile and $mainlist
    2. Adding VISION.rSuper to $superclass
    3. In $construct replace the line Do "$ctask.tPrint.$ReportConstruct($cinst)" with "Do inherrited"
    4. Change all fields to iRow.<FieldName>
  8. It is recommended you use a large monitor when converting reports so you can view both old and new side-by-side.

Checking You Have not Lost Column References: When you have finished all migration in STAGE2 open STAGE3. Copy the new custom classes into STAGE3. Then expand it and click into in and then Find (check it is Find and Replace: STAGE 3) #???. If you get anything found, print the report. Return to STAGE2 and fix all the #??? errors. Finally re-copy all the custom classes again into STAGE3 and re-check for #???.

Testing The Customisation: The best approach here is to start with a new Vision folder tree within the Company folder. Make sure the Terminal.inf file has no optServerFolder entry.

It makes sense to make a completely new migration of the data (as you may have changed schema column definitions), so the first thing to do is copy the custom Schema and Table classes (if any) into the fresh V4to5Migration.lbs. These you can obtain from the Company\V500\5-MergedNewOpenVision\OpenVisionV500.lbs.

But you also need in V4to5Migration.lbs the original custom file classes, and those you can copy from Company\V500\3-V4to5OpenVision\Stage2.lbs.

With both old file and new schema and table classes in V4to5Migration.lbs, you can proceed with a fresh migration of data.

Now you need to prepare Vision.lbs with your customisation:

  1. Copy the contents of Company\V500\5-MergedNewOpenVision\ to the local Custom folder.
  2. Launch Vision and connect create Logon Settings for Data\TrainingDemo.db so you can work with the Change Management System unconnected to your migrated data.
  3. Open the Change Management System and Custom Feature Utility.
  4. Select your custom library and list all classes.
  5. Now select all your custom classes.
  6. Save these to the ProgUser,db database and then switch to viewing the ProgUser,db contents. Select all lines and then in the library list VISION. Copy all the classes to VISION.
  7. Now VISION is loaded with your customisation and you can close and re-open selecting the migrated database which will contain any custom data.
  8. Test all your customisation. If you need to adjust anything, make sure you note the class name. These will, after testing, need to be copied back into your OpenVision and yhen to the ProgUser.db.
  9. Remember to only use the V4to5Migrate.lbs you have loaded earlier with custom file, schema and table classes (which need to be up-to-date if testing lead to changes) for the final live data migration.

Chris Ross - Caliach Design