Deploying Personalizations

This chapter covers the following topics:

Overview

Both admin-level and user-level personalizations may be extracted from one database and loaded into another. This allows you the freedom to create and test personalizations in a test database before deploying the personalizations to a production instance. Use the Import/Export UI in the Functional Administrator responsibility to deploy your personalizations.

Note: While the Import/Export UI and command line tools are not applicable to Online Patching introduced in Release 12.2, they will continue to work in the presence of Online Patching. Refer to Section 6.3 in Developing and Deploying Customizations in Oracle E-Business Suite Release 12.2, My Oracle Support Knowledge Document 1577661.1, for additional steps on how to deploy your custom personalizations via a patch in conjunction with the Online Patching feature.

Deploying Personalizations Using the Functional Administrator Responsibility

For personalized pages that have been created in or migrated to Oracle JDeveloper OA Extension, the meta data can either be in the form of XML files on the file system or stored in the MDS (Meta Data Services) repository. By exporting meta data into XML files on the file system, you can easily move those files to another system or simply login to a different environment and import those XML files to a new database instance. The Functional Administrator responsibility provides a simple UI that lets you both export meta data to XML files, and import XML files into a MDS repository.

  1. Set the profile option FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH) to a root directory in your file system where your files are to be exported to or imported from.

    For more information about the FND: Personalization Document Root Path profile option, refer to the Personalization section in the OA Framework Profile Options appendix of the Oracle Application Framework Developer's Guide.

  2. Log in to the Oracle E-Business Suite under the Functional Administrator responsibility.

  3. Select the Personalizations tab, then select the Import/Export sub tab.

  4. The Personalization Repository page renders an HGrid that represents the personalized contents of the MDS repository. You may expand nodes in the HGrid to search for and select specific personalized regions or pages to export to an XML file. Note that base documents are not shown in this repository. You may also select nodes (packages) from this HGrid to export to an XML file. Note that if you select a node to export, then all packages and documents contained within that selected node are exported.

    The focus of the HGrid is initially set to the /oracle/apps/ node. The root path when the HGrid first renders, is always /oracle.

    You may expand the HGrid at the initial focus, but note that there are a large number of applications to browse through at this level. Instead, you may want to plan ahead and use the Search region above the HGrid to identify specific applications or personalized pages, regions or packages. The Search region allows you to search by Application Name or Document Path and well as by a range of Last Updated dates. The search results are shown in the HGrid.

    Personalization Repository page of the Functional Administrator responsibility

    the picture is described in the document text

  5. Select the pages, regions or packages you wish to export, then select Export to File System to export the selection to the directory specified by the profile option FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH). You may also select Delete to delete your selection from the repository.

  6. Once you export your meta data to XML files on the file system, you should login to the other Oracle E-Business Suite environment that you want to import these files to, and set the profile option FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH) to the file system location of the exported XML files.

  7. To import the XML files from your file system into another MDS repository, login to the other Oracle E-Business Suite environment as a Functional Administrator. Select the Personalizations tab, then select the Import/Export sub tab. Select Exported Personalizations from the side navigation menu to display the Exported Personalizations page.

    Exported Personalizations page of the Functional Administrator responsibility

    the picture is described in the document text

  8. The HGrid in the Exported Personalizations page displays all the documents present in the directory specified by the profile option FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH). Select all the documents you wish to import and choose Import from File System.

    You may expand nodes in the HGrid to search for and select specific personalized regions or pages to import from the file system. You may also select nodes (packages) from this HGrid to import all packages and documents contained within that selected node.

Deploying Personalizations Using the Import/Export Command Line Tools

Although using the Import/Export UI under the Functional Administrator responsibility to export and import your personalizations is preferred, you may also use the Import/Export command line tools to deploy your personalizations. For personalized pages that have been created in or migrated to Oracle JDeveloper OA Extension, you can use the Export tool to export a personalized region from a repository to an XML file and use the Import tool to import an XML file into a repository.

The Import/Export tools requires JDK version 1.1.8, but can also run with JDK version 1.3. Before running the tools, your classpath, path and environment should be set up similar to the environment required for applying an AD patch.

The meta data for personalized regions are stored in personalization files in the MDS repository, under the following directory structure:

<prod_top>
 |-mds
   |-<component>
     |-webui
       |  + file.xml
       |-customizations
         |-<layer_type>
           |-<layer_value>
              + file.xml

The <layer_type> is the set of personalizations belonging to a given personalization level: Function, Verticalization, Localization, Site, Organization, Responsibility or User. The <layer_value> is the level value associated with the <layer_type>. The levels and corresponding level values are defined in the following table:

Layer Types (Levels) and Level Values
Layer Type (Level) Level Value
Function Function Name
Verticalization Industry ID
Localization Location Code
Site 0 (zero)
Organization Organization ID
Responsibility Responsibility ID
User User ID

Export Tool

The Export tool allows you to export a package or xml file (along with translation information) from the MDS repository of a database instance to a .xml file (or .xlf file for translations). The command line Export tool is necessary if you wish to perform bulk translations of personalization documents.

