Oracle Application Change Management Pack for Oracle E-Business Suite User's Guide Release 4.0 Part Number E18710-01

Contents

Previous

Next

Customization Manager

Introduction

Customization Manager automates the process of packaging, releasing and reporting customizations for a single Oracle E-Business Suite instance or multiple Oracle E-Business Suite instances. It provides capabilities to integrate with third-party source control repositories to access customizations that need to be packaged. It also integrates with Patch Manager for deployment of custom patches to one or more Oracle E-Business Suite instances.

Customization Manager also provides a dashboard to manage custom applications across Oracle E-Business Suite instances. It provides capabilities to not only register and validate custom applications across instances, but also a drill down to the custom objects associated with any registered custom application on a given instance. Registration and validation of the custom application ensures that custom packages associated with the custom application can be deployed on the given Oracle E-Business Suite instance.

Key Benefits

• Automates creation of customization packages that are deployable with Patch Manager or standard Oracle E-Business Suite Applications DBA (AD) Utilities

• Provides repository to manage/catalog customizations.

• Validates custom code against software coding best practices using a standards checker.

• Integrates with most source control systems.

• Supports National Language Support (NLS) patches.

• Generates reports on customization packages or manifests in these formats: rich text format (RTF) for Microsoft Word, PDF, or Microsoft Excel.

• Leverages Oracle Enterprise Manager infrastructure for distributed processing.

• Provides an interface to manage custom applications across the enterprise.

File Types

Customization Manager allows you to package custom files of a variety of file types, including the following:

• Oracle Application Object Library (FND) objects - menus, responsibility, concurrent programs, and so on

• Forms

• Reports

• Database objects - views, tables, triggers, packages, and so on

• Oracle Application Framework components

For more information on file types, see the appendix.

For more information on making customizations, see the Oracle E-Business Suite Developer's Guide and the Oracle Application Framework Developer's Guide.

Setup Steps for Customization Manager

• Ensure that the Preferred Credentials are set for each user as described in the first chapter.

• Ensure that "amp.properties" file under $OMS_HOME/sysman/config has the property called 'stageDir' defined with value of the name of the folder that is to be used as a stage with read/write permissions. For example,

  stageDir=/tmp

• Configure the stage directory for the Oracle E-Business Suite Infrastructure for the particular instance you will use for building patches that contain Java or PLD files. This step can be done via the All Targets page in Oracle Enterprise Manager (search for Oracle E-Business Suite Infrastructure) and drilling down to set the stageDir value of APPL_TOP Context.

Major Features and Definitions

Package

A package is a fundamental unit of work of Customization Manager. A package consists of all the relevant objects that constitute a customization along with all the necessary metadata relevant for the given customization. A customization package can have one or more custom patches associated which can be deployed to promote customizations.

File Manifest

The file manifest contains a list of files to be included in a package.

File Metadata Repository

The File Metadata Repository stores metadata information of custom files used to create customization packages. This information can be used to manage and catalog customizations within the system.

Technology Stack Details

The Technology Stack Details for a package is a snapshot of the technology stack properties for the Oracle E-Business Suite instance where the package was compiled.

Reporting

Customization Manager provides several methods for generating reports on packages:

• Generate a Standard report on a single package.

• Compare two packages using a Comparison report.

• The Instance Comparison report can be used to compare a given package against an instance with respect to technology stack, files with versions, missing entries for file driver file, custom products involved, and so on. It can be used to assess the likely impact before actually applying the custom patch on the given instance

Reports can be generated in RTF for Microsoft Word, PDF, and Microsoft Excel.

Releasing a Package

Once a customization package is created and tested successfully, it might need to be shared with other users. This is possible by updating the package metadata and setting the package status as "Released".

Obsoleting a Package

For scenarios where the given customization is no longer valid, the customization package may be retired by updating the package metadata and setting the package status to "Obsoleted".

Applications Standards Validation

Customization Manager has a standards checker to check the that the files included in a custom package meet certain coding standards. This checker tests all code for standards compliance and cannot be turned on or off.

Some standards are mandatory and will result in failure when Customization Manager attempts to build the package. Other standards are recommended, and the standards checker will give a warning but the package will be built.

For example, Customization Manager mandates that each file included within a customization package has an Oracle-compliant source header present within the file. If a file in a package is missing this header, the package cannot be built.

Oracle-compliant Source Header

Each file included within a customization package is recommended to have an Oracle-compliant source header present within the file.

The following is an example of an Oracle-compliant header:

$Header: sample.txt 10.1 2002/06/06 09:38 lmathur noship $  

The header contains the following elements:

• Filename

• Revision ID - This needs to be incremented every time a file is checked in

• Date and time of checkin

• Author

• Shipment state - ship/noship

Automatic Header Update and Insertion

This option can be enabled while defining or updating the "File Source Mapping" used for package creation. When the "Automatic header update" option is selected, Customization Manager takes care of querying the source control repository to derive the revision number and updates the Oracle-compliant header present within the file with the same, during the process of package creation.

It is important to ascertain that the correct "Version command" is provided to lookup/query the revision number from the given source control repository, except when using CVS or File System. This feature is not supported when the source repository is 'File System'. Also, for CVS there is no need to specify the version command as the header is always looked up from the $Header string present within the file.

Important: When using the automatic header update feature with CVS, you must have a $Header placeholder within each source file. The placeholder header must be embedded in the source file before the file is checked in into CVS.

Also ensure that you change the file name with the correct case within the $Header before embedding the header in the file.

Important: When using Subversion, it is required to use Subversion client version 1.2 or above for automatic header update.

Automatic header update is supported for all file types. For binary files like forms, reports, and so on, you must provide a dummy placeholder for the header with enough appropriate offset (space). It is recommended to leave at least 40% extra offset (space) to accommodate incrementing revision numbers. During the process of package creation, the system uses this as a placeholder and updates it with the correct header. Again, the automatic header update option should be enabled and the correct version command should be specified within the file source mapping. The header is calculated based on the release and the version in the source control. For example, if you are building a package for Release 12 and the version of the file in the subversion repository is 29, then the header version calculated would be 120.29.

