This chapter covers the following topics:
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.
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.
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.
Log in to the Oracle E-Business Suite under the Functional Administrator responsibility.
Select the Personalizations tab, then select the Import/Export sub tab.
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
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.
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.
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 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.
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 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 |
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\jdev\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>]
Note: 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:
<Package_or_Document_Name> - (Required) Replace with an OA Extension package name or file name. You can export all the OA Extension xml files in a package (even if they were imported separately) or export a specific OA Extension file. This argument points to the relevant package or file using the OA Extension syntax, which is case-sensitive when interpreting the OA Extension ID.
<output_dir> - (Required) Output directory where the exported xml file structure is to be stored. You may set this to any directory, however, we recommend that you export your packages or XML files to $APPL_TOP/personalizations.
If you run the export tool for the package /oracle/apps/ak/dem/webui/customizations/site/0/REQORDERSTATUSPAGE and specify -rootdir $APPL_TOP/personalizations, the xml file is saved as $APPL_TOP/personalizations/oracle/apps/ak/dem/webui/customizations/site/0/REQORDERSTATUSPAGE.xml.
Note: The command line Export tool does not consider the value of the FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH) profile option to determine its output directory.
<username> - (Required) Username for the database to export from.
<password> - (Required) Password for the database to export from.
<database> - (Required) Database connection for the database to export from, in tnsnames format.
<MMD_dir> - (Required) This argument is available only when you run the JDK version 1.3 style of the Export tool. Use this argument to specify the directory location of the OA Extension MMD files. (OAElementList.xml, JRADElementList.xml, UIXElementList.xml).
-includeSubpackages - (Optional) This argument is available only when you run JDK version 1.3 and applies only when you specify a package name to export. If you include this argument, then all the documents in the subdirectories of the package directory specified are exported. For example, consider the following directory structure:
oracle |-apps |-icx | |-regions | + region1.xml |-ak |-regions + region2.xml
If you run the export tool for the package oracle\apps with the argument -includeSubpackages, both region1 and region2 are exported.
-displayOnly - (Optional) This argument is available only when you run the JDK version 1.3 style of the Export tool. Include this argument to just display the list of documents to Export. The documents themselves are not actually exported from the repository.
-jdk13 - (Optional) Include this argument to run the JDK 1.3 style of the Export tool. The JDK 1.3 style of exporting supports the -withRefs, -includeSubpackages, -mmddir, -displayOnly and -validate options, whereas the JDK 1.1.8 style does not.
-validate - (Required) This argument is available only when you run the JDK version 1.3 style of the Export tool. Include this argument to validate the OA Extension files before exporting from the repository. The Export tool displays warning messages for any validation issues in the files, but the files are still exported from the repository even if there are validation warning messages.
-translations - (Optional) If this argument is specified, the Export tool exports from the repository, the translations, if any, for the specified XML documents and does not export the XML documents themselves. The translations (XLIFF documents) are exported to the appropriate language subdirectory as .xlf files, under the output directory specified by -rootdir. If the -translations argument is not specified, the Export tool exports only the specified MDS XML files from the repository.
<language> - (Optional) Language for which translations should be exported. The -language argument is valid only when the -translations argument is specified. If the -language argument is not specified but the -translations argument is, then translations for all languages are exported.
<dbdrv_file> - (Optional) File that contains the DBDRV command to insert into the exported XML document. A template file containing a DBDRV command is available at ..\jdev\lib\ext\jrad\config\TemplateAppsJRADCustomizationFile.xml.
Warning: The -dbdrvFile option should be used only by Oracle's in-house E-Business Suite developers.
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 testing -dbconnection "(description = (address_list = (address = (community = tcp.world)(protocol = tcp) (host =machine1.oracle.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 testing -dbconnection "(description = (address_list = (address = (community = tcp.world)(protocol = tcp) (host =machine1.oracle.com)(port = 1521))) (connect_data = (sid = mach1)))" -mmddir d:\jdeveloper\jdev\myhtml\oa_html\jrad -jdk13 -translations -language fr-FR
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.
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:
Note the original path to the document you personalized. This is found in the Personalize page of the Personalization UI. (For example: Document Name: /oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG)
Add '/customizations/', the personalization level, and level value that you have chosen in the personalization UI to the path of the document following the webui directory, but before the component name in the document reference path. The personalization levels and level values are defined in the following table:
Level | Level Value |
---|---|
Function | Function Name |
Verticalization | Industry ID |
Localization | Location Code |
Site | 0 (zero) |
Organization | Organization ID |
Responsibility | Responsibility ID |
User | User ID |
These values combined with the original document reference form the path to the customization document stored in the MDS repository.
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.
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 APPSPWD -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=yourhost)(PORT=yourport))(CONNECT_DATA= (SID=yoursid)))"
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\jdev\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.
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]
Note: 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 following:
<full_path_of_file_or_directory_to_import> - (Required) Replace with the full path to an OA Extension package name to import all the xml files in a package directory, or replace with the full path of a file name to import a specific xml file. This argument is case-sensitive.
Note: Although you can import XML files of your customizations from any location, we recommend that you copy the file or package directory you want to import to $APPL_TOP/personalizations and import from this staging area. For example, to import the file <JDEV_USER_HOME>/myprojects/mycompany/oracle/apps/fnd/dem/hello/webui/HelloWorldPG.xml, you would first copy it to the staging area $APPL_TOP/personalizations, so that the full path of the file you now specify is $APPL_TOP/personalizations/mycompany/oracle/apps/fnd/dem/hello/webui/HelloWorldPG.xml. To import all the files in the package, you specify $APPL_TOP/personalizations/mycompany/oracle/apps/fnd/dem/hello/webui/.
Note: If you wish to import a custom XML page, we recommend that you stage the file in $APPL_TOP/<CompanyIdentifier>/<CustomProductShortName>/<product-version>/mds/. Refer to "Deploying Customer Extensions" in the OA Framework Developer's Guide for additional information.
Note: JDK 1.1.8 only supports importing one file at a time.
<username> - (Required) Username for the database to import to.
<password> - (Required) Password for the database to import to.
<database> - (Required) Database connection for the database to import to, in tnsnames format.
<userID> - (Optional) User ID used to set the created_by or last_updated_by columns in the repository tables
<root_dir> - (Required) Root directory from where the xml files are loaded.
This should be the directory where the OA Extension package structure resides. If you follow our staging area recommendation for personalizations, this is: $APPL_TOP/personalizations.
Note: The command line Import tool does not consider the value of the FND: Personalization Document Root Path (FND_PERZ_DOC_ROOT_PATH) profile option to determine the root directory from where the xml files are loaded.
<root_pkg_dir> - (Optional) Top level directory under rootdir to which the OA Extension package belongs. For example, if under rootdir, you have a "fnd" directory, and the xml files belong to the "/oracle/apps/fnd" package, you would set the rootPackage argument as -rootPackage /oracle/apps. Note that this parameter has to start with "/".
Note: In the JDK version 1.1.8 style of the Import tool, if a "package" attribute is specified in an xml file's top level component, that "package" attribute takes precedence over the rootPackage and rootDir arguments and determines the package the document is imported into.
-validate - (Required) This argument is available only when you run the JDK version 1.3 style of the Import tool. Include this argument to validate the OA Extension files before importing into the repository. The Import tool displays warning messages for any validation issues in the files, but the files are still imported into the repository even if there are validation warning messages.
-includeSubpackages - (Optional) This argument is available only when you run the JDK version 1.3 style of the Import tool and only if you are importing a package directory. Include this argument to import all the xml files located in the subdirectories of the package directory specified. It is important you only have MDS xml files in the directory hierarchy when using this argument. For example, consider the following directory structure:
oracle |-apps |-icx | |-regions | + region1.xml |-ak |-regions + region2.xml
If you run the import tool for the package oracle\apps with the argument -includeSubpackages, both region1 and region2 are imported.
-jdk13 - (Optional) Include this argument to run the JDK 1.3 style of the Import tool. The JDK 1.3 style of importing supports the -loadRefs, -includeSubpackages, -mmddir, -displayOnly and -validate options, whereas the JDK 1.1.8 style does not.
<MMD_dir> - (Required) This argument is available only when you run the JDK version 1.3 style of the Import tool. Use this argument to specify the directory location of the OA Extension MMD files. (OAElementList.xml, JRADElementList.xml, UIXElementList.xml).
-displayOnly - (Optional) This argument is available only when you run the JDK version 1.3 style of the Import tool. Include this argument to just display the list of documents to import. The documents themselves are not actually imported into the repository.
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 testing -rootdir $APPL_TOP/personalizations -rootPackage /mycompany/oracle/apps/ -dbconnection "(description = (address_list = (address = (community = tcp.world)(protocol = tcp) (host =machine2.us.oracle.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 testing -rootdir $APPL_TOP/personalizations -rootPackage /mycompany/oracle/apps/ -validate -dbconnection "(description = (address_list = (address = (community = tcp.world)(protocol = tcp) (host =machine2.oracle.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 APPSPWD -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=yourserver)(PORT=yourport))(CONNECT_DATA= (SID=yoursid)))"
See a summary of key Personalization issues with suggested workarounds if available.
BLAF UI Guideline(s)
Javadoc Files
Lesson(s)
Sample Code