To use the Export tool, ensure that your classpath, path and environment are set up similar to the environment required for applying an AD patch, and call java oracle.jrad.tools.xml.exporter.XMLExporter <Package_or_Document_Name> with the appropriate parameters.

If you have Oracle JDeveloper OA Extension, you may alternatively use the export.bat file or the export shell script that is packaged with the JDeveloper IDE, located in the jdevbin\oaext\bin directory of the JDeveloper install area. The batch file and shell script each set up the classpath, path and environment for you. Just typing export without any parameters will give help about its usage.

Usage of the Export tool is as follows:

java oracle.jrad.tools.xml.exporter.XMLExporter <Package_or_Document_Name> -rootdir <output_dir> -username <username> -password <password> -dbconnection <database> [-mmdir <MMD_dir>]
[-includeSubpackages]
[-displayOnly]
[-jdk13]
[-validate]
[-translations]
[-language <language>]
[-dbdrvFile <dbdrv_file>]

Additional Information: There are two styles of exporting based on the version of JDK you are using. One style requires a minimum of JDK 1.1.8. The other style requires JDK 1.3 and provides additional convenience options, described below, that are not available with JDK 1.1.8. If you specify -jdk13 as an argument in the command line, the tool uses the JDK 1.3 style of importing.

The arguments should be replaced as follows:

Example Export Tool Usage

The following example exports the XML for the document /oracle/apps/fnd/dem/hello/webui//HelloWorldPG from the repository to the file system directory $APPL_TOP/personalizations, and inserts a DBDRV command into the exported XML document, using the JDK 1.1.8 style of the export tool (typical Apps ARU/ DBDRV use case):

java oracle.jrad.tools.xml.exporter.XMLExporter 
  /oracle/apps/fnd/dem/hello/webui/HelloWorldPG 
  -rootdir $APPL_TOP/personalizations 
  -username user1 
  -password <password> 
  -dbconnection "(description = (address_list = (address =
    (community = tcp.world)(protocol = tcp)
    (host =examplemachine.example.com)(port = 1521)))
    (connect_data = (sid = mach1)))"    
  -dbdrvFile d:\jdev\lib\ext\jrad\config\
     TemplateAppsJRADCustomizationFile.xml

The following example exports the French translation for the document /oracle/apps/fnd/dem/hello/webui//HelloWorldPG from the repository to $APPL_TOP/personalizations/fr_FR/oracle/apps/fnd/dem/hello/webui/HelloWorldPG.xlf, using the JDK 1.3 style of the export tool:

java oracle.jrad.tools.xml.exporter.XMLExporter 
  /oracle/apps/fnd/dem/hello/webui/HelloWorldPG    
  -rootdir $APPL_TOP/personalizations 
  -username user1 
  -password <password> 
  -dbconnection "(description = (address_list = (address =
    (community = tcp.world)(protocol = tcp)
    (host =examplemachine.example.com)(port = 1521)))
    (connect_data = (sid = mach1)))"    
  -mmddir d:\jdeveloper\jdev\myhtml\oa_html\jrad 
  -jdk13 
  -translations 
  -language fr-FR

Exporting Personalizations

If for any reason you cannot use the Personalization Repository page of the Functional Administrator responsibility to export personalizations, you may use the command line Export tool.

Step 1 - Determine the Path

To export a personalization, you must first determine the path to the document you personalized. You can determine the path of the MDS personalization document you wish to export by using the following rules:

Example 1

The Notification Worklist Table has a base document path of:

/oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG.

If you created a site level personalization for this document your resulting path to the customization document would be:

/oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG

Example 2

Suppose you create a function level personalization for the 'High Priority Worklist' custom function. In this case you need to know the function code for the 'High Priority Worklist' function. Let's assume it's OAFHP_WORKLIST. The path to the document would be:

/oracle/apps/fnd/wf/worklist/webui/customizations/function/OAFHP_WORKLIST/AdvancWorklistRG

You can also use SQL*Plus to review all the personalizations for a given base document. JDR_UTILS is a PL/SQL package that allows you to evaluate the list of personalization documents that are in your MDS repository. Included in this package is a procedure called jdr_utils.listcustomizations(''); which allows you to see the personalization document path names that are currently defined in MDS. To run this procedure, launch Sql*Plus, set serveroutput on, and execute the jdr_utils.listcustomizations(''); command. Replace the '' reference with an actual base document reference. For example, to see all the personalization documents for the Notifications Worklist Table, execute the following command:

exec jdr_utils.listcustomizations('/oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG');

If you run the example above, you may notice function personalization document references that you did not create. These are Oracle-seeded function-level personalizations created by the Oracle E-Business Suite development teams. Personalization definitions are seeded by development teams so that they can share components across products and vary their look and behavior slightly with each use.

For more information about JDR_UTILS, refer to the Inspecting the MDS Repository Content section in the Testing and Debugging chapter of the Oracle Application Framework Developer's Guide.

Step 2 - Export

Use the Export tool to export the base language personalized page from the MDS repository to an XML file on the file system. Insert into the path of the original document you personalized, the personalization level and level value mapping information determined in the previous step to derive the personalization document name.