Automatic header insertion is supported only for selected file types when using Subversion as the source control system. In this case, Customization Manager inserts a valid Oracle compliant header into the source file during the process of package creation, even when there is no $Header present in the file. The following file types are supported for automatic header insertion in case the file does not contain a proper $Header:

• .css

• .drvx

• .htm

• .html

• .ildt

• .java

• .jlt

• .jsp

• .ldt

• .msg

• .odf

• .pdt

• .pkb

• .pkh

• .pks

• .pl

• .plb

• .pls

• .sh

• .slt

• .sql

• .tpl

• .wft

• .wfx

Uploading Existing Custom Patches

You can upload a custom patch to Customization Manager repository:

The upload option is provided to upload existing custom patches created in the Customization Manager repository. On upload, a package with status "Succeeded" is created. The status can move to status "Released" or "Obsoleted" as other customization packages. One or more NLS patches can be uploaded for a given package. Once uploaded, the patches can be deployed using Patch Manager. Also, attachments can be added for the uploaded packages.

Note: Reporting and update capabilities are not available for the uploaded packages.

Automatic File Driver File Generation and Update

A file driver file is a master file for adpatch to identify valid Oracle E-Business Suite files for a given product (including a custom product). It is required to have an entry within the file driver file for selected file types like forms, reports, and so on. If not, then the following error is thrown during patching: "File in patch is not a known Oracle Applications file".

Customization Manager takes care of this file driver file requirement automatically. Customization Manager implicitly generates a file driver file for the relevant files in a package. During deployment with Patch Manager, these entries are automatically added to the custom product master file driver file. In case a user applies a patch manually with adpatch, he or she can run updateFileDriver.pl within the <package>/meta-inf folder before invoking adpatch.

Note that if you get the error "File in patch is not a known Oracle Applications file" while applying a custom patch built with Customization Manager, then it could be due to a missing entry in file driver file for the custom product for one or more custom files.

The file driver file for a custom product is located under:

$<custom_product_top>/admin/driver/<custom_product_short_name>file.drv  

For example, if XXCO is the custom product, then you can find the file driver file under

$XXCO_TOP/admin/driver/xxcofile.drv  

All custom files would require an entry in the respective file driver file depending on the custom product they belong, EXCEPT files which have destination path beginning with any of the following:

• admin

• sql

• mds

• lib

• patch

• help

• def

as well as any java file under destination path beginning with "java".

The usual format for an entry into the file driver file is:

<product>  <subdirectory>  <filename>  

Sample entries are as below:

xxco    admin/sql XXCONLADD.sql  

xxco    forms/<LANG> XXCOFORM.fmb

Change Approval in Customization Manager

This section provides examples of how the Change Approval Framework is used with Customization Manager.

Change Approval is supported in Customization Manager for the following:

• Releasing a package

• Obsoleting a package

• Registration of a custom application

Prerequisites

Approvals for Customization Manager must be enabled with the following setting in the amp.properties file::

enableApproval_CM=Y

There is a user who is either a Super Administrator or who has the role EBS_CM_APPROVAL_ROLE. For registration of a custom application, it is also required that the user has approver target access for the given E-Business Suite instance.

Scenario - Request to Release a Package

Here is an example of a package undergoing release with Change Approval enabled. Note that a similar process can be used in making a package obsolete.

1. A user requests for release/obsolete package from the Update Package Metadata page.

2. The package then goes into Pending Approval status. The package cannot be updated any more.

3. The Super Administrator or Approver with the EBS_CM_APPROVAL_ROLE role logs in and navigates to the Change Approval Requests Dashboard.

4. The Super Administrator or Approver updates the request “Release: <package>".

   If the request is approved, the package is released. If the request is rejected, the package goes back to its old status (Succeeded).

Scenario - Request to Register a Custom Application

Here is an example of registering a custom application.

1. A user (for example, "John") requests to register a defined custom application for a given instance.

   The request then goes into Pending Approval status. It can be tracked from the "Custom Application Requests" dashboard.

2. The Super Administrator or Approver with the EBS_CM_APPROVER role, and approver target access to the Oracle E-Business Suite instance, logs in and navigates to the Change Approval Requests Dashboard.

3. The Approver updates the request “Register:<custom application>".

   If approved, the request moves to the "Approved" status. If rejected, the request moves to the "Requested" status.

4. The original requestor, "John", logs in and navigates to "Custom Application Requests". If his request is approved, he can select the request and execute it.

   The job log can be tracked from the request details. The change request history also tracks all events.

Diagnostic Tests for Customization Manager

You can run diagnostic tests on your system in preparation for using Customization Manager. These tests can be accessed from the Diagnostics dashboard, available from the Pack Diagnostics link on the Oracle Applications page. For more information on running diagnostic tests, see: Running Pack Diagnostics Tests, Oracle Application Management Pack for Oracle E-Business Suite User's Guide.

The following tables list tests related to Customization Manager:

Customization Manager Main Page

The main page for Customization Manager lists packages that are registered in the system. For each package, the following is given:

• Name - The name of the package.

• ID - The ID of the package. This is always unique across packages.

• Release - The Oracle E-Business Suite release level for the package.

• Product - The owning product or custom application.

• Type - The type of package. Valid values include AOL, FORMS, PL/SQL, XML Publisher, OAF, and Others. This is purely for classification purposes and has no bearing on the functionality of the package.

• Status - The status of the package. Valid values include Saved, In Progress, Failed, Succeeded, Released, Pending Approval, and Obsoleted. Note that some actions are restricted based on the status of a package.

• Owner - The owner of the package. Note that some actions are restricted based on the owner of a package.

• Last Updated - The date and time the package was last updated.

• Update - Use this icon to update a package.

• Delete - Use this icon to delete a package.

You can search for a package based on its name or ID, or click the "Advanced Search" link to perform a search on other criteria.

The following functions are available for a given package (depending on its status and ownership):

• Using the procedure specified, deploy the package as a patch job in Patch Manager using the Deploy button. Packages with statuses "Succeeded" or "Released" can be deployed.

