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 the 
     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:
    : Indicates that the files merged correctly. These files can be placed in the 
     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.
    : 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.
    Navigate to $NX_ROOT/site/cfg/ folder, edit the
     file and define the following properties:
      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. 
      Define the location of the OOTB files from the previous release.
      For example, 
      In case of a patch upgrade, point the variable to backup folder taken for the patch migration.
      Define the location of the customized files that you saved as the backup.
      For example, 
      If you failed to create a backup of the 
       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 
       (example, _incompatible_r17_1). Rename the files back to the original name before you execute the utility.
      Define the location of the OOTB files from the latest release.
      For example, 
       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 
       file that is located in 
      ; ensure that the file exists in 
       folder locations.
      If the relative folder paths mismatch, the utility might throw errors.
      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.
      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.
      Location that contains the log and differences files for debugging.
      For example, LOG_LOC=$NX_ROOT/log/UpgradeFactoryLogs
    Navigate to 
     folder and execute the following file to start the merge process:
    • Unix/Linux:
      When you execute the script, it prompts the variables that you defined in
      , 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:
  4. Verify the 
     log file to ensure successful merging of the customization.
    To manage the log level, edit the 
  5. Manually merge the files that the utility failed to merge.
  6. Copy the files from the merged folder location to 
  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 
     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 
     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 
  • 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.