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 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 testing 
  -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 testing 
  -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 APPSPWD 
  -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 testing 
  -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 testing 
  -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:

Example

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)))"