• Update the package metadata using the Update Metadata button. Packages with the statuses Succeeded or Released only can be updated for metadata changes, provided they are owned by the user currently logged in.

• Run a report on the package using the Report button. Packages with statuses Succeeded, Released or Obsoleted can be used for reports.

You can also create a new package using the Create button.

Use the Related Links at the bottom of the page to access the following features:

• File Source Mapping

• E-Business Suite Mapping

• Package Report

• File Metadata Repository

• Custom Applications

• Custom Application Requests

Registering File Source Mapping

File Source Mapping captures all the required metadata for retrieving custom files from a source control or file system repository. Creating a File Source Mapping is usually performed once as a setup step. You may create one or more File Source mappings, if required.

The main File Source Mapping page allows you to search for a File Source Mapping by name. The table lists each mapping with the following:

• Name - The name given to the mapping. Click on the link to go to the Update File Source Mapping page.

• Host Name - The name of the host from where the source control or file system is accessible.

• Source Control Type - The type of the source control system. Valid values are: SubVersion, CVS, File System, or Others.

• Owner - The user who created this File Source Mapping.

• Last Updated - The date and time the mapping was last updated.

• Enabled - Specifies if the mapping is enabled or disabled. You can enable/disable a mapping in the Update File Source Mapping page.

• Public - Whether the given mapping is public. If a mapping is public, all users can view it, but only the owner and Super Administrators can edit it.

• Delete - Use the icon provided to delete a mapping. You can delete a mapping only when no package is associated with it.

To create a File Source Mapping

Perform the following steps to create your File Source Mapping. Note that for the checkout command, you should follow the checkout command syntax provided on the page.

1. Enter the name for the file source mapping.

2. Enter the host name of the file source mapping. You can select the host from the list of values.

3. Enter the stage path. This should be a folder on the given host with read/write access which is used for temporary processing during checkout.

4. Select the source control type. Possible values are:

   • SubVersion

   • CVS

   • File System

   • Others

   The source control type is used to default the checkout command. However, the checkout command can be modified based on your source control or file system configuration. If your source control system is not among CVS, SubVersion or File System, then you may choose "Others" and enter your checkout command.

5. Enter the complete command, with required parameters, to be used to check out files. The parameters that can be used to construct the checkout command are mentioned under the "Checkout Command Syntax: section. Oracle strongly recommends that you to test the checkout command by using the “Test Checkout Command” option. It is also important to ascertain that the user provided within the “host” credentials has the correct permissions on the given host selected for checkout.

6. Optionally enter the environment script to be run before files are checked out, to set any environment parameters ore preprocessing, if required.

7. Enter a description for your reference.

8. Mark the file source mapping as Public if desired.

   If a file source mapping is marked as Public, any user can view it and use it to create a package. However, only the owner and Super Administrators can edit the file source mapping.

   This feature is typically useful when you would want the system administrator to create one mapping and enable all developers to use them, without having them know the details of the source control system.

   Note that a Super Administrator can see all transactions. A Super Administrator can access all file source mappings, Oracle E-Business Suite mappings, reports, and packages. A Super Administrator can also modify and delete them.

9. The “Test Command” feature allows you to test the checkout command and the version command provided on the remote checkout host. It is strongly recommended that you test the checkout command and version command to help prevent any failures during checkout while creating a package. Enter Test Checkout Command information

   

   Enter the following:

   • Product

   • Source Path

   • File Name

   • Version

   • Language

   • User Name - If your source control system requires it and a %user_name% token is included within the checkout command.

   • Password - If your source control system requires it and a %password% token is included within the checkout command.

   Use the Preview or Test button to preview or test the checkout command and version command. The results will be shown in the Command Preview or Test Results field.

To update a File Source Mapping

You can update a File Source Mapping by clicking on its name listed in the main File Source Mapping page. You can only update the fields described below. It is not possible to update the host for a given file source mapping.

Note that you can check or uncheck the Enabled box to enable or disable a file source mapping.

1. Enter the source control type. Possible values are:

   • SubVersion

   • CVS

   • File System

   • Others

2. Enter the complete command, with required parameters, to be used to check out files.

3. Enter the stage path. The stage path is the location of the directory, with write permissions, to where the files would be checked out.

4. Optionally enter the environment script to be run before files are checked out, to set environment parameters.

5. Enter a description.

6. Mark the file source mapping as Public if desired. If it is marked as Public, all users can view the mapping. However, only the owner and Super Administrators can edit it.

7. The separate preview and test section is provided so that you can preview the checkout command and test it on the remote checkout host. It is strongly recommended that you test the checkout command before actually using it to create a package.

   Enter the following:

   • Product

   • Source Path

   • File Name

   • Version

   • Language

   • User Name

   • Password

   Use the Preview or Test button to preview or test the checkout command. The results will be shown in the Command Preview or Test Results field.

Example of a File Source Mapping with Parameters

The following table provides information on the file source mapping parameters and sample values for each parameter.

Here is the syntax of a checkout command with the parameters:

svn cat file:///usr/local/svn/%product_code%/%file_path%/%lang_code%/%file_name% --username %user_name% --password %password% > %file_name%

Here is the above checkout command with values substituted for the parameters:

svn cat file:///usr/local/svn/xxco/patch/115/import/US/Custom_Responsibilities.ldt --username developer1 --password <password> > Custom_Responsibilities.ldt

E-Business Suite Mapping

Creating an E-Business Suite Mapping is an optional setup step. This mapping is used if Java or PLD file compilation is required. It is also used for report generation. The E-Business Suite Mapping indicates the Oracle E-Business Suite instance which would be used to compile Java or PLD files or used for report generation. Please note that all operations on this instance are read-only and using an instance for E-Business Suite mapping cannot cause any kind of change on the given instance via Customization Manager.

The main E-Business Suite Mapping page allows you to search for an E-Business Suite Mapping by name. The table lists each mapping with the following:

• Name - The name given to the mapping. Click on the link to go to the Update E-Business Suite Mapping page.

• Instance Name - The name of the Oracle E-Business Suite instance.

• Release - Release level of the Oracle E-Business Suite instance.

• Owner - The user who created this mapping.

