Creating overlays with BPCU for existing customizations and future upgrades
When you upgrade BMC Cloud Lifecycle Management and you want to preserve your existing customizations, use the Best Practices Conversion Utility (BPCU) to copy your existing AR System and ITSM customizations into overlays and custom objects. This allows them to be preserved for future upgrades.
To summarize this process, say that you are upgrading from version 3.1 (which consumes AR System 7.6.04) to version 4.1 (which consumes AR System 8.0). To preserve your customizations, you first run BPCU in difference mode (-m D) after you finish the AR System upgrade to 8.0. This creates a report which lists the non-permitted customized objects as well as objects modified or added in base mode. For example, the following report shows three customized fields that are not permitted.
If you do not fix these field objects and convert them to overlay, your customizations would not be preserved in future upgrades.
You then run BPCU a second time in overlay (-m o) mode to generate overlays for the customized objects. As a result, any future upgrades would not modify these overlaid objects and your customizations will be preserved.
This topic contains the following information:
How BPCU creates overlays and custom objects from existing objects
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.
Before you begin
- Upgrade the Enterprise-AR and Cloud-AR servers to version 8.1.01.
- 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, bpcu81_build001.ZIP).
- Uncompress the bpcu81_build001.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\bpcu81_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.
Contact BMC Support to obtain a special overlay hash file that contains BMC Cloud Lifecycle Management objects with the appropriate ITSM version for your environment. Then copy this special overlay hash file to the Enterprise-AR and Cloud-AR hosts, for example, C:\Windows\Temp.
- Take a snapshot of the Enterprise-AR and Cloud-AR hosts and, at the same time, back up their databases.
To create overlays
- 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:- At a command prompt, change directories to the BPCU installation directory,<utilityInstallDir>/Best_Practice_Conversion_Utility.
Run the BPCU in ReportDiff mode, and compare objects on StagingServer with those in the special overlay hash file:
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m D -f "<hashFileLocation>\31SP1PMergedWith8.0.xml"For example:
bpcu -x vw-aus-clmidd06 -t 0 -u Demo -p "" -m D -f "C:\Windows\TEMP\31SP1PMergedWith8.0.xml"
A BPCU difference report (bpcu-diff-report_date_timestamp.html) is generated (for example, bpcu-diff-report_20151020_1445382817.html) 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 the upgrade process.
- If the BPCU difference report shows non-permitted customizations (as shown below), 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! (For detailed information on how to do this, see Fixing nonpermitted modifications in the ITSM documentation)
Otherwise, if you agree with the report, you can simply run BPCU in Overlay mode and convert the customizations to overlays. - Run the BPCU in Overlay mode to create overlays and custom objects from your customizations so that they will be preserved across an application upgrade.
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>\OverlayHashFile.xml"
For example:
bpcu -x vw-aus-clmidd06 -t 0 -u Demo -p "" -m o -f "C:\Windows\TEMP\31SP1PMergedWith8.0.xml"
As shown below, the BPCU generates overlays for directly changed origin objects and the modified objects, It also converts any user-created objects to custom objects. For more information about Overlay mode, see Using-BPCU-to-generate-overlays-for-modified-legacy-objects.
Related topic