This documentation applies to the 8.1 version of Remedy Action Request System, which is in "End of Version Support."

To view the latest version, select the version from the Product version menu.

Stage 3 - Create overlays for existing customizations

In stage 3, you copy your existing customizations into overlays and custom objects, allowing them to be preserved for future upgrades. This includes customizations to BMC Remedy AR System server and all other applications and components.

The following figure shows how the Best Practices Conversion Utility (BPCU) is used to create overlays and custom objects from your existing objects. If you customized workflow by copying and disabling an application object, you need to run BPCU twice. Otherwise, you need to run it only once. Object 1 is a customized version of workflow object 2, so object 1 is converted into an overlay of object 2. Because object 3 is a modified application object, object 7 (a new object), is created as an overlay of object 3. Object 6, which was created in the production environment is converted into a custom object.

  • The upper plane shows the overlay group, which contains overlays, custom objects, and origin objects that have not been overlaid.
  • The lower plane shows the base group, which contains only origin objects.

To create overlays

  1. Find out what objects have been modified.
    In particular, determine which objects have been modified in ways that are not permitted in overlays. For any such objects, this can prevent an application upgrade from succeeding, if the upgrade affects that object.
    Running the BPCU in ReportDiff mode allows you to determine such modifications, and to make the necessary corrections before upgrading any applications. It compares the current objects to a set of base objects that are defined in an overlay hash file.
    To generate a BPCU difference report:
    1. At a command prompt, change directories to the BPCU installation directory, <utilityInstallDir>/Best_Practice_Conversion_Utility.
    2. Run the BPCU in ReportDiff mode, and compare objects on StagingServer with those in the overlay hash file:
      bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m D -f "<hashFileLocation>\OverlayHashFile.xml"

      A BPCU difference report, bpcu-diff-report_date_timestamp.html, is generated and placed in the <utilityInstallDir>\Best_Practice_Conversion_Utility\output folder. The report is an HTML-formatted file that displays a list of the extensions and customizations in your setup, and indicates whether the extensions and customizations are permitted or non-permitted.
      The BPCU also generates some migrator .xml instruction files that are used in stage 5 of the upgrade process.
  2. If the BPCU difference report shows non-permitted customizations, resolve them.


    Ensure that you have set your BMC Remedy Migrator configuration options before performing the following procedures.

    1. Install a reference server (ReferenceServer) that is the same version as your production AR System server, and install copies of all applications that are running on your production server. (The installed applications must be the same version as the applications on your production server, including patches and hotfixes.) The reference server will have only unmodified origin objects from the BMC released software, with no customizations.
    2. On ReferenceServer and StagingServer, use the Migrator command-line interface to create a .migrator file that contains only the objects with non-permitted customizations. Then, use Migrator to compare the two files.
    3. For each object that contains a non-permitted modification, perform the appropriate corrective action.
    4. After fixing all non-permitted modifications, delete your Migrator instruction files and the difference report from the output folder.
    5. Run the BPCU again in ReportDiff mode to generate a clean set of instruction files based on your server after you have removed all non-permitted customizations.


      The clean Migrator instruction files are the instruction files that you will use in stage 5 of the upgrade process.

      These corrective actions allow BPCU to preserve an object as a custom object that does not conflict with a BMC application object, or the corrective actions allow BPCU to create an overlay from the object.
  3. Create overlays or custom objects from your customizations so that they will be preserved across an application upgrade.
    To do this, run the BPCU again in Overlay mode to create overlays and custom objects.
    In some cases, BMC application objects might have been copied and disabled, with modifications made to the enabled copy. Generally, such copies have names that are the same as the original object name appended with a well-known prefix or suffix. In other cases, BMC application objects might have been modified directly, or there may be a mixture of these methods.
    If at least some of your customizations are copies of original objects with names that have well-known prefixes or suffixes, perform the following steps:
    1. For each object, if its name contains both a prefix and a suffix, remove one or the other. Otherwise, the BPCU does not convert the object. 
    2. If you created copies of original objects but did not use prefixes or suffixes to identify them, rename those copies to include a prefix or a suffix. 
    3. Run BPCU in Overlay mode with the -P and -S options.
      bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>\OverlayHashFile.xml" -P "prefix1,prefix2,..." -S "suffix1,suffix2,..."
      BPCU makes the following changes to active links, filters, and escalations:
      • If the origin object is enabled, BPCU marks the copy as a custom object.
      • If the origin object is disabled, BPCU converts the copy into an overlay of the origin object.
        The -P and -S options allow BPCU to convert active links, filters, and escalations into overlays when they are copies of disabled origin objects.
    4. Run the BPCU in Overlay mode again without the -P and -S options.
      bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>\OverlayHashFile.xml"
      The BPCU generates overlays for directly changed origin objects.

If your customizations are only in modified origin objects that have not been copied and renamed, perform the following step:

  • Run BPCU in Overlay mode without the -P or -S option.
    bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>\OverlayHashFile.xml"
    The BPCU generates overlays for the modified objects and converts any user-created objects to custom objects.

Related topics

Where to go from here

Stage 4 - Acquire origin objects (optional)

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.