• Last Updated - The date the mapping was last updated.

• Enabled - Specifies if the mapping is enabled or disabled. You can enable/disable a mapping in the Update E-Business Suite Mapping page.

• Public - Whether this E-Business Suite Mapping is available for all users. If a mapping is marked as Public, all users can view it, but only the owner and Super Administrators can edit it.

• Delete - Use the icon provided to delete a mapping. You can delete a mapping only when there are no packages associated with it.

Select the Create button to create a new mapping.

To create an E-Business Suite Mapping

Use the following steps to create an E-Business Suite Mapping.

1. Enter a name for the mapping.

2. Enter the name of the reference Oracle E-Business Suite instance. Options for this instance are automatically discovered by Oracle Application Management Pack for Oracle E-Business Suite.

3. Mark the mapping as Public, if desired.

   If an E-Business Suite Mapping is marked as Public, any user can view it and use it to create a package, but only the owner and Super Administrators can edit it.

   This feature is typically useful when you would want the system administrator to create one mapping and enable all developers to use them, without having them know the details of the source control or Oracle E-Business Suite system.

   Note that a Super Administrator can see all transactions, including E-Business Suite mappings. A Super Administrator can access all file source mappings, E-Business Suite mappings, reports, and packages. A Super Administrator can also modify and delete them.

4. Enter the stage path. The stage path is the location of the directory with write permissions used for temporary processing during compilation and build process.

5. Enter the prepend classpath. This field is valid only with Java files; this classpath is prepended to these files when a package is built. This can be used to specify any third party libraries if you custom java files have dependencies on them.

6. Enter a description for the mapping.

To update an E-Business Suite Mapping

To update an E-Business Suite Mapping, click on its name in the main E-Business Suite Mapping page. Note that you cannot update the E-Business Suite Mapping name or the instance mapping here.

1. Check the Enabled box if you want the E-Business Suite Mapping to be active.

2. Check or uncheck the "Public" box depending on whether the mapping should be viewable by all users.

3. Enter the stage path. The stage path is the location of the directory with write permissions to where files would be compiled.

4. Enter the prepend classpath. This field is valid only with Java files; this classpath is prepended to the environment classpath during package compilation.

5. Enter a description for the mapping.

Creating a Package

Use the following procedures to create packages:

To create a package

1. Enter general information for the package. The Package ID is an auto-generated unique number.

   

   • Package Name - Enter a user-friendly name for the package.

   • Product - Enter the owning product application. This product can be a custom product created in Oracle E-Business Suite (not in Customization Manager).

   • Package Type - Enter the package type. This value is for your own classification and convenience for searching and cataloging. No validation is performed on this field.

   • Description - Enter a description for your reference. This description becomes part of the package readme.

   • File Source Mapping - Enter the File Source Mapping for this package. Select from the list of previously-defined mappings.

   • User Name - Enter the user name to connect to the source control system, if required. The User Name will be substituted in the "%user_name%" parameter of the checkout command.

   • Password - Enter the password for the above user name, if required. The password entered here would be substituted for the %password% token within your checkout command.

   • Upload Manifest - If you have a file manifest in a comma-separated value (CSV) format on your computer, you can upload it here.

     The following is an example of a file manifest:

     #Product,SourcePath,FileName,Version,Type,DestPath,LangCode
     xxco,java\r12\reporter\cpserver,XXCOCustomCp.java,115.1,java,java/r12/reporter/cpserver,Generic
     xxco,patch\115\import,XXCOConcprog.ldt,115.9,software ldt,patch/115/import,US
     xxco,patch\115\import,XXCOMenu.ldt,,software ldt,patch/115/import,US
     xxco,patch\115\import,XXCOReqGroup.ldt,115.3,software ldt,patch/115/import,US
     xxco,patch\115\import,XXCOResp.ldt,115.7,software ldt,patch/115/import,US
     xxco,patch\115\import,XXCOUser.ldt,115.6,software ldt,patch/115/import,US
     xxco,forms,XXCOFRM.fmb,,fmb,forms,US

2. Enter the file listing.

   

   You may add or remove file entries manually from the File Listing page. Alternatively, you may also include file entries from the File Metadata Repository using the Include Files button.

   For each file, enter the following:

   • Product - The owning product application. This product can be a custom product created in Oracle E-Business Suite (not in Customization Manager). This would be substituted in the "%product_code%" parameter in the checkout command.

   • Source Path - The source directory for the file on the source control system or file system. This would be substituted in the "%file_path%" parameter in the checkout command.

   • File Name - The name of the file. This would be substituted in the "%file_name%" parameter in the checkout command.

   • Version - Optional. The version of the file. The version is only needed if the checkout command will use the version information. This would be substituted to the “%version%” parameter in the checkout command.

   • Type - The type of the file. Ensure that correct type is selected for the file entry. The Oracle Applications DBA (AD) patch driver instructions are based on the type selected. For details, please refer to the appendix describing the file types.

   • Destination Path - The destination path for the file in the Oracle E-Business Suite instance excluding the language subdirectory relative to the product top.

     For common file types, a default destination path is provided automatically but this default value can be overridden.

     The destination path must be an AD-compliant destination path according to Oracle E-Business Suite standards.

     The destination path in the patch driver is automatically suffixed with the language code chosen with exception to "Generic".

     Note: For "Generic" files, ensure that the destination path is entered correctly: For example,

     Product: XXCO
     Source Path: forms/US
     File Name: IDC.fmb
     Destination Path: forms
     Language: US

     The final destination path is "forms/US" but the values are entered separately.

   • Language - Optional. The language code for the file. Select the language code as needed to generate the respective NLS patch.

   Important: Customization Manager strongly recommends that each file included within a customization package has an Oracle-compliant source header present within the file.

   The following is a sample Oracle compliant header:

   $Header: sample.txt 10.1 2002/06/06 09:38 lmathur noship $  

   The header contains the following elements:

   • Filename

   • Revision ID - This needs to be incremented every time a file is checked in

   • Date and time of checkin

   • Author

   • Shipment state - ship/noship

