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.

Remedy Action Request System 8.1 ... Upgrading Upgrading without overlays already present Stage 3 - Create overlays for existing customizations Creating overlays with the Best Practice Conversion Utility

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

  1. 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.
  2. At the command prompt, go to the <utilityInstallDir>\Best_Practice_Conversion_Utility folder.
  3. 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

Command-line options for Overlay mode

Option

Description

-x

Name of the server on which to perform the operation.

-u

User name.

-p

User password.

-a

(optional) User authentication string.

-t

(optional) TCP port of the server on which to perform the operation.

-r

(optional) RPC port of the server on which to perform the operation.

-f

Absolute path to the overlay hash file provided by BMC (include full path and file name).

-c

(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:
Best_Practice_Conversion_Utility\obj-filter-lst_template.txt
Best_Practice_Conversion_Utility\obj-filter-lst_template.xml


This option applies to all modes except when two overlay hash files are compared in ReportDiff mode.

-e

(optional) Comma-separated list of form names whose associated fields and views are the only objects processed by the operation.

-o

(optional) Name of the difference report. Do not include a file extension.

-T

(optional) Format of the difference report. Values are:

  • 0 — HTML (Default)
  • 1 — CSV
  • 2 — XLSX

-m

Utility mode. Values are o or overlay.

-k

(optional) Indicates whether to display or hide the list of objects that are skipped during conversion.

  • 0 — (Default) Hide this list in the difference report.
  • 1 — Display this list in the difference report.

-P

Comma-separated list of prefixes in the names of user-created objects.
All objects whose name begins with one of these prefixes are converted into overlays or custom objects.
This option applies only to active links, active link guides, filters, filter guides, escalations, menus, and all types of containers. (Per BMC recommendations, to modify such objects in pre-7.6.04 releases, you should make a copy of the origin object and add a prefix or suffix to its name.)
You must ensure that the corresponding out-of-the-box object exists and is the same type in the 7.6.04 release.

-S

Comma-separated list of suffixes in the names of user-created objects.
All objects whose name ends with one of these suffixes are converted into overlays or custom objects.
This option applies only to active links, active link guides, filters, filter guides, escalations, menus, and all types of containers. (Per BMC recommendations, to modify such objects in pre-7.6.04 releases, you should make a copy of the origin object and add a prefix or suffix to its name.)
Ensure that the corresponding out-of-the-box object exists and is the same type in the 7.6.04 release.

-i

(optional) Flag that specifies whether to include overlay and custom objects in the "addition" section of the difference report. Values are:

  • 0 — (Default) Exclude from addition section.
  • 1 — Include in addition section.

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:

  • Total count of objects
  • Number of new objects
  • Number of changed objects
  • Percentage customization
  • Number of new and changed objects with nonpermitted modifications

    The following types of statistical information is displayed only when you use a certain execution parameter.
  • Number of new objects that are not converted to custom objects when you execute BPCU in Overlay mode
  • Number of changed objects that are not converted to overlays when you execute BPCU in Overlay mode

Dashboard worksheet

Dashboard tab

Whether an object on the server is new

Difference Report
worksheet, rows with
the value Extension in the Customization
Type column

Extensions tab

Whether an object on the server has been modified

Difference Report
worksheet, rows with
the valueCustomization
in the Customization
Type colum

Customizations tab

Whether modified objects in the server contain permitted or nonpermitted modifications:

  • If an object contains non-permitted modifications, it is flagged as an object that cannot be converted into an overlay. All such objects must be fixed before running BPCU in Overlay mode.
  • If an object contains permitted modifications, its flagged as an object that can be converted into an overlay.

    Note: When you run BPCU in ReportDiff mode with the -k option and its value as 1, the Customizations tab displays the Skipped During Conversion column. This column displays the value true for objects that are skipped during conversion whether they were modified in a permitted or non-permitted manner. Therefore, even if the Convertible to Overlay column for a particular object displays the value false, you do not need to fix any non-permitted modifications made on it.

Difference Report worksheet, rows with the value Customization in the Customization Type column

  • Permitted modifications:
    Convertible to Overlay = true
  • Nonpermitted modifications:
    Convertible to Overlay = false

Customizations tab, all panels

  • Permitted modifications:
    Convertible to Overlay = true
  • Nonpermitted modifications:
    Convertible to Overlay = false
  • Version of the utility that was executed to generate the
    report
  • Date and time when the report was generated
  • Parameters supplied to the utility for the current execution
  • AR System applications installed in the execution environment

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

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.

Last modified by Hemant Baliwala on Apr 01, 2014
generate legacy modes overlays objects differences reports

Comments

  1. Joachim Latzko

    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.

    Jan 21, 2014 08:26
    1. Hemant Baliwala

      Hi Latzko,

      Thanks for your comment. I am working with the SME to update the topic.

      -Hemant

      Jan 22, 2014 02:39
      1. Joachim Latzko

        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.

        Jan 22, 2014 04:18
  2. Juraj Izak

    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.

    Apr 01, 2014 04:03
    1. Hemant Baliwala

      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

      Apr 01, 2014 05:22
  3. Debasish Hazarika

    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

    Dec 30, 2015 06:49
    1. Poonam Morti

      Hi Debasish,

      I will verify the option details with the SME and update the topic.

      Thanks,

      Poonam

      Dec 31, 2015 12:56
  4. Debasish Hazarika

    Hi Poonam,

     

    Did you get a chance to verify with the SME?

     

    Thanks,

    Debasish Hazarika

    Jan 27, 2016 10:49
    1. Poonam Morti

      Sorry for the delay in response. I am verifying this with the SME and will get back to you soon.

      Thanks,

      Poonam Morti 

      Jan 27, 2016 11:05
    1. 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

       

      Jan 28, 2016 01:15
  5. Debasish Hazarika

    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

     

     

     

    Jan 28, 2016 08:07
Using BPCU to generate difference reports
BPCU log information
© Copyright 1991-2020 BMC Software, Inc. © Copyright 1991-2020 BladeLogic, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2020 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.