Skip to content
CA Service Management - 14.1
Documentation powered by DocOps

The Customization Upgrade Utility

Last update September 12, 2017

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.


  • Before implementing CA Service Management, backup the Out of the box (OOTB) web directory located at $NX_ROOT/bopcfg/www/htmpl

  • Copy the backup directory to $NX_ROOT/samples/customization_upgrade/htmpl/original folder.

  • Create a backup of the site/mods folder. This folder is used by the utility to identify the customized files for processing.

  • Implement the CA Service Management for CA SDM.

    Tip: We recommend 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.

Important! 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.

    Important: 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 file and define the following properties:
      Set the default value to 0.
      Define the location of the OOTB files from the previous release.
      For example, PREVIOUS_BASE_FOLDER=$NX_ROOT/samples/customization_upgrade/htmpl/original
      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_r14_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, NEW_BASE_FOLDER=$NX_ROOT/bopcfg/www/htmpl

      Important! 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.


      Define the location of the target folder that is used by the utility to create the merged files.

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

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

      Note: When you execute the script, it prompts the variables that you defined in, which you can update, if necessary.

      The merge process runs similar to the one as indicated in this image:

      After the merge process completes successfully, you can view the result similar to the one 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/ 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/ 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.
Was this helpful?

Please log in to post comments.