3. Enter the E-Business Suite information (Conditionally required). The E-Business Suite mapping information is only required when the package contains at least one Java or PLD file. You can select the Oracle E-Business Suite Mapping from the list provided.

4. Enter the Package Metadata. You can enter the instructions for package application here. These instructions will become part of the package readme.

5. Enter Comments. These comments will be recorded as part of the package history for tracking changes made to the package.

6. Enter Prerequisite Information.

   For Release 11i packages, you can enter one or more prerequisite patch numbers that can be used for deployment validation with AD utilities.

   For Release 12 (and higher) packages, enter in the prerequisite patch numbers that will be used in validation when the package is deployed through Patch Manager. Note that this validation is done only if you use the Check Prerequisites button in the Patch Details page when creating a patch run in Patch Manager.

   Note: Prerequisite information entered here for Release 12 packages is only used in deployment by Patch Manager.

7. Enter Mailing List information.

   You can enter e-mail addresses for people who should be sent notifications about the package's creation status on the event of success or failure. It is recommended to have e-mail notifications set so that the appropriate users can be notified about the package success or failure.

To create a package using the "Create Like" option

Customization Manager allows you to create a package by copying the details from an existing package. This procedure can be used typically to create a mirror copy of the package or create another package with minor modifications without having to enter all the relevant details about the package.

To create a package using the "Upload" option:

If you have any legacy custom patches, the same can be uploaded to the Customization Manager repository in context to a new customization package. Click on the “Upload” button from the package search page to upload an existing custom patch. While uploading a custom patch, the following information is required:

• Package Name

• The release to which the custom patch belongs to.

• The custom product/application associated with the custom patch

• Package type: only for classification purposes

• Description for your reference

• Any specific instructions for applying the custom patch

You can upload one or more custom patches (NLS patches) to this customization package. However, it is important that all of them must be associated with the same unique patch number. Clicking the Submit button creates a customization package with the status "Succeeded". This customization package can now be deployed just like any other customization package and can be "Released" or "Obsoleted", when required.

Updating a Package

To update a package, find the package listing in the main Customization Manager page and select the icon in the Update column.

To update a package's definition

1. Enter general information for the package. The Package ID is an auto-generated unique number and cannot be updated. The Package Name cannot be updated as well.

   • Product - Enter the owning product application. This product can be a custom product created in Oracle E-Business Suite (not in Customization Manager).

   • Package Type - Enter the package type. This value is for your own classification and convenience for searching and cataloging. No validation is performed on this field.

   • Description - For your reference.

   • File Source Mapping - Enter the File Source Mapping for this package. Select from the list of previously-defined mappings.

   • User Name - Enter the user name to connect to the source control system, if required. The User Name and Password (below) will be substituted in the "%user_name%" and "%password%" parameters of the checkout command.

   • Password - Enter the password for the above user name, if required.

   • Upload Manifest - If you have a file manifest as a comma-separated value (CSV) format on your computer, you can upload it here.

2. You may add or remove file entries manually from the File Listing page. Alternatively, you may also include file entries from the File Metadata Repository using the Include Files button.

   For each file, enter the following:

   • Product - The owning product application. This product can be a custom product created in Oracle E-Business Suite (not in Customization Manager).

   • Source Path - The source directory for the file on the source control system or file system. This would be substituted in the "%file_path%" parameter in the checkout command.

   • File Name - The name of the file. This would be substituted in the "%file_name%" parameter in the checkout command.

   • Version - Optional. The version of the file. The version is only needed if the checkout command will use the version information. This would be substituted in the "%version%" parameter in the checkout command.

   • Type - The type of the file. Ensure that correct type is selected for the file entry. type. The Oracle Applications DBA (AD) patch driver instructions are based on the type selected.

   • Destination Path - The destination path for the file in the Oracle E-Business Suite instance excluding the language subdirectory. This must be an AD-compliant destination path according to Oracle E-Business Suite standards. The destination path in the patch driver is automatically suffixed with the language code chosen with exception to "Generic". The destination path for a file entry is defaulted to the source path, which may be modified if necessary.

   • Language - Optional. The language code for the file. Select the language code as needed to generate the respective NLS patch.

3. Enter the E-Business Suite mapping information (Conditionally required). The E-Business Suite mapping information is only required when the package contains at least one Java or PLD file. You may select the E-Business Suite Mapping from the list provided.

4. Enter the Package Metadata. You can enter the instructions for package application here. These instructions will become part of the package readme.

5. Enter Comments. These comments will be recorded as part of the package history for tracking changes made to the package. As a best practice, it is recommended to add comments describing the changes done to the package and other details. Any comments added are tracked with the package history information.

6. Enter Prerequisite Information.

   For Release 11i packages, you can enter one or more prerequisite patch numbers that can be used for deployment validation with AD utilities.

   For Release 12 (and higher) packages, enter in the prerequisite patch numbers that will be used in validation when the package is deployed through Patch Manager. Note that this validation is done only if you use the Check Prerequisites button in the Patch Details page when creating a patch run in Patch Manager.

   Note: Prerequisite information entered here for Release 12 packages is only used in deployment by Patch Manager.

7. Enter in Mailing List information. You can enter e-mail addresses for people who should be sent notifications about the package's update status on the event of success or failure.

Saving a Package

If, in the process of creating or updating a package definition, you want to save the package definition before submitting a request to have Enterprise Manager actually build the package, click the Save button on the final Submit page of the Create/Update process. Your package definition will be saved and it will appear on the main Customization Manager page with a status of Saved.

Searching for a Package

You can perform an Advanced Search for packages with the following criteria:

• Name

• ID

• Product

• Instruction Contains

• Prerequisite Patch

• Description Contains

• Owner

• Release

• Package Type

• Standards Check Results

• Status

• Language

• Public (Choose whether you want results with only Public packages, no Public packages, or either)

• Contains File

• Contains File with Version (Used in conjunction with "Contains File")

• Updated within (Days)

• File Source Mapping

• E-Business Suite Mapping

• Last Updated By

Viewing Package Details

You can view package details by clicking on its name in the search results table on the main Customization Manager page.

Package Details

The following details are shown in this region:

• Package ID

• Package Name

• Release

