Customization Upgrade Utility

CA Service Desk Manager allows customers to extend the design forms as required. 
casm171
CA Service Desk Manager allows customers to extend the design forms as required. The Customization Upgrade utility facilitates smooth upgrade and merging of the customized forms into the latest CA SDM version.
Customization Upgrade for Patch Migration
If you are upgrading from 17.0, ensure to take backup of bopcfg ($NX_ROOT/bopcfg/www/htmpl) file and provide the same file path into PREVIOUS_BASE_FOLDER.
Prerequisites
  • Create a backup of the 
    site/mods
     folder. This folder is used by the utility to identify the customized files for processing.
  • Upgrade to CA SDM 17.1.
     It is recommended that you clean up the unused HTMPL and CSS files from the customization folder before merging the content.
How the Utility Works
For the utility to run successfully, the following folder locations are required:
  • Out of the box (OOTB) files from the previous release
  • Customized files
  • Out of the box files from the latest release
  • Target location of the merged files
The utility merges the customization in the OOTB files of the latest release, and then places the merged files in the target location. A log file is also generated, which indicates the status of each file:
  •  
    Merged
    : Indicates that the files merged correctly. These files can be placed in the 
    sites/mods
     folder by the administrator.
  •  
    Unable to merge
    : The files that fail to merge correctly are created with '_partial_merge' in the file name. You can use these files to merge the customization manually.
  •  
    Copied
    : When the previous or the current releases do not have a corresponding OOTB file, the utility copies the file in the target location.
 We recommend that you use the utility to merge only the HTMPL and CSS files. We currently do not provide support to merge the failed files and such files must be merged manually.
Execute the Utility
 
Follow these steps:
 
  1. In CA SDM, as an administrator, navigate to the location that contains the utility.
     When using 
    \
     as the file separator to define folder locations on Windows, use another 
    \
     as the escape character.
  2.  
    Navigate to $NX_ROOT/site/cfg/ folder, edit the 
    cu_env.properties
     file and define the following properties:
    •  
      DO_SDM_CONV
      Set the value to 1, if the CA SDM version that is being upgraded is 12.5 or earlier.
      Retain the default value, 0, if the CA SDM version that is being 12.6 and above. 
    •  
      PREVIOUS_BASE_FOLDER
      Define the location of the OOTB files from the previous release.
      For example, 
      PREVIOUS_BASE_FOLDER=$NX_ROOT/migrate/tor17_0/prer17_0/bopcfg/www/htmpl
      In case of a patch upgrade, point the variable to backup folder taken for the patch migration.
       
    •  
      CUSTOMIZED_FOLDER
      Define the location of the customized files that you saved as the backup.
      For example, 
      CUSTOMIZED_FOLDER=<Site-mods-backup-path>/www/htmpl
      If you failed to create a backup of the 
      site/mods
       folder, you can define the CUSTOMIZED_FOLDER path as $NX_ROOT/site/mods/www/htmpl folder. However, the migration process renames some HTMPL files to 
      _incompatible_for_r<major_release>_<minor_release>
       (example, _incompatible_r17_1). Rename the files back to the original name before you execute the utility.
    •  
      NEW_BASE_FOLDER
      Define the location of the OOTB files from the latest release.
      For example, 
      NEW_BASE_FOLDER=$NX_ROOT/bopcfg/www/htmpl
       
       This utility reads the folder recursively to find corresponding files to compare and merge, like any other compare tool. Therefore, the relative path to an htmpl file from PREVIOUS_BASE_FOLDER, CUSTOMIZED_FOLDER, and NEW_BASE_FOLDER folders must match.
      For example, if you want to merge 
      about.htmpl
       file that is located in 
      $CUSTOMIZED_FOLDER/web/analyst
      ; ensure that the file exists in 
      $PREVIOUS_BASE_FOLDER/web/analyst
       and 
      $NEW_BASE_FOLDER/web/analyst
       folder locations.
      If the relative folder paths mismatch, the utility might throw errors.
    •  
      MERGED_FOLDER
      Define the location of the target folder that is used by the utility to create the merged files.
       Do not define the MERGED_FOLDER path to any existing CA SDM folder, as the utility might rename the folder.
    •  
      TEMP_LOC
      Temporary location to contain the processing files.
      For example, TEMP_LOC=$NX_ROOT/temp
       Ensure enough space to contain the files in the PREVIOUS_BASE_FOLDER, CUSTOMIZED_FOLDER, and NEW_BASE_FOLDER locations.
    •  
      LOG_LOC
       
      Location that contains the log and differences files for debugging.
      For example, LOG_LOC=$NX_ROOT/log/UpgradeFactoryLogs
  3.  
    Navigate to 
    $NX_ROOT/bin
     folder and execute the following file to start the merge process:
    •  
      Windows: 
      customization_upgrade.bat
       
       
    • Unix/Linux: 
      customization_upgrade.sh
       
      When you execute the script, it prompts the variables that you defined in 
      cu_env.properties
      , which you can update, if necessary.
      The merge process runs as indicated in this image:
        merge_process.png  
      After the merge process completes successfully, you can view the result as indicated in the image:
  4. Verify the 
    $NX_ROOT/log/customization_merging.log
     log file to ensure successful merging of the customization.
    To manage the log level, edit the 
     
    $NX_ROOT/site/cfg/log4j.properties
     file.
     
  5. Manually merge the files that the utility failed to merge.
  6. Copy the files from the merged folder location to 
    $NX_ROOT/site/mods
     folder.
  7. Execute the following command on the CA SDM server to clear the cache:
    pdm_webcache -bH
Understand the Files Created in the Output Folder
  • Successfully merged files are placed in the MERGED_FOLDER with the same file extension. For example, <file_name>.htmpl; <file_name>.css
  • Partially merged files are created with 
    _partial_merge
     in the filename. For example, <file_name>.htmpl_partial_merge
    You can analyze the partially merged files and can perform the manual merge.
  • Customizations that do not have a corresponding OOTB file in the previous release are considered as new and copied in the output folder with the same name.
  •  
    Customizations that do not have a corresponding OOTB file in the latest release are considered as unmerged and copied in the output folder with the 
    _unmerged
     in the file name.
     
  • The .htmpl file format of the copied files can change based on the value defined in DO_SDM_CONV property in the 
    $NX_ROOT/site/cfg/cu_env.properties
     file.
  • The log file contains the status of each file processed.
Manually Verify the Merged Files
You can use any diff tools to verify that the merging process was successful.
 
Verification method 1: Compare the differences
 
  • Compare the files in the CUSTOMIZED_FOLDER and the MERGED_FOLDER, and
  • Compare the files in the NEW_BASE_FOLDER and PREVIOUS_BASE_FOLDER.
In both the comparisons the differences must match, which indicates that the merge was successful. If not, then, manually merge the files.
 
Verification method 2: Compare the 
 
customization
 
  • Compare the PREVIOUS_BASE_FOLDER and CUSTOMIZED_FOLDER to identify the customization
  • Compare the NEW_BASE_FOLDER and the MERGED_FOLDER to identify the customization
In both the comparisons, the customization must match. If not, then, manually merge the files.
Exceptions to Merging Customization
The merge utility fails when your customization falls under the following scenarios:
  • When the number of customizations in the file is large.
  • When the customized content location has changed only slightly, that is, immediately before or after the customized content, the utility fails to find the reference location and eventually fails.
  • When the customized file is split into multiple OOTB HTMPL and CSS files.