Creating overlays with BPCU for existing customizations

When you upgrade BMC Cloud Lifecycle Management and you want to preserve your existing customizations, you can copy your existing AR System and ITSM customizations into overlays and custom objects, allowing them to be preserved for future upgrades.

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 workflows 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.

Before you begin

On the Enterprise-AR and Cloud-AR servers, go to the <AR_install_dir>\ARSystem directory (for example, C:\Program Files\BMC Software\ARSystem) and locate the BPCU ZIP file (for example, bpcu80_build001.ZIP).
Note

The AR System 8.1 release contains two ZIP files – bpcu80_build001.ZIP and bpcu81_build001.ZIP. Updates to BPCU (bpcuversionNumber.zip) and the Overlay hash file (OverlayHashFile.zip) between patch releases are posted to the BMC Communities website: https://communities.bmc.com/welcome.
Uncompress the ZIP file and review its contents.
By default, the BPCU files are extracted to the Best_Practice_Conversion_Utility folder (for example, C:\Program Files\BMC Software\ARSystem\bpcu80_build001\Best_Practice_Conversion_Utility). It contains the BPCU utility, the OverlayHashFile.xml file, and other supporting files.
Configure your system for BPCU. For more information, see Configuring your system for the BPCU.

To create overlays

Upgrade the Enterprise-AR and Cloud-AR servers.
Run BPCU from the command line to 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. For more information about ReportDiff mode, see Using BPCU to generate difference reports.
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"
  For example:
  bpcu -x vw-aus-clmidd06 -t 0 -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.
  The BPCU also generates some migrator .xml instruction files that are used in the upgrade process.
If the BPCU difference report shows non-permitted customizations (as shown in the following figure), resolve them:

Detailed information about these non-permitted customized objects is available in the Extensions and Customizations tabs in the HTML report:

You must fix all these active links, fields, forms, and views!
Otherwise, if you agree with the report, you can simply run BPCU in Overlay mode and convert the customizations to overlays.
Note

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.
  Note
  
  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.
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. For more information about Overlay mode, see Using BPCU to generate overlays for modified legacy 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.

Creating overlays with BPCU for existing customizations

Before you begin

To create overlays

Comments