• Standard Checker Results - For detailed results, click on the link.

• Created - The date and time the package was created.

• Last Updated - The date and time the package was last updated.

• Status - The status of the package. Possible values are: In Progress, Succeeded, Saved, Failed, Released, and Obsoleted.

• Product

• Package Type

• E-Business Suite Mapping Name – If applicable.

• File Source Mapping Name

• Owner

• Uploaded: Whether this package was created as a result of a patch upload.

• Public: Whether this package is shared across all users.

History Details (View Package History)

The package history provides a chronological view of all the important events in the lifecycle of a package.

Click the History Details button to go to the View Package History page, which provides high-level history tracking of the package, including the timestamp and user-entered comments for the following events:

• Creation of package

• Update of package

• Release of package

You can also drill down to the Oracle Enterprise job details for the package creation and any updates.

View Log

Use the View Log button to view the most recent Oracle Enterprise Manager job details for the package.

Description

Any description entered for the package is shown here.

Instructions

Instructions entered in the Package Metadata field are shown here.

Patch Downloads

For each patch generated, the following information is shown here:

• File Name - Click on the patch file name link to download the patch.

• Language - The language of the patch.

• Size - The size of the patch.

• Readme - Click on the icon to download the readme. The readme file is in HTML format and includes the package description and package metadata.

Typically, each customization package could be associated with one or more language patches.

Manifest

The file manifest is shown here. Details for each file include Product, Source Path, File Name, Language, Destination Path, Version, and Last Updated timestamp.

Use the Download Manifest button to download the manifest as a comma-separated values (CSV) file, viewable in Microsoft Excel.

You can search for a specific file by entering in the file name in the "Locate File" field and clicking Go. Wildcard characters “%” and “*” are supported here.

Technology Stack Details

Technology Stack details for a package is a snapshot of the technology stack properties for the Oracle E-Business Suite instance where the package was compiled. Patch Manager, when deploying the patch, checks the compatibility of the details specified here with the environment to which the package is being deployed. You can first check Technology Stack compatibility yourself by running "Instance Comparison" reports.

Attachments

You may add or remove any associated documentation like project plan, design documents, and so on. For each attachment, the following is listed:

• File Name

• Description

• Last Updated timestamp

You can remove an attachment from the package using the Delete icon. If the package is Released or Obsoleted, then the attachments cannot be deleted.

Mailing List

View the e-mail addresses for people who should be sent notifications about the package, on the event of success or failure.

Package History

View the history of the package by clicking the History Details button. The package history captures a trail of all major actions upon the package with the comments captured.

Updating Package Metadata

Package metadata can be updated to change the status of the package or to push the file entries metadata in the package to the File Metadata Repository. The "Update Package Metadata" page enables you to do the following:

• Change the status of the package. You can release or obsolete a package by changing its status to "Released" or "Obsoleted". Once a package is updated to the "Released" status, it can no longer be updated and becomes accessible to other users. Once a package is updated to the "Obsoleted" status, it can no longer be updated or deployed.

  Note: With the Change Approval Framework, once an approver approves a request to release/obsolete a customization package from a user, the package is released/obsoleted. The user does not need to release/obsolete the package explicitly after the approval.

  Tip: Add comments for future reference when you release or obsolete a package. For example, state the reason why you are obsoleting a package.

• Add file metadata entries to the File Metadata Repository.

• If you are the owner of the package or super administrator, you can mark the package as “Public” which entitles the package to be shared across all users for view/update.

• Add comments which are recorded in the package history for the above changes.

Standards Checker Results

The results of the standards checker can be accessed by clicking on the standards checker status.

The standard checker results can also be downloaded as a CSV format file by clicking the Download Results button.

To view details about the standard checker validations for a given file, click on the overall status against each file. The details about the standard checker validations include the standard name, result and the message.

In case the standard checker completes with "Error", the package processing is aborted and there are no patches generated.

Package Reports

Customization Manager offers powerful reporting capabilities to help you document, compare and track your customizations. You can generate three types of reports on packages:

• A Standard report gives you details on a single package, including technology stack requirements and the file manifest. You might use this to document customizations.

• A Comparison report allows you to compare two packages. For example, you might want to compare their technology stack snapshots or the versions of the files included in the packages.

• An Instance Comparison report allows you to compare the details of the package with that of an actual Oracle E-Business Suite instance. The details which are compared include custom application, file driver file entries, file manifest and versions, and the technology stack snapshot of a package to the technology stack properties of a given instance. By doing this comparison you can determine possible compatibility issues of the package with the instance and assess the possible impact/possible issues before actually applying the patch.

The technology stack compatibility information and the report is also available from the Patch Manager interview process by clicking the "Technology Stack Report" icon on the Patch Details page.

Important: Oracle strongly recommends that you generate an Instance Comparison report for each custom package and the instance where it is intended to be deployed to identify any technology stack incompatibilities before actually applying the patch.

Reports can be accessed from the Reports link on the Change Management dashboard, or from the Reports link under Related Links on the Package Search page.

Creating a Report

To create a report, you can

• Select a package from the Package Search results page and click Report

• Click Report button on the View Package page, or

• Click the Create button on the Package Report page.

To create a Standard Report

A Standard report gives you details on a single package, including technology stack requirements and the file manifest.

1. Enter in a user-friendly name for your report.

2. Choose Standard for the Report Type.

3. Enter the package you want the report to be based on in the Package field. This package must have the status of Succeeded, Released, or Obsoleted.

4. Enter the Report Format. Options are:

   • PDF (Portable Document Format)

   • RTF (Rich Text Format)

   • XLS (Microsoft Excel format)

5. Enter the Oracle E-Business Suite Mapping to be used for the report generation.

6. Click Submit.

To create a Comparison Report

A Comparison report allows you to compare two packages. For example, you might want to compare technology stack requirements or versions of the files included in the packages.

1. Enter in a user-friendly name for your report.

2. Choose Comparison for the Report Type.

3. Enter the package name in the Primary Package field. This package must have the status of Succeeded, Released, or Obsoleted.

4. Enter the package name in the Secondary Package field. This package must have the status of Succeeded, Released, or Obsoleted.

