Using BPCU to generate overlays for modified legacy objects
In Overlay mode, the Best Practice Conversion Utility (BPCU) compares objects in an overlay hash file with the objects on a server, generates a report of their differences, and performs the following tasks based on the contents of the report:
- For permitted customizations, BPCU generates an overlay by creating a copy of each object, and sets its Overlay property to Overlay.
- For permitted extensions, BPCU generates a custom object and sets the Overlay property to Custom.
In Overlay mode, BPCU ignores all the overlay, overlaid, and custom objects on the server. Therefore, running BPCU multiple times in Overlay mode does not cause problems for such objects, including objects that are shared among applications.
To generate overlays for pre-7.6.04 objects
- Generate a difference report, and fix all the non-permitted extensions and customizations that are identified.
If non-permitted extensions and customizations are found among the set of objects to be processed, BPCU does not run in Overlay mode. - At the command prompt, go to the <utilityInstallDir>\Best_Practice_Conversion_Utility folder.
- Run BPCU in Overlay mode by executing the following command with the appropriate arguments (see the following table):
- (Microsoft Window)
bpcu.bat
- (UNIX)
bpcu.sh
- (Microsoft Window)
Command-line options for Overlay mode
Option |
Description |
---|---|
|
Name of the server on which to perform the operation. |
|
User name. |
|
User password. |
|
(optional) User authentication string. |
|
(optional) TCP port of the server on which to perform the operation. |
|
(optional) RPC port of the server on which to perform the operation. |
|
Absolute path to the overlay hash file provided by BMC (include full path and file name). |
|
(optional) Full path to the XML file containing a list of objects to include in or to exclude from the operation. Note Following sample files are available bpcu<version>.zip file:
|
|
(optional) Comma-separated list of form names whose associated fields and views are the only objects processed by the operation. |
|
(optional) Name of the difference report. Do not include a file extension. |
|
(optional) Format of the difference report. Values are:
|
|
Utility mode. Values are |
|
(optional) Indicates whether to display or hide the list of objects that are skipped during conversion.
|
|
Comma-separated list of prefixes in the names of user-created objects. |
|
Comma-separated list of suffixes in the names of user-created objects. |
|
(optional) Flag that specifies whether to include overlay and custom objects in the "addition" section of the difference report. Values are:
|
The differences report that BPCU generates
BPCU generates a report that shows differences between the unmodified objects represented in an overlay hash file and objects on a server. It also shows which changed objects can be converted into overlays or custom objects, and which objects have been changed in a way that makes the conversion impossible.
Difference reports are produced in HTML, comma-separated values (CSV), or Microsoft Excel (XLSX) formats. By default, the report name uses the following format:
bpcu-diff-report_date_timestamp.extension
Difference reports are stored in the <utilityInstallDir>\Best_Practice_Conversion_Utility\output folder.
The following table describes the information that a difference report provides about objects and where you can find the information.
Information in a difference report generated by BPCU
Information |
XLSX report format |
HTML report format |
---|---|---|
Statistical information about all types of objects found on the server where BPCU was executed:
|
Dashboard worksheet |
Dashboard tab |
Whether an object on the server is new |
Difference Report |
Extensions tab |
Whether an object on the server has been modified |
Difference Report |
Customizations tab |
Whether modified objects in the server contain permitted or nonpermitted modifications:
|
Difference Report worksheet, rows with the value Customization in the Customization Type column
|
Customizations tab, all panels
|
|
Execution Information worksheet |
Execution Information tab |
Note
BPCU does not include information in a difference report about objects that are unchanged.
BPCU HTML report Dashboard tab
(Click the image to expand it.)
BPCU HTML report Extensions tab
(Click the image to expand it.)
Convertible to Overlay column in Customizations tab indicates whether the customization is permitted in overlays
(Click the image to expand it.)
BPCU HTML report--Execution Information tab
(Click the image to expand it.)
Related topics
Stage 3 - Create overlays for existing customizations for an example
of using the bpcu
command to generate overlays
Using BPCU to generate difference reports
Permitted and non-permitted modifications on overlays
Comments
Can you please provide an example of the XML file for the -c option. The structure of the file does not seem to be documented anywhere.
Hi Latzko,
Thanks for your comment. I am working with the SME to update the topic.
-Hemant
Hi Hemant! I just found an example file plus documentation as part of the bpcu distribution.
The file names are: obj-filter-lst_template.xml (sample file) obj-filter-lst_template.txt (=readme).
Joachim.
There is a description for option -e: "...Do not use this option with the
-s
option." The description for -s option (lower case) is missing.Hi Juraj,
The -s(lowercase) option is only for internal use. It is not relevant to end users. I have updated the docs and removed the reference.
Thanks,
Hemant
The - P and -S options for prefix and Suffix works only for Active Links, Filters and Escalations. Is that a correct statement? If that is the case the section where it describes -P and -S options at this page should be updated.
Also in a previous section following is a subtext for -P and -S option.
"The -P and -S options allow BPCU to convert active links, filters, and escalations into overlays when they are copies of disabled origin objects"
Here is the link to the previous section.
https://docs.bmc.com/docs/display/public/ars81/Stage+3+-+Create+overlays+for+existing+customizations
Its just very confusing with two different descriptions at two places for these options.
Thanks,
Debasish
Hi Debasish,
I will verify the option details with the SME and update the topic.
Thanks,
Poonam
Hi Poonam,
Did you get a chance to verify with the SME?
Thanks,
Debasish Hazarika
Sorry for the delay in response. I am verifying this with the SME and will get back to you soon.
Thanks,
Poonam Morti
Hi Debasish,
The prefix and suffix parameter is applicable to all objects.
Behaviour with reference to active links, filters and escalations is as follows.
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.
If you disable out of the box object and copy the same with prefix and suffix, make their customization and if you do not specify prefix or suffix, BPCU converts the object to custom and leaves old and new object in the system. This can cause functional issues.
Thanks,
Poonam
Hi Poonam,
Thanks for your response. However. it doesn't address my original question.
BPCU when ran with -P and -S option does take care of Active Links , Filters and Escalations and that is well understood.
But from my experience I don't see it taking care of Guides and Menus(any container objects) or I am not very sure what the behavior of it should be with Container objects when ran with -P and -S option. And BPCU not taking care of Guides/Menus makes sense since those objects cannot be enabled or disabled.
In that case the following line in this page where it describes -P and -S should be updated or the behavior explained.
"This option applies only to active links, active link guides, filters, filter guides, escalations, menus, and all types of containers.
Can you please let me know how does BPCU take care of Guides and Menus when ran with -P and -S options.
Thanks,
Debasish Hazarika