Example of Exporting Personalizations

Export the site level personalizations made to the Advanced Worklist table document /oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG to $APPL_TOP/personalizations/oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG.xml.

Note: You can place the documents under any root directory you wish using the -rootdir parameter. The following example uses $APPL_TOP/personalizations as a recommendation.

java oracle.jrad.tools.xml.exporter.XMLExporter 
  /oracle/apps/fnd/wf/worklist/webui/customizations/site/0/
  AdvancWorklistRG
  -rootdir $APPL_TOP/personalizations
  -username APPSNAME 
  -password <password> 
  -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
     (HOST=yourhost)(PORT=yourport))(CONNECT_DATA=
     (SID=yoursid)))"

Import Tool

If for whatever reason, you cannot use the Exported Personalizations page of the Functional Administrator responsibility to import personalizations, you may use the command line Import tool. The Import tool allows you to import an xml file or package directory into the MDS repository of a database instance.

To use the Import tool, ensure your classpath, path and environment is set up similar to the environment required for applying an AD patch and call java oracle.jrad.tools.xml.importer.XMLImporter <Package_or_Document_Name> with the appropriate parameters.

If you have Oracle JDeveloper OA Extension, you may alternatively use the import.bat file or the import shell script that is packaged with the JDeveloper IDE, located in the jdevbin\oaext\bin directory of the JDeveloper install area. The batch file and shell script each set up the classpath, path and environment for you. Just typing import without any parameters will give help about its usage.

Note: With the migration from Oracle Containers for J2EE (OC4J) to Oracle WebLogic Server in Release 12.2, only the owner of the XMLImporter utility or the members of the apps (SID) group may execute the Import tool. However, since the Import tool is a standalone utility class, you can provide other user groups access by updating the permissions of the following files to "read" for the intended user group in both the run edition and patch edition file systems:

$FMW_HOME/oracle_common/modules/oracle.dms_11.1.1/dms.jar
$FMW_HOME/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar

Usage of the Import tool is as follows:

java oracle.jrad.tools.xml.importer.XMLImporter 
  <full_path_of_file_or_directory_to_import> -username <username> -password <password> -dbconnection <database> [-userId <userID>]
-rootdir <root_dir> [-rootPackage <root_pkg_dir>]
[-validate][-includeSubpackages][-jdk13]
[-mmddir <MMD_dir>]
[-displayOnly]

Additional Information: There are two styles of importing based on the version of JDK you are using. One style requires a minimum of JDK 1.1.8, which is how the ARU/DBDRV commands use the import tool. The other style requires JDK 1.3 and provides additional convenience options, described below, that are not available with JDK 1.1.8. If you specify -jdk13 as an argument in the command line, the tool uses the JDK 1.3 style of importing.

The arguments should be replaced as indicated:

Example Usage

The following example imports the XML file <JDEV_USER_HOME>/myprojects/mycompany/oracle/apps/fnd/dem/hello/webui/HelloWorldPG.xml (after copying it to $APPL_TOP/personalizations), using the JDK 1.1.8 style of the import tool (typical Apps ARU/ DBDRV use case):

java oracle.jrad.tools.xml.importer.XMLImporter 
  $APPL_TOP/personalizations/mycompany/oracle/apps/fnd/dem/hello/
  webui/HelloWorldPG.xml
  -username user1 
  -password <password> 
  -rootdir $APPL_TOP/personalizations    
  -rootPackage /mycompany/oracle/apps/
  -dbconnection "(description = (address_list = (address = 
    (community = tcp.world)(protocol = tcp)
    (host =examplemachine.example.com)(port = 1521)))
    (connect_data = (sid = mach2)))"

The following example imports all of the XML files for the package specified by the directory <JDEV_USER_HOME>/myprojects/mycompany/oracle/apps/fnd/dem/hello/webui/, using the JDK 1.3 style of the import tool. Import all files in subpackages as well and validate the files to import.

java oracle.jrad.tools.xml.importer.XMLImporter 
  $APPL_TOP/personalizations/mycompany/oracle/apps/fnd/dem/hello/
  webui/ 
  -jdk13 
  -mmddir "d:\deliver\jdev\mywork\config\jrad" 
  -includeSubpackages    
  -username user1 
  -password <password> 
  -rootdir $APPL_TOP/personalizations    
  -rootPackage /mycompany/oracle/apps/ 
  -validate 
  -dbconnection "(description = (address_list = (address = 
    (community = tcp.world)(protocol = tcp)
    (host =examplemachine.example.com)(port = 1521)))
    (connect_data = (sid = mach2)))"

The following example imports the site level personalized document, $APPL_TOP/personalizations/oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG.xml, into the MDS repository:

java oracle.jrad.tools.trans.imp.XLIFFImporter 
  $APPL_TOP/personalizations/oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG.xml
  -username APPSNAME 
  -password <password> 
  -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
    (HOST=yourserver)(PORT=yourport))(CONNECT_DATA=
    (SID=yoursid)))"

Known Issues

See a summary of key Personalization issues with suggested workarounds if available.

Related Information