5. Enter the Report Format. Options are:

   • PDF (Portable Document Format)

   • RTF (Rich Text Format)

   • XLS (Microsoft Excel format)

6. Enter the Oracle E-Business Suite Mapping to be used for the report generation. Please note that this instance would be only used to publish the report using BI Publisher.

7. Click Submit.

To create an Instance Comparison Report

An Instance Comparison report allows you to compare the technology stack properties of a package to the technology stack properties of a given instance. By doing this comparison, you can tell if the package can be properly deployed on the instance.

In addition, the report lists any missing entries in the file driver file, and compares files and versions within the package to those of the instance.

1. Enter in a user-friendly name for your report.

2. Choose Instance Comparison for the Report Type.

3. Enter the package you want the report to be based on in the Package field. This package must have the status of Succeeded, Released, or Obsoleted.

4. Enter the Report Format. Options are:

   • PDF (Portable Document Format)

   • RTF (Rich Text Format)

   • XLS (Microsoft Excel format)

5. Enter the Oracle E-Business Suite Mapping to be used for the report comparison. The Oracle E-Business Suite instance referred by this mapping would be the one which would be compared against the package. As a best practice, it is recommended to generate an instance comparison report for every instance where you intend to deploy the package, to identify any possible incompatibilities/issues before actually applying the package.

6. Click Submit.

Viewing a Report

In the Package Report search results table, the following is shown for each report:

• Name - The name of the report.

• Type - The type of the report; either Standard, Comparison, or Instance Comparison.

• Primary Package - The primary package on which the report is based.

• Secondary Package (if any) - For Comparison reports, the second package used in the comparison.

• E-Business Suite Mapping - The E-Business Suite Mapping used in the report generation or comparison.

• Format - The format of the report; either PDF, RTF, or XLS.

• Status - The status of the report.

• Last Updated - The Last Updated timestamp for the report.

• Download - Click on the link provided to download a ZIP file containing the report.

• Details - Click on the Details icon to view details on the report submission job. This link takes you to the Oracle Enterprise Manager Deployments Status page for the report submission.

• Delete - Click on the Delete icon for the report to delete the report.

Standard Report Output File

The Standard Report output file has three sections:

• Package Details - Information pertaining to the package's definition.

• Technology Stack Information - Properties and values of the technology stack of the instance mapped through the Oracle E-Business Suite Mapping for the package.

• File Manifest - The listing of the files in the package, including their respective product, source path, name, version, language, and type.

Comparison Report Output File

The Comparison Report output file has three sections:

• Package Details - Information pertaining to the packages' definitions.

• Technology Stack Information - This section shows a comparison of the values of the two packages' technology stack details.

• File Manifest - This section shows a comparison of the versions of each given file in the two packages.

Instance Comparison Report Output File

The Instance Comparison Report output file has three sections:

• Package Details - Information pertaining to the package's definition.

• Oracle E-Business Suite Instance Information - Basic information for the instance used in the report comparison. Information includes name, patch level for Applications DBA (AD), patch level for Oracle Application Object Library (FND), and the database release information.

• Missing custom products/applications.

• Missing entries in file driver file.

• File comparison to report missing files or version differences.

• Technology Stack Details - For each given property, this table lists the value for the package and the Oracle E-Business Suite instance, and how they compare to each other.

Searching for a Report

You can search for a report by its name on the main Package Report page, or click the Advanced Search link to search based on additional criteria, including:

E-Business Suite Mapping - The E-Business Suite mapping used for the report generation or comparison.

• Primary Package - The primary package for the report.

• Secondary Package - The secondary package, if any. The secondary package would be used in Comparison Reports.

• Type - The type of report; either Standard, Comparison, or Instance Comparison.

• Report Format - The format chosen for the report; either PDF, RTF, or XLS.

Releasing and Sharing a Package

After a package is released, it is implicitly shared with other users to deploy. Use the Update Package Metadata page to release a package. See: Updating Package Metadata.

Note: With the Change Approval Framework, once an approver approves a request to release a customization package from a user, the package is released. The user does not need to release the package explicitly after the approval.

Before you deploy a custom package in Patch Manager, you should run the Instance Comparison Report to compare the technology stack properties of the package with those of the instance to which the package is being deployed. Patch Manager does not stop the deployment of a patch if the technology stack properties are not compatible, so you should make your best judgement based on the Instance Comparison Reports.

Maintaining the File Metadata Repository

The File Metadata Repository stores metadata information on each file. It can be used as a cataloging repository for all custom files within your enterprise.

The File Metadata Repository is also aware of the objects within the custom files. This capability typically applies to SQL scripts and PL/SQL packages where the objects are tables, indexes, sequences, views, and so on.

The system can parse and discover objects within custom files when added to the File Metadata Repository. This can be initiated from the “Update Package metadata” screen on clicking the box "Add file metadata to file repository".

Examples of custom objects include:

• Tables

• Views

• Mviews and Mview logs

• Triggers

• PL/.SQL package names

• Indexes

You can view and updates objects populated for a give file. You can also search for files containing specified objects and include them during package creation or update.

Search capabilities are limited to:

• PL/SQL spec and body (all formats)

• SQL files

• Oracle Application Framework XML files

• XDF

The information on a file can be uploaded to the repository in one of three ways:

• By uploading a package's file manifest in CSV format to the repository.

• By adding metadata for an individual file manually to the repository.

• By updating the metadata for a file already in the repository.

You can add metadata to the repository using the "Add file metadata to file repository" option in the Update Metadata page.

The File Metadata Repository can be accessed from its link on the Change Management Dashboard under Customization Manager.

You can search for a file by entering the filename in the Search field on the main File Metadata Repository page. Alternatively, use Advanced Search to search for its file using one or more of the following: Filename, Product, Language, Source Path, Destination Path, or Object.

Also, during the package create/update flow, you can search for files or files referring to objects within the file metadata repository using the Include Files button.

To upload a file manifest

1. Select the Upload Manifest button from the main File Manifest Repository page.

2. Select your file manifest file using the Browse button for the File Manifest field.

3. Optionally add a description.

