Customization Upgrade Utility
CA Service Desk Manager allows customers to extend the design forms as required.
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.
- Create a backup of thesite/modsfolder. 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 thesites/modsfolder 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:
- 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.
- Navigate to $NX_ROOT/site/cfg/ folder, edit thecu_env.propertiesfile and define the following properties:
- DO_SDM_CONVSet 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_FOLDERDefine the location of the OOTB files from the previous release.For example,PREVIOUS_BASE_FOLDER=$NX_ROOT/migrate/tor17_0/prer17_0/bopcfg/www/htmplIn case of a patch upgrade, point the variable to backup folder taken for the patch migration.
- CUSTOMIZED_FOLDERDefine the location of the customized files that you saved as the backup.For example,CUSTOMIZED_FOLDER=<Site-mods-backup-path>/www/htmplIf you failed to create a backup of thesite/modsfolder, 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_FOLDERDefine the location of the OOTB files from the latest release.For example,NEW_BASE_FOLDER=$NX_ROOT/bopcfg/www/htmplThis 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 mergeabout.htmplfile that is located in$CUSTOMIZED_FOLDER/web/analyst; ensure that the file exists in$PREVIOUS_BASE_FOLDER/web/analystand$NEW_BASE_FOLDER/web/analystfolder locations.If the relative folder paths mismatch, the utility might throw errors.
- MERGED_FOLDERDefine 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_LOCTemporary location to contain the processing files.For example, TEMP_LOC=$NX_ROOT/tempEnsure enough space to contain the files in the PREVIOUS_BASE_FOLDER, CUSTOMIZED_FOLDER, and NEW_BASE_FOLDER locations.
- LOG_LOCLocation that contains the log and differences files for debugging.For example, LOG_LOC=$NX_ROOT/log/UpgradeFactoryLogs
- Navigate to$NX_ROOT/binfolder and execute the following file to start the merge process:
- Unix/Linux:customization_upgrade.shWhen you execute the script, it prompts the variables that you defined incu_env.properties, which you can update, if necessary.The merge process runs as indicated in this image:After the merge process completes successfully, you can view the result as indicated in the image:
- Verify the$NX_ROOT/log/customization_merging.loglog file to ensure successful merging of the customization.To manage the log level, edit the$NX_ROOT/site/cfg/log4j.propertiesfile.
- Manually merge the files that the utility failed to merge.
- Copy the files from the merged folder location to$NX_ROOT/site/modsfolder.
- 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_mergein the filename. For example, <file_name>.htmpl_partial_mergeYou 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_unmergedin 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.propertiesfile.
- 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
- 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.