4. Click Submit.

To upload an individual file

1. Optionally add a description.

2. Enter the name of the file.

3. Enter the product to which the file belongs.

4. Enter its source path.

5. Enter the destination path.

6. Enter the language for the file.

7. Optionally enter a description.

8. Click Submit.

To update the metadata for a file already in the File Metadata Repository

1. Select the Update icon for the file in the Search results table in the main File Metadata Repository page.

2. Update the file name, product, source path, destination path, language, and/or description as desired.

3. Click Submit.

   It is possible to associate one or more customization objects to a given file. For instance, a PLS file might be associated with a PL/SQL procedure name as one of the objects. You might update a given file entry to associate one or more customization objects to it. This capability allows you to catalog and later search for customization objects using the Advanced Search option within the File Metadata Repository. However, there are currently no validation checks built into the system that use this information during package creation or deployment.

Managing Custom Applications

You can manage your custom applications via the dashboard. The common dashboard allows you to:

• View custom applications and instance associations

• Register a new custom application

• Validate an already registered custom application

Navigation: The Custom Applications page is accessible from the Change Management Dashboard > Customization Manager region > Custom Applications link.

Note that a custom application "definition" is de-coupled from registration. Once an application is defined, it can be registered on one or more instances.

To define a new custom application

1. Navigate to the Custom Applications page. Select "New Custom Application", and click Go. The Define Custom Applications page appears.

   

2. Specify an Application Short Name for your application. Note that only alphanumeric characters are allowed, and letters must be lowercase. The application short name is recommended to be prefixed with "xx".

3. Specify an Application Name for your application.

4. Optionally provide a description.

5. Click Submit to save your work.

Note that a custom application definition is not associated with any specific Oracle E-Business Suite instance but can be used to register the given custom application on one or more Oracle E-Business Suite instances.

To discover an existing custom application

1. Navigate to the Custom Applications page. Select "Existing Custom Application", and click Go. The Discover Custom Applications page appears.

   

2. Select the custom application you wish to discover and add. You can use the Search feature to narrow down the results the table.

To validate a custom application

Existing registered applications can be validated.

1. Navigate to the Custom Applications page. Click the "Custom Application Requests" link at the bottom of the page. The Custom Application Requests page appears. Click the Validate button. Alternatively, you can also select the instance and click the Validate button from the custom application view details screen.

2. Enter in the Application Short Name for the application. You can use the LOV provided. Note that the Application Name defaults in.

3. Enter in the Oracle E-Business Suite instance. You can use the LOV provided. Note that the Preferred Credentials need to be set for this Oracle E-Business Suite instance.

4. Click Submit. A job to validate the custom application will be submitted. Validation is based on certain standards and is provided by Oracle Applications DBA (AD) utilities.

To register a custom application on an Oracle E-Business Suite instance

1. Navigate to the Custom Applications page. Click the "Custom Application Requests" link at the bottom of the page. The Custom Application Requests page appears. Click the Register button. Alternatively, you can also click the Register button on the Custom Application details page.

2. Enter in the Application Short Name for the application. You can use the LOV provided. Note that the Application Name defaults in.

3. Enter in the Oracle E-Business Suite instance. You can use the LOV provided. Note that the required APPLSYS schema, APPS schema and system schema Preferred Credentials need to be set for this Oracle E-Business Suite instance.

4. Enter in an Application ID. Oracle recommends you use an application ID greater than 50000. Customization Manager automatically generates and defaults the recommended application ID.

5. Select "Run AutoConfig" if desired. AutoConfig execution is necessary for the custom application to be available for patching. Please run AutoConfig manually if you do not chose to run it during the custom application registration.

6. When change approval is enabled, enter e-mail addresses for Notification E-mail(s). In registering a custom application, you first submit a request to register the application. This request must then be approved (either automatically or manually, depending on your Change Approval Framework setup).

7. Enter a justification.

8. Click Submit. A request to register the custom application will be submitted.

To view details of custom application

You can view details of a custom application. Details include:

• List of instances where custom application is present with statusvalidated/not validated. If the status is not validated, it is recommended to use the Validate button to launch a validation request. A valid status ensures that custom patches for the given custom application can be applied on that instance.

• Custom objects associated with the given custom application which are present on the given instance can be viewed by clicking on the "View Objects" icon. Customization Manager automatically discovers and relates the following objects associated with a custom application:

  • Custom forms

  • Profile options

  • Request sets

  • Database objects

  • Alerts

  • Audit group information

• All files in the File Metadata Repository for the given custom application.

• List of packages that have been created for the custom application.

To track details of a custom application request

A custom application request can be used to register or to validate a custom application on a given instance.

1. Navigate to the Custom Applications page. Click the "Custom Application Requests" link at the bottom of the page. The Custom Application Requests page appears. Select a custom application request from the table and click View.

2. Details for the request will be shown.

   

   Tip: To debug or view logs of a custom application request, click on “Job Details” icon against the specific custom application request. This would navigate to the EM job log associated with the custom application request. Click and view details on the “DO_JOB” step to view the detailed log of the given custom application request. In case of a failure of a custom application request, a new request should be submitted after rectifying the errors/failures listed in the job details log.

To execute a job to register or validate a custom application when the change approval system is enabled

1. Confirm that the request to execute the job to register or validate the custom application has been approved. To do this, navigate to the Custom Applications page. Click the "Custom Application Requests" link at the bottom of the page. The Custom Application Requests page appears. Approved requests will be listed with the Status "Approved".

2. Select an Approved custom application request from the table and click Execute.

3. The system will attempt to execute a job to register or validate the custom application. If the system cannot execute the job, details regarding the job will be shown.

Known Limitations

Known limitations with Customization Manager include:

• Because Enterprise Manager 11g Grid Control Release 1 uses an https OMS port by default, all links used in Customization Manager use https mode. Due to a known limitation with Internet Explorer and https-enabled websites, Customization Manager cannot download files, including patches, readmes, file manifests, and package reports in Internet Explorer. Another browser such as Mozilla Firefox should be used instead.

Copyright © 2010, 2011, Oracle and/or its affiliates. All rights reserved.