10 Exporting and Importing Content

OracleAS Portal provides a set of export/import utilities that enable you to move content between portal installations. This chapter provides a summary of recommendations and best practices developed for export/import functionality as provided in OracleAS Portal version 10g (9.0.4). This chapter contains the following sections:

• How Does Export and Import Work?

• What are the Most Common Use Cases?

• What Do I Need to Check Before I Begin?

• How Does Export Work?

• How Does Import Work?

• How Do I Manage My Transport Sets?

• How Do Objects Behave After Migration?

• What Are the Recommended Best Practices?

10.1 How Does Export and Import Work?

The export and import process consists of the following steps:

• Create transport sets and extract the content to transport tables. Transport sets contain the portal objects that you are planning to export to your target portal environment. This information is displayed in a manifest. The manifest is simply the list of objects in a transport set, used to provide a granular level of control over the export.

• Move the transport sets from one system (source) to another (target) using Portal export/import command-line scripts to generate a transport set dump file.

• Transfer the script and dump file to the target system using FTP or other file transfer utilities.

• Invoke the command line script to import the dump file to the transport tables on your target system.

• Import the objects from the transport tables to the target portal repository using the Transport Set Manager portlet.

10.2 What are the Most Common Use Cases?

OracleAS Portal supports the ability to copy or update page groups and portal content between your source and target destination portal instances. This section introduces some of the most common uses.

10.2.1 Case 1: Importing/Exporting Between Development to Production Instances

This case illustrates the steps involved in copying or updating portal page groups and portlets between a development instance and a production instance of OracleAS Portal.

Note: User customizations are not exported, therefore any customizations on a page or portlet on the source are not exported or imported.

Scenario 1. Exporting your pages and content to a target portal system. The first export to your target system should migrate the entire page group. The subsequent steps provide an overview of the process:

1. Develop page groups, applications and content on the source system.

2. Identify pages, applications and content to export, then create transport sets accordingly and export to the target system.

3. Import the transport sets on the target system, into your portal repository.

Scenario 2. Updating content on your target instance. OracleAS Portal supports the updating of item, region-level content on your target system ONLY under the following circumstance:

• Export/import of ALL changes from the source to the target instance. All page structure, content and user preferences on your target system are replaced with the content from your source system. The first export to your target system should migrate the entire page group from the source portal to the target portal instance.

Refer to Section 10.8, "What Are the Recommended Best Practices?", for a detailed overview of the recommended practices.

Note: The current release does not support editing the same content on both source and target portal instances.

10.2.2 Case 2: Deploying Identical Content Across Multiple Portal Instances

This case illustrates the process of deploying the same set of OracleAS Portal objects across multiple portal instances. Oracle EXP and IMP utilities can be useful when deploying identical content across multiple OracleAS Portal instances. In this case, the OracleAS Portal objects (portlets, page groups, and so on), can be created in one instance, and propagated to multiple instances using the Oracle EXP and IMP utilities. See Section 10.8.8, "Migrating Your Portal Across Databases" for details.

10.3 What Do I Need to Check Before I Begin?

Before proceeding with the export/import process, make sure you have the following information:

• System Requirements

• Privileges for Exporting and Importing Your Content

• Portal instance information:
  • Portal schema name

  • Portal schema password

  • Portal connect string information

  • Portal user name

  • Portal user password

  • Company name (used only for hosted portal installations) - leave blank in most cases.

    Note: The Portal schema password is a randomized password created on install. You may want to update the password to something more meaningful.

10.3.1 System Requirements

Before exporting and importing, ensure that your system meets the minimum system requirements, as described in this section.

Note: Export and import functions only within the same release of OracleAS Portal, for example, 9.0.4 to 9.0.4 You cannot export and import between two different releases, such as, 3.0.9 to 9.0.4.

• Using Different Releases and Versions of Export. Whenever you are moving data between different releases of the Oracle database server, the following rules apply:
  • The Oracle IMP utility and the database to which data is being imported (the target database) must be the same version.

  • The version of the Oracle EXP utility must be equal to the lowest version of the source or target database.

    Note: Oracle EXP and IMP are the export and import utilities used to dump and restore data in an Oracle specific format for backup and transfer of user data.

  The choice of whether to use the database Oracle home or the middle-tier Oracle home depends on the version of the database used for the source and target portal installations. The 9.0.4 middle-tier uses a 9.0.1.4 Oracle home.

  Based on the recommendations given earlier, the following conditions apply when a 9.0.4 portal and 9.0.4 middle-tier is involved:

  • Always use the middle-tier Oracle home for export. 9.0.1.4 is the lowest version of the database supported for a 9.0.4 portal installation.

  • Always use the target database Oracle home for import. The version of the import utility and the target database must be the same.

    Note: If you have configured a 9.0.2 portal (9.0.2.2 or 9.0.2.3) to use a 9.0.4 middle-tier then the rules described in the Using Different Releases and Versions of Export must be followed properly.

  For example, to create an export file for an import into a higher release database, use a version of the Oracle EXP utility that is equal to the source database. To create an export file for an import into a lower release database, use a version of the Oracle EXP utility that is equal to the version of the target database.

  Note: It is strongly recommended that you use the same database version for the source and target portal installations.

• The Oracle EXP utility always exports user data, including Unicode data, in the character sets of the export server. The character sets are specified at database creation.

  The Oracle IMP utility automatically converts the data to the character sets of the import server.

  Some 8-bit characters can be lost (that is, converted to 7-bit equivalents) when you import an 8-bit character set export file. This occurs if the client system has a native 7-bit character set or if the NLS_LANG operating system environment variable is set to a 7-bit character set. Most often, you notice that accented characters lose their accent mark.

  Both the EXP and IMP utilities provide indications of any required character set conversion before exporting or importing the data.

  Note: When the character set width differs between the export client and the export server, truncation of data can occur if conversion causes expansion of data. If truncation occurs, the export displays a warning message.

• Understand your source and target portal instances.
  • Do you have command line access to appropriate directories on the source and target machines? You must have command line access to run the shell or command utilities generated by the export-import process. The command line utilities in turn access the Oracle EXP and IMP utilities, as well as the Portal instance.

  • Is your database configured to allow the execution of background jobs? Each export or import process sets up a background process. Therefore, verify that the job_queue_processes database parameter is set appropriately.

    To check the value of the job_queue_processes parameter, perform the following query from SQL*Plus:

    %select name, value from v$parameter where name='job_queue_processes'
    
    

    The value for job_queue_processes should be at least 2 to allow the execution of background jobs.

    An alternative way of checking the job_queue_processes parameter is to examine the init.ora file in your database's ORACLE_HOME.

• Plan to perform the export and import process during non-business hours and to disable access to OracleAS Portal during the process. One way to disable access to the portal temporarily for all other users, is to configure your listener for a different port number during the duration of the export and revert it back to the original port when your export is complete.

10.3.2 Privileges for Exporting and Importing Your Content

This section describes the privileges required to successfully export and import your content.

10.3.2.1 Privileges for Exporting Your Content

To allow for secured control over the export of shared objects (objects in the Shared page group), there are now two privileges defined at the infrastructure level.

• Any Transport Set - Manage enables you to perform export/import of portal objects, including 'shared' objects. This privilege is granted to the DBA group by default during the portal installation process.

• A user with the Any Transport Set - Execute privilege can export/import portal objects, excluding shared objects. This privilege is granted to the PORTAL_ADMINISTRATORS group by default during portal installation process.

Table 10-1 provides a description of export user privileges.

Table 10-1  Export User Privileges

User Privileges	Export non - shared objects?	Export shared objects?
Any Transport Set - Manage	Yes	Yes
Any Transport Set - Execute	Yes	No
Any Transport Set - None	No	No

10.3.2.2 Privileges for Importing Your Content

In addition to the Any Transport Set - Manage privilege, you must also have Manage privilege on objects of a given type to successfully import your content.

For example, a page group containing Web providers require you to have Manage All privileges on All Providers and All Page Groups in order to import that page group. Table 10-2 provides a description of each object type and the required privilege level.

Note: The ORCLADMIN and Portal users are granted Manage All on all page groups at the time of install or upgrade. Members of the DBA group are also granted Manage All on all page groups by default.

Table 10-2  Import User Privileges

Object Type	Privileges
All Page Groups	Manage All: This privilege is required, along with the 'All Providers Manage' privilege to import page groups and shared objects.
All Providers	Manage: This privilege is required for the import of Page Groups and Portal DB Provider objects.
All Portal DB Providers	Manage: This privilege is required for the import of Portal DB Provider objects.
All Shared Components	Manage: This privilege is required for the import of shared components if the Portal DB Provider objects reference the shared components.

Note: If you import a page which is based on a style belonging to the shared objects group and do not have the necessary privileges to import shared objects, then the style of the page is reset to "Main Style" by default (provided the Ignore Warnings option was selected in the Transport Set Manager).

10.4 How Does Export Work?

This section describes the export process and the steps required to successfully move content from the source portal system, including:

• Creating Transport Sets

• Exporting Your Data

10.4.1 Creating Transport Sets

Once the system requirements are verified, your goal is to create a transport set. The subsequent diagram illustrates the process.

Note: Limit any possible conflict issues by making one person responsible for maintaining a transport set.

Figure 10-1 Export Process

Text description of the illustration cg_imex_export.gif

1. You select the objects to be exported from the Navigator or Bulk Actions (enables you to add multiple pages at once to the export transport set). The Transport Set Manager is automatically displayed.

2. You choose a name and select the export options for the Transport Set, click Export Now from the Transport Set Manager to initiate the export.

3. The procedure extracts the data and populates the transport tables.

4. You generate a migration script and log information from the Transport Set Manager.

5. You execute the script to generate a dump file.

The Export/Import Dependency Manager ensures that all the dependencies of objects in the transport set are correctly extracted. Specifically, the Dependency Manager classifies each object as explicitly selected, referenced, external or child, based on how the object is related to the objects being explicitly exported. The information is displayed in the manifest, see Figure 10-2.

• Explicitly Selected Objects. Objects, that were explicitly selected, from the Navigator or Bulk Actions for export. When a page contains a portlet from an external provider, the manifest displays the external provider as a dependency.

• Referenced Objects. Objects that are directly or indirectly referenced by the explicitly selected objects. For example, a style used by a page is a referenced object, when it belongs to the same page group.

• External Objects. External objects ensure that the explicitly selected objects perform on the target portal. For example, external-providers and database schemas could be considered external objects. Generally, shared objects and components are external objects unless explicitly selected.

• Child Objects. Objects that are part of a hierarchy. For example, sub-pages, sub categories and sub-perspectives are child objects of a page, category and perspective.

  Note: When a referenced object contains child objects then the child objects are always imported in reuse mode. You should therefore explicitly select the referenced object and include it in the transport set. This will enable you to set the import mode to Replace on Import. Before importing the page group in reuse mode, note the page group properties and after import manually update any changes to reflect the old properties.

Working with Import Modes

The manifest provides a granular level of control over the import mode. The manifest is simply the list of objects in a transport set. There are two modes available during import:

• Replace on Import. If the object exists on the target, it is replaced. If it doesn't exist, then it is created. When this mode is not selected and if the object exists, the object on the target portal is retained as is. However, if the object doesn't exist on the target, then it is created.

• Reuse on Import. If the object does not exist on the target, it is created. If it already exists, it remains as is.

The following table describes the object classification and the default modes.

Table 10-3  Default Modes

Object Classification	Default Import Mode
Explicitly Selected Objects	Replace on Import
Referenced Objects	Reuse
Child Objects	Replace on Import
External Objects	Reuse

Figure 10-2 Transport Set Manifest

Text description of the illustration cg_imex_exp_dep_mgr.gif

Clicking the name of an object, for example, an explicitly selected object, displays a detailed read-only screen of child, referenced and external objects, as shown in Figure 10-3.

Figure 10-3 Manifest Detailed Screen

Text description of the illustration cg_imex_manobjs.gif

Note: To simplify the manifest, seeded types are not extracted. If you want to extract them, create custom types in the Shared Objects page group based on the existing seeded types. The Dependency Manager includes these in the manifest.

10.4.2 Exporting Your Data

Review the Section 10.7, "How Do Objects Behave After Migration?" before migrating your portal content from a source to a target instance.

Note: Portlet repository information (security, organization, and so on) related to the portlet is not migrated during the export/import process.

To create a transport set for export:

1. Select the objects for export (from the Navigator, or search results > Bulk Actions for page groups). See Figure 10-4

   Note: Be sure to export portlets (Portal Forms, Portal Reports, Charts, Dynamic Pages), before exporting portal pages/page groups that reference them.

Figure 10-4 Portal Navigator

Text description of the illustration cg_imex_portal_nav.gif

2. Click the Export link to display the Transport Set Manager, as shown in Figure 10-5. Make the transport set name as descriptive as possible and avoid using any special characters at the start of the name. For example, My Company Transport Set 18-JAN-2003.

Figure 10-5 Transport Set Manager

Text description of the illustration cg_imex_transname.gif

3. Check the appropriate boxes under the Transport Set Options:
   • Access Control Lists. Includes Access Control Lists associated with the objects in the transport set.

   • Include Preferences for Users/Groups. Includes the users and groups global privileges when object Access Control Lists are selected for export.

   • Ignore Warnings. Allows the export to proceed when a warning is encountered.

   • Advanced Logging. Provides a detailed log of the export process, including debug messages.

4. Choose the import modes, delete any explicitly selected objects and promote (make explicit) any external objects. Making an external object explicit enables you to add a new object to a transport set 'in-place' instead of going back to the portal Navigator and adding it. External objects are not exported or imported by default until they are promoted as explicitly selected objects. See Figure 10-6

5. Select either, Export Now if you are finished, or Save for Later if you want to add more objects. See Section 10.6, "How Do I Manage My Transport Sets?" for details on how to edit and browse the transport sets currently on the system.

   Note: When you select some of the transport set options and choose Save for Later, the next time you add an object to the transport set all of the previously selected options are reset. Therefore, you should select the options each time until you finalize the transport set.

Figure 10-6 Transport Set Manager Objects

Text description of the illustration cg_imex_transmanifest.gif

6. Click Export Now to finalize the transport set. The objects marked for export are copied to the transport tables for migration. These operations happen in the background.

7. Check the log in your transport set manager for any errors by clicking the View Log Of Actions link.

Figure 10-7 Transport Set Log Output

Text description of the illustration cg_imex_trans_log_file.gif

8. Choose an appropriate export script based on your operating system. See Figure 10-8.

Figure 10-8 Portal Migration Scripts

Text description of the illustration cg_imex_transscripts.gif

For Netscape users:

1. Click the selected script, then 'Save Target As'.

2. Change the name and remember to include the correct filename extension, .csh for UNIX or .cmd for NT, for example, MyScript.csh.

3. Save the file to the directory on your file system where you will want to run the export script (generally this directory should be where your export portal resides).

   Note: UNIX users should save the file to a local directory and move the script to the middle-tier machine where the IMP utilities reside to create the dump file.

For Internet Explorer users:

1. Right-click the selected script, then 'Save Target As'.

2. Change the name and remember to include the correct filename extension, .csh for UNIX or .cmd for NT, for example, MyScript.csh.

3. Save the file to the directory on your file system where you will want to run the export script (generally this directory should be where your export portal resides).

   Note: This location must have access to the database. On some systems, the downloaded UNIX script requires you to set the execute permissions correctly before running it.

Running Your Script to Create an Export Dump File

The next steps in the export process are to create a transport set dump file using the script you just created in the last section, and then transfer your export data to your target system.

To create a dump file:

• The parameters in bold are only applicable for export and are mandatory. The subsequent example assumes that the name of the script is MyScript.csh.

  %MyScript.csh
  Usage: MyScript.csh <-mode export_or_import> <-s portal_schema>
  <-p portal_password> <-pu portal_username> <-pp portal_userpassword>
  <-company company_name> <-c connect_string> <-d dump_file_name(s)>
  <-automatic_merge>
  

  Note: The value for the company_name parameter is the company name you see in the login page when working in a hosted portal. When working in a non-hosted portal, the value for the parameter should be 'none'. If you're running the script in interactive mode no value should be passed.

  The following table provides a description of the parameters you can use in this process.

  Table 10-4  Parameter Descriptions

  Parameters	Description
  -mode	Mode for invoking the Export Import Command Line Utility EXPORT mode: Exports content to dump files using Oracle EXP utility IMPORT mode: Imports content from dump files using Oracle IMP utility
  -s portal_schema	Oracle database account for portal
  -p portal_password	Oracle database password for portal
  -pu portal_username	Lightweight username for logging into portal
  -pp portal_userpassword	Lightweight user password for logging into portal
  -company company_name	Company name (for example, ORACLE)
  -c connect_string	TNS Connection Information to remote database
  -d dump_file_name(s)	Name(s) of files for Oracle export or import utilities to write to or read from. If filename(s) are used, they must be separated by commas and enclosed in double-quotes. For example: "FILE1.DMP,FILE2.DMP"
  -automatic_merge	Automatically import contents of dump file

To transfer your export data:

1. Run the script using -mode export as the option.

   %MyScript.csh -mode export
   
   

   This prompts you for information such as schema name (source), password, dump file name(s), and so on. It also creates a dump file upon completion.

2. Finally, using FTP, transfer your dump file and export/import script to the machine where your target OracleAS Portal repository resides.

10.4.3 Exporting Large Page Groups

You can use the opeasst.csh (Oracle Portal Export Assistant) script to export large page groups, which may time out in the browser while calculating the page group dependencies. These timeout issues are due to the Dependency Manager and the pre-check routines that are run as foreground processes. The actual data extraction and the data merge are performed in the background.

The script can be found in the /portal/admin/plsql/wwu directory. An example of the script follows:

%opeasst.csh
Usage: opeasst.csh <-s portal_schema> <-p portal_password> <-c connect_string> 
<-ts transportset_name> <-pgrps pgrp_names> <[-export_acls [-include_prefs]]> 
<[-ignore_warnings]> <[-advanced_logging]>

The following table provides a description of the parameters used in this process.

Table 10-5  OPEASST.CSH Parameter Descriptions

Parameters	Description
-s portal_schema	Oracle database account for portal.
-p portal_password	Oracle database password for portal
-c connect_string	TNS Connection Information for the source database.
-ts transportset_name	Name of the transport set to be created
-pgrps pgrp_names	Comma-delimited list of Page groups for export
-export_acls	Export object level privileges
-include_prefs	Include preferences for users/groups
-ignore_warnings	Ignore any trivial warnings/errors generated during the data extraction process
-advanced_logging	Generate a very detailed log for the echo data extraction process

Perform the export from the command line, then:

1. Check the log in your transport set manager for any errors by clicking the Status link. See Section 10.6, "How Do I Manage My Transport Sets?" for details on how to edit and browse the transport sets currently on the system.

2. When the export is complete browse your transport sets and select the appropriate script for your operating system. See Section 10.4.2, "Exporting Your Data" for details.

3. Run the script using -mode export as the option.

   %MyScript.csh -mode export
   
   

   This prompts you for information such as schema name (source), password, dump file name(s), and so on. It also creates a dump file upon completion.

4. Finally, using FTP, transfer your dump file and export/import script to the machine where your target OracleAS Portal repository resides.

5. To import your objects, the contents of the transport set dump file must first be imported to the transport set tables on the target system. See Section 10.5.2, "Importing Your Data".

The following features and limitations currently exist:

• The script supports only exporting page groups.

• Multiple page groups can be exported at once using comma-delimited values.

• Exporting 'Account Control Lists', 'Include Preferences for User/Groups', 'Ignore Warnings' and 'Advanced Logging' are all supported.

• There is no import mode option available, that is, replace on import or reuse.

• Exporting database providers is not supported.

• If the Dependency Manager results in some external objects for the page group being exported, all the external objects are automatically promoted by the script without any user intervention. Those objects that are promotable are recursively promoted to become part of the transport set until there are no remaining external objects in the transport set.

• The script name cannot be changed.

  Note: Remember to set the infrastructure Oracle home when trying to connect to the database to run the opeasst.csh script.

10.5 How Does Import Work?

This section describes the import process and the steps required to successfully move content to the target portal system, including:

• Running Your Script on Your Target System

• Importing Your Data

10.5.1 Running Your Script on Your Target System

To import your objects, the contents of the transport set dump file must first be imported to the transport set tables on the target system. This is done by calling the same script (used in the export) with -mode set to import. The parameters in bold are only applicable for import and are mandatory.

%MyScript.csh
Usage: MyScript.csh <-mode export_or_import> <-s portal_schema>
<-p portal_password> <-pu portal_username> <-pp portal_userpassword>
<-company company_name> <-c connect_string> <-d dump_file_name(s)>
<-automatic_merge>

To perform the entire import from the command line, which initiates a background process, you must include the portal username and password parameters. This is required to validate your role on the target portal instance.

Note: The value for the company_name parameter is the company name you see in the login page when working in a hosted portal. When working in a non hosted portal the value for the parameter should be 'none'. If you are running the script in interactive mode, no value should be passed.

The contents of the dump files are imported and the transport set is made available from the UI for merging on the target portal system. Figure 10-9 illustrates how the import process works.

Figure 10-9 Import Process

Text description of the illustration cg_imex_import.gif

1. You import the contents of the transport set dump file to the transport set tables utilizing the same script used in the export.

2. A background job is submitted to initiate the import and log information is generated.

3. Once the import is complete, you can access the transport set from the User Interface.

   Note: To preserve data integrity, avoid: Importing an object, changing its name then re-importing it. Importing an object, promoting (moving it to shared objects) then re-importing it. Importing an object, then moving it from one hierarchy to another.

10.5.2 Importing Your Data

To import an object, the contents of the transport set must first be imported to the target system. When you select a transport set for import, a pre-check process determines if the objects already exist on the target.

To import your content:

1. Locate the Export/Import Transport Set portlet, installed by default on the Administer tab.

   Note: When you import a transport set and click the Browse Transport Sets link, you will see the newly imported transport set with a status of 'Export Complete' and links to the export scripts. Selecting a transport set on the target for Reuse resets the transport set. This makes the transport unusable because it was not exported from the target instance and therefore no objects exist that match the objects in the transport set.

2. Select the imported transport set; click Import.

   The Import Manager is displayed.

   

   Text description of the illustration cg_imex_impmanager.gif

   Check the appropriate boxes under the Transport Set Options:

   Note: The Access Control Lists and user preferences cannot be selected if you chose not to select them during the export process.

   • Access Control Lists. Includes the Access Control Lists associated with the objects in the transport set.

   • Include Preferences for Users/Groups. Includes the users and groups global privileges when object Access Control Lists are selected for import.

   • Ignore Warnings. Allows the import to proceed when a warning is encountered.

   • Advanced logging. Provides a detailed log of the import process, includes debug messages.

3. Click the Objects tab to view the list of objects included for import.

4. If you select Replace on Import, the object is replaced if it is found in the target portal.

   Note: Replace on Import mode is the default mode for explicitly selected objects; reuse is the default mode for referenced objects. The import modes are not applicable to the external objects until they are "promoted" to explicitly selected objects.

Figure 10-10 Transport Set Manager Import Objects

Text description of the illustration cg_imex_impobjs.gif

5. To view the log output, click the Status icon. The following table provides a description of each status type.

   Status	Description
   Text description of the illustration cg_expimp_pass.gif	Pass.
   Text description of the illustration cg_expimp_fail.gif	Fail.
   Text description of the illustration cg_expimp_warning_1.gif	Pass with Warnings. The Pass with Warnings status only appears when the Ignore Warnings option is selected in the transport set. Otherwise the object status will be set to Fail.

Figure 10-11 Transport Set Manager Import Log Output

Text description of the illustration cg_imex_impstat.gif

6. Click Close to return to the Objects page.

7. Select either, Import Now if you are finished or Save for Later.

   When you select Import Now, the exported objects are imported in the background. Clicking Save for Later saves changes to the transport set for later resolution and import.

8. Check the log for errors. If you select Ignore Warnings, then any warnings generated are ignored and the import proceeds. However, if the Ignore Warnings option is not selected, and warnings exist, the import will fail.

To ensure that everything has been imported correctly, check the following:

• In the Navigator, verify that the content in each portal page group that you have imported has been imported correctly. Specifically, for each portal page, verify that the appropriate portlets all appear in each region of your portal page. When these portlets (navigation pages, pages exposed as portlets, DB provider components or web portlets) occur as external dependencies and they do not exist on the target when Ignore Warnings is enabled then the portlet entry is deleted from the page.

  Note: During import a two-step pre-check process is performed. Clicking the initial View Log shows both the first stage of the process, and the pre-check as complete. This is done prior to the actual import and prior to data populating the portal tables. Clicking the Refresh Log will show both the second stage of the process and the pre-check with a different timestamp.

What happens when I select 'Ignore Warnings'?

Objects that are being imported can be classified into two types:

• Warning Types - Objects that, on failure cascade warnings to explicitly selected objects.

• Failure Types - Objects that, on failure cascade failures to explicitly selected objects.

When the Ignore Warnings option is selected the warning types will raise warnings and the explicitly selected objects will be imported. However, if there is a failure type object and it fails, then the explicitly selected object will also fail irrespective of the Ignore Warnings value.

If an explicitly selected object has two dependencies, a warning type and a failure type and if both the dependencies fail the pre-check process, then the failure type will dominate and the explicitly selected object will also fail even if Ignore Warnings is selected.

If Ignore Warnings is not selected, then the warning type objects will fail, that is, the explicitly selected object will fail.

Ignore Warnings impacts explicitly selected objects more than any other kind of object. Referenced and external objects raise failure/warnings for the explicitly selected object based on their type and whether the Ignore Warnings option is set. Figure 10-6 describes the expected behavior for each object when selecting the Ignore Warnings option.

Table 10-6  Warning/Failure Types

Object	Type	Expected Behavior
Attribute	Failure	The explicitly selected object will fail when the dependent attribute fails.
Itemtype	Failure	The explicitly selected object will fail when the dependent itemtype fails.
Pagetype	Failure	The explicitly selected object will fail when the dependent pagetype fails.
Style	Warning	The style will default to the main style of the page group that it belongs to.
Category	Warning	The category is set to 'none'.
Perspective	Warning	The perspective associated with an item/page is removed.
Page Template	Failure	The explicitly selected object will fail when the dependent template fails.
Page	Warning	There can be three possible outcomes when a page is a dependent of another object: Page exposed as a portlet. The portlet entry is removed from the region that contained the page portlet. Page link pointing to a page. The page link item is removed from the region, since the page to which the link is pointing to has failed. Pronto Dependency. The link that was pointing to the page that failed, is reset to point to the same page in which the Pronto link is located.
Navigation Page	Warning	The navigation page portlet is removed from the page. You can associate the page with another navigation page after import.
Color, Font, JavaScript, Application Template, Image	Warning	Set to default at runtime.
DB Provider Component	Warning	The portlet entry where the component is placed is deleted from the page.

When the container objects listed subsequently appear as an external dependency, because their child objects have been selected for export and they do not exist on the target, then the explicitly selected object (child object of the container object) will always fail irrespective of the Ignore Warnings value.

• Page group

• Portal DB Provider

• Category

• Perspective

• Page

10.6 How Do I Manage My Transport Sets?

The Export/Import Transport Set portlet, shown in Figure 10-12, is installed by default on the Administer tab and enables you to export, import, edit and browse the transport sets currently on the system. This section discusses the following:

• Editing a Transport Set

• Browsing Transport Sets

Figure 10-12 Export/Import Transport Set Portlet

Text description of the illustration cg_imex_exp_imp_portlet.gif

10.6.1 Editing a Transport Set

You can view and edit the list of objects selected for a transport set. Once you have created a new transport set and selected the Save for Later option:

• Navigate to the Export/Import Transport Set portlet.

• Select the Transport Set from the export list of values.

• Edit the preferences.

10.6.2 Browsing Transport Sets

You can view all of the transport sets that are on the system and their current status. You can also view the log of actions, referenced objects and download export/import scripts. Additionally, you can delete transport sets from the system or to reuse a transport set, select the transport set and click Reuse.

Note: The Reuse option is only valid for transport sets in the source portal with a status of 'Export Complete' or 'Export Failed'.

Figure 10-13 Browse Transport Sets

Text description of the illustration cg_imex_browsw_trans.gif

10.7 How Do Objects Behave After Migration?

The following considerations should be made before migrating portal content from a source to a target instance using OracleAS Portal export/import. This section discusses the behavior of portal objects after migration.

Table 10-7  Behavior of Objects

Object Type	Behavior
Page Groups	On the first export/import, if a page group doesn't exist, it is created on your target system. Any settings at page group level are replicated on the target system. On the second import, depending on the mode selected: Replace on Import mode. The page group properties from the source replace those on the target. All objects within the page group are created/updated depending on whether they existed or not. Reuse mode. When page groups already exist on the target the properties are reused and not updated. New objects within the page group are created, existing objects are reused. Notes: New pages are currently not created when page groups are imported using reuse mode. The order of visible objects (in the Configure tab) may differ between the source and target portal. This will result in the drop-down lists (when selecting an item, category, and so on) to look different in the target portal. You can manually re-order the visible objects in the target.
Attributes	On the first export/import, the attributes are created on the target system. The second import, depending on the mode selected for your target: Replace on Import mode. The properties of the attribute are updated. Reuse mode. When the attribute already exists on the target it is reused and not updated. Notes: Attributes that are marked as external cannot be created on the target even with Any Transport Set - Manage privilege. Attributes on the source and the target can only be considered the same when they have the same name, are the same type and have the same unique internal identifier. If the two attributes have the same unique internal identifier but different names then they can be only imported in replace on import mode. If the name and the type are the same but the unique internal identifier is different then the attribute import will fail and cascade to any other related objects.
Approvals	To view the approvers, Access Control Lists must be exported and imported along with the page group or page that has an approval defined on them. Replace on Import mode. The Approval process can be established for a page or page group. If a page group or a page is marked for either insert or update, then the approval object will be processed in replace on import mode. All the information in the target will be deleted and re-created. Reuse mode. No action is performed.
Items	Item information comes as a part of page export. They follow the import mode of the page. Replace on Import mode. When a page is imported in Replace on Import mode, items in page regions from the source are copied to the target. Any items found only on the target are removed, items that exist on both the source and target are updated, and items that exist only on the source are created. Reuse Mode. No items are imported from the source. The page from the source is only used as a reference, and will determine the import mode of items. Notes: If PL/SQL items are present in the pages being exported, the Dependency Manager does not mark the PL/SQL execute schema as an external dependency. For this reason, ensure that the target database instance already has the schema that is referenced by PL/SQL items, or manually migrate them before importing the items. The list of object items will show differently between source and target unless you migrate those referenced objects (pages, categories, and perspectives) within the same transport set as the list of objects. Note that the Dependency Manager will not mark the objects referenced in the list of objects for export. For this reason, you need to explicitly mark those referenced objects for export, or ensure that they are already in the transport set. If portlet instance items are moved from one region to another between subsequent imports of the same page, any customization made by the user(s) on those portlet instances are removed.
Pages	Exports the page and the page type, template, and style it references along with content (item and portlets). Replace on Import mode. The properties of the page are replaced. For region import behavior see, 'Regions'. For item behavior see, 'Items'. Reuse mode. The original page on the target is reused. Notes: The current release does not support locking and unlocking content using WebDAV. Content contributors can lock a file, which in turn will check out the item. On import no owned locks will be displayed. Edit defaults and customizations for web portlets are not currently migrated. When a page exposed as a portlet appears in the external objects list, make sure to include the page in the transport set.
Regions	Region information comes as part of page export. They follow the import mode of the page. Replace on Import mode. When a page is imported in replace on import mode, page regions from the source are copied to the target. Any regions found only on the target are removed, including all content in those regions. Reuse Mode. No regions are imported from the source. The page from the source is only used as a reference, it will determine the import mode of regions.
Templates	Exports the template and the style it references and any content on the template. The layout and content of pages that depend upon the template are synchronized with the revised template on the target. Replace on Import mode. The template properties are replaced on import. Reuse mode. Template information is reused on the target and is not updated from the settings on the source system. Notes: Changes to the template are currently not replicated in pages that use the template in the target when the pages are not imported along with the template. You should always export the template and the pages (using the template) together. Avoid creating pages that use the imported template directly on the target as these would not be synchronized correctly with the updated template. Do not export or import the following templates found in the shared objects or page group (they are present only if a category or perspective is created in that page group), Category Pages Template or Perspective Pages Template. A template can force all pages based on the template to use the template's style, or it can allow pages based on it to have their own style. When importing a template whose style has changed, the changes are only propagated to the pages based on the template if the template forces the pages to use the template's style.
Categories	Exports the category and its sub-categories. Reuse mode. The original category on the target is reused. Notes: The category page (the page that appears when a category is clicked) and the category template are not exported. They are created each time on import. The category is always reused, therefore you should make any changes once on the target and it will never be lost during subsequent imports. This applies to the category, the category page and the category template. There is no replace on import mode. The replace on import option will not apply, the category will always be reused.
Perspectives	Exports the perspective and its sub-perspectives. Reuse mode. The original perspective on the target is reused. Notes: There is no replace on import mode. The replace on import option will not apply, the perspective will always be reused. The perspective page (the page that appears when a perspective is clicked) and the perspective template are not exported. They are created each time on import. The perspective is always reused, therefore you should make any changes once on the target and it will never be lost during subsequent imports. This applies to the perspective, the perspective page and the perspective template.
Navigation pages	Exports the navigation page and the style it references and any links on the navigation page. Replace on Import mode. The properties of the navigation page are replaced. Reuse mode. The original navigation page on the target is reused.
Styles	Exports the style. Replace on Import mode. The properties of the style are replaced. Reuse mode. The style on the target is reused. Note: Styles on the source and the target can only be considered the same when they have the same name and the same unique internal identifier. If the two styles have the same unique internal identifier but different names then they can be only imported in replace on import mode.
Item Types	Exports the item type and the attributes it references. Seeded item types can be modified, such as file item but these modifications are not reflected on the target. Notes: It is recommend that if you modify a seeded item type, that you make a copy of the seeded item type and modify the attributes of the copy. Item Types on the source and the target can only be considered the same when they have the same name, are the same type and have the same unique internal identifier. If the item types on the source and the target have same unique internal identifier but different names then they can only be imported in replace on import mode. Currently when the attributes associated with the custom types (item type, page type) are modified or the functions associated with the custom type are modified between imports, the changes are not always correctly migrated. You should delete and re-create the custom type on the target. This will result in all the items/pages (based on the custom type) being deleted.
Page Types	Exports the page type and the attributes it references. Note: Page Types on the source and the target can only be considered the same when they have the same name, are the same type and have the same unique internal identifier. If the page types on the source and the target have same unique internal identifier but different names then they can only be imported in replace on import mode.
Portal DB Providers	Exports the entire Portal DB Provider and the shared components it references. Make sure that the schema referenced in the registration information (in your source portal) is exported and imported first. Replace on Import mode. The properties of the Portal DB Provider are replaced. Reuse mode. The Portal DB Providers on the target are reused. Note: Whenever a database provider component is exported, the provider associated with the component is included as an external dependency.
Web Providers	All web providers referenced by your transport set must either exist already on your target system or be able to be registered successfully during the import on your target system. Reuse mode. Providers are always reused. Note: If the provider registration generates an error, due to insufficient privileges then the provider object fails the pre-check stage. This is then cascaded to the explicitly selected objects, a provider failing always fails the explicitly selected objects irrespective of the ignore warnings value.

10.8 What Are the Recommended Best Practices?

The following is a summary of important recommendations and best practices developed for migrating portal content from a development or test environment to a production instance using OracleAS Portal export/import:

• Migrating Your Users and Groups

• Migrating Your Page Groups and Components

• Migrating Your Web Providers

• Migrating Your Portal DB Provider Schemas

• Migrating Your Portal DB Providers and Components

• Migrating Your Oracle Reports Components

• Migrating Your Search Components

• Migrating Your External Applications

• Migrating Your Portal Across Databases

10.8.1 Migrating Your Users and Groups

Oracle recommends the following procedure for export/import:

• Develop your portal objects (page groups, content, portlets, and so on) on your source/development system.

• To simplify the task of export/import, assign users, groups and privileges ONLY on your production system.

• Use export/import to migrate your portal objects to your target/production system.

• Apply users and privileges to imported portal objects as needed.

Users and groups are defined in Oracle Internet Directory. When you choose to include Access Control Lists and User and Group Preferences during a Portal Export, the user and group profiles held in the Portal schema are included in the transport set. However this does not migrate the user and group definitions that are held in Oracle Internet Directory.

For the user and group profiles to be properly imported on the target portal, the user and groups that they refer to, must exist in the target portal's associated Oracle Internet Directory.

If you are building your portal content on a test or development server, with the intention to then move that content to a production server, you have the option of assigning your security privileges on the test server and then migrating them, along with the content, to your production server.

In this scenario, assign the privileges to groups, so there is no need to ensure the consistency of the user population between the test and production infrastructures.

If you want to precisely model your user population on both the production and test servers, the best approach is to use Oracle Internet Directory's Directory Integration Platform - Directory Synchronization capabilities to synchronize the data from the production directory server to the test server. Synchronizing the data from production to test also provides you the option of adding test users and groups to the test Oracle Internet Directory server without affecting the production server.

Note: See the Oracle Internet Directory Administrator's Guide for more information on setting up directory synchronization. Note that it is advisable to automatically synchronize the data from production to test, but not the other way around.

With the production groups also present on the test server, you can model and test all your access privileges on the test server and then safely migrate the Portal Access Control Lists with your exported objects onto the production system.

If you are introducing new groups and access privileges for those groups on the test system, then before you move the Portal content and access control lists to production, make sure you migrate the group definitions to production first. You can actually create the groups on production first, and let the synchronization process reflect the new group on the test system before applying the test access control entries, if you need to actually create the group on the test instance first, you can create the group on production with the same means you used to generate the group on test. If this was done manually, and you want to avoid repeating the manual step on production, you can issue an LDAP query on the test instance to generate an LDIF file, which you can then load onto the production instance. For example:

%ldapsearch -h testoid.domain.com -p 389 -D cn=orcladmin -w password123 -b 
'cn=portal.iasdb.domain.com,cn=groups,dc=domain,dc=com' -s sub -L `cn=groupname' 
> newgroup.ldif

Note: Before loading the LDIF file containing the group information into the production Oracle Internet Directory instance, you may need to edit the file to correct the portal instance name to match the name for that portal instance on the production Oracle Internet Directory instance. This name will typically be different between the test and the production instances and the name is part of the group DN, so it will have to be modified before loading the file.

In this example, cn=portal.iasdb.dbserver.domain.dcom, cn=groups, dc=us, dc=oracle, dc=com is the location under which the portal groups are located. Refer to the Security chapter for more information on the organization of the entries in the Directory Information Tree in Oracle Internet Directory. This creates a file called newgroup.ldif containing the group definition. You can then load the file on the production Oracle Internet Directory instance by using ldapadd:

%ldapadd -h prodoid.domain.com -p 389 -D cn=orcladmin -w password123 -v -f 
newgroup.ldif

You may only want to deploy default privileges granted to some of the seeded Portal groups, or no privileges at all. If no privileges are deployed, then the user performing the import will own the objects. The user can then further grant privileges on the target system as necessary for the specific deployment.

There is no need to synchronize seeded groups or users, assuming that, if privileges are granted to seeded groups in Portal, and those seeded groups are still present on the target system, then the privileges will be correctly associated with those seeded groups.

When migrating group profiles from the source to the target, the import will remap the DNs of the groups to the local group base on the target system if the exported profile was one for a local group on the source. A local group is one that is under the portal group container (the group install base). For groups that were not under the group install base, the DN will remain unchanged.

Note: The ssoexp and ssoimp scripts found in the wwu directory are obsolete for 9.0.x and not compatible with the 9.0.x login server. These should not be used.

10.8.2 Migrating Your Page Groups and Components

Page groups and their associated components may be moved from development to production using the export/import utilities described in this document. In addition to page groups as a whole, individual components within page groups such as sub-pages, categories, perspectives and page styles can be moved individually to the target system, only if the entire page group has been imported to the target system earlier.

Note: The current release does not support the use of circular references. If you import a page group which contains a circular reference then this will produce an ORA-00001: unique constraint error, however the import should still finish successfully.

• Some considerations and best practices to keep in mind are the following:
  • The first export to your target system should migrate the entire page group from the source portal to the target portal instance. Subsequent transport sets can then export an individual page, or other page group component on the target portal installation.

    Note: The pre-check process will fail for an object if the page group does not exist on the target. Whenever a page group object is exported, the page group that owns the object is included as an external dependency. You can chose to promote the page group if you do not know if the page group exists on the target and therefore avoid any potential pre-check failures. The same applies to other objects included in a hierarchy. Categories, perspectives and pages when exported display the parent category, perspective or page as an external dependency in addition to the page group to which they belong. All database provider components display the provider as an external dependent when they are exported by themselves. The default settings of a page group, for example, the default template, style, navigation page, and so on, are also extracted by the Dependency Manager and classified as either reference or external (that is, local or shared).

  • All new or existing content on a page is replaced when a page with the same name is being re-imported to the target.

  • You can only move objects within a page group to the same page group of the same name on the target portal.

  • A page is migrated along with any sub-pages.

  • After an initial import operation to your target system, if you change the name of the page group on the target system, subsequent import attempts to that page group will fail.

  • Categories, itemtypes, perspectives and pagetypes that are configured in the source are not automatically configured in the target. You must explicitly configure these objects unless you are doing a page group export.

• Page URL Behavior. Always use page link item types or direct access URLs when creating links to portal pages. Do NOT use "raw" portal page URLs.

  By default, portal page URLs generated by OracleAS Portal contain installation specific ID numbers that change when the object is exported. This causes broken links when pages are imported into a different site.

  Here is an example of a URL generated for a page. If the page is imported on another site, this PAGEID will change.

  http://my.portal.com/servlet/page?_pageid=47,49&_dad=portalr2&_schema=portal
  
  

  If you are using such URLs as manually entered links, we recommend instead the use of Direct Access URLs or Page Link item types.

  The same page has this direct access URL:

  http://my.portal.com/pls/portal/url/PAGE/HRPAGEGROUP/HRHOME/HRBENEFITS
  
  

  To find the direct access URL for a page, look at the page property sheet. A link to the property sheet can be displayed by adding a Property Sheet Smart Link item to the page.

  You can also use a Page Link item type to create a link to a page. The Page Link item type dynamically generates the correct link at runtime.

• Page Portlets: When you replace a page, the content as well as the structure is replaced on the target.

  Note: This release does not support the import/export of the OracleAS Portal Survey components or the Favorites portlet.

  To preserve content in a page (items, portlets) on the target, but import a style, layout or rendering changes from the source then expose your content through the Federated Portal Adapter portlet. The key here is to separate your content from your page structure into two separate page groups. One for content only, exposed through the Federated Portal Adapter, and the other is your 'display' page group. Users can use this to access, view, and customize their portal. Follow these steps:

  1. On the source system, create a page group that only contains pages that have one region that you will later expose to other pages. This region is to be populated with either portlets or items. Name this page group "Content Page Group".

  2. Export this content page group to the target system.

  3. On the target system, register the content page group through the Federated Portal Adapter. Expose these pages as portlets through the Federated Portal Adapter provider on the target system.

  4. On the source system, register the same provider (using the same name as the Federated Portal Adapter provider).

  5. On the source system, create another page group called "Display Pages". In this page group, construct pages with regions that expose the portlets from the Federated Portal Adapter provider. You can also include tabs, and other portlet regions in this page group if required.

  6. Export the "Display Page" group to the target system.

  7. From the target system, update, delete, modify, and add new items to the regions, pages in the content page group exposed through PL/SQL provider.

  8. On the source system, make changes to the page structure (tabs, new regions, and so on) to the "Display Page" page group.

  9. Export the latest "Display Page" page group to the target system.

  10. Verify that the "Content Page Group" contains the new changes that you made in step 7 on both the source and the target environments.

  11. Verify that the target system contains the latest changes to the pages in the "Display Page" page group that you recently changed.

      Note: When a page containing a portlet from an adapter rendered provider (the loop-back case) is imported and the provider is automatically registered on the new portal, it will have the old URL, referencing the old portal. When a loop-back provider is required in the new portal, you will have to create one or update the default provider.

• Page and Portlet Customizations and Edit Defaults Migration. You can preserve the user customizations on a page or portlet on the target system while replacing or reusing the edit properties or edit defaults of that page or portlet.

  Note: Edit Defaults and Customizations for web portlets are not currently preserved.

  Base objects that no longer exist on the page in the source portal will be removed from the target page after subsequent imports. This will ensure that all customizations for base portlet regions are also removed. Base objects are regions, portlets/items and tabs that are imported as part of the core definition of the page, defining its structure and content.

  Portlets that already exist on a page behave in the following way when the page is imported in replace on import mode:

  • Edit Defaults will be replaced.

  • User Customizations will be preserved.

  Properties of the page behave in the following way when the page is imported in replace on import mode:

  • Edit Properties will be replaced.

  • User Customizations will be preserved, subject to the user customizations being valid.

    Note: You can customize, add, hide/show, delete and move portlets and tabs. The page must have at least one portlet region and one tab (tab related customizations) in that region. The customized objects inherit the properties of the page. When a region is deleted, for example, a second import removes the region or tab from the page, then customized objects will also be deleted.

  When you import the page with an increase in the number of portlets on a page, then the source takes precedence even if you have customized the page in the target and deleted a portlet. The next time you import the same page, the deleted portlet is considered to be a new portlet to be added to the structure on the target. This also applies to tabs.

  The order of appearance of these portlets (customizations) and the portlets that form the content of the page are determined by the source and mode of import.

  • Replace on Import mode. The portlets from the source are arranged in the order found in the source followed by the portlets in target (customizations).

  • Reuse Mode. The customizations are preserved and there will be no changes to the target page.

10.8.3 Migrating Your Web Providers

Before importing on your target system, all providers referenced by your transport set must either already exist on your target system or be able to be registered successfully during the import on your target system. The pre-check process determines if a provider of the same name already exists on the target. If the provider does not exist, then the pre-check attempts to register the provider.

To ensure successful registration, check that your providers meet the following conditions on your target system:

• Ensure that you have sufficient privileges to register the web providers.

• Ensure that you have connections to your providers during the import operation. An alternative is to remove portlets of those providers that may not be contactable or available during the import process from the pages before exporting. Then add them back manually to the pages on your target system after importing.

• If you are using proxies on either your import or export portal installations, ensure that your proxies are configured correctly on your import installation before importing.

• Consider registering your providers manually in advance of performing your import on the target system to help ensure that your import operation goes smoothly.

  Note: If you start the import process then decide not to proceed, some stray providers may remain on your target portal due to the pre-check process of registering the providers.

• If you register your providers manually, they need to have the same name as the corresponding providers on your source system.

  Note: A different URL for the development (source) provider and the production (target) provider can be used. Pre-register the production provider on the target portal server with the same name as the development provider on the source portal server but pointing to the appropriate URL for the production provider. When pages referencing the provider are imported from the source to the target, they will point to the production provider instead of the development provider.

10.8.4 Migrating Your Portal DB Provider Schemas and Components

A Portal DB Provider Schema is the schema specified when registering the DB provider. The subsequent steps must be performed for the successful migration of pages that reference Portal DB Provider portlets.

1. Use the Oracle EXP utility to export the Portal DB Provider schemas. See Section 10.8.4.1, "Migrating Your Portal DB Provider Schemas" for details.

2. Export the Portal DB Providers and Components. See Section 10.8.4.2, "Migrating Your Portal DB Providers and Components" for details.

3. Use the Oracle IMP utility to import the Portal DB Provider schemas.

4. Import the Portal DB Providers and Components.

   Note: Make sure that the schema referenced in the registration information (in your source portal) is exported and imported first and has the same name on target as the source. If your Portal DB Provider components references schema objects outside this schema then ensure that the other referenced schemas are also present on the target. Grant any necessary privileges between these schemas and the Portal DB Provider schema.

The simple example that follows provides an overview of the process. SAMPLE_APPLICATION is a Portal DB Provider that needs to be migrated. It uses the PORTAL_SRC_DEMO schema for the database objects referenced by the components.

Assumptions

• PORTAL_SRC_DEMO is the Portal DB Provider building schema in the source.

• PORTAL_SRC is the source portal instance.

• PORTAL_DST is the target portal instance.

Steps

Ensure that the source portal instance is setup in one database instance and that the target portal is setup in a different database instance.

1. Use the Oracle EXP utility to export the PORTAL_SRC_DEMO schema from the source.

2. Export the Portal DB Provider from PORTAL_SRC.

3. In the target database instance, use the Oracle IMP utility to import the PORTAL_SRC_DEMO schema.

4. Import the dump file (from step 2) into the newly created schema on the target database instance.

5. Import the Portal DB Provider into PORTAL_DST.

10.8.4.1 Migrating Your Portal DB Provider Schemas

The Portal DB Provider schemas must be exported and imported first. Follow the steps that follow:

• For database schema(s) used by Portal DB Providers that are marked for export
  • Use Oracle EXP/IMP utilities to migrate the database schema(s)

  • Grant privileges that were not covered by the migration specified earlier

10.8.4.2 Migrating Your Portal DB Providers and Components

Portal DB Providers (portlet builder components) may be exported as part of a transport set in much the same way as page groups, either independently or as part of the same transport set with page groups and shared objects.

Note: The current release does not support exporting seeded providers, for example, 'people_app' or development in place portlets.

If the same schema name cannot be used for the Portal DB Provider in the target portal instance, then perform the following steps:

1. Create the schema with all the required objects for it to be a Portal DB Provider.

2. Manually register a Portal DB Provider with the same name as the export portal pointing to this schema before using Portal export/import.

The following Portlet Builder object types can be exported from Portal:

Table 10-8  Portlet Builder Object Types

Object Type	Description
Portal DB Provider	Exports the entire Portal DB Provider and the shared components it references.
Form	Exports the form and the shared components they reference.
Report	Exports the report and the shared components they reference.
Chart	Exports the chart and the shared components they reference.
Calendar	Exports the calendar and the shared components they reference.
Dynamic Page	Exports the dynamic page and the shared components they reference.
XML Component	Exports the XML component and the shared components they reference.
Hierarchy	Exports the hierarchy and the shared components they reference.
Menu	Exports the menu and the shared components they reference.
URL	Exports the URL and the shared components they reference.
Frame Driver	Exports the frame driver and the shared components they reference.
Link	Exports the link and the shared components they reference.
List of Values	Exports the list of values and the shared components they reference.
Data Component	Exports the data component and the shared components they reference.

Note: If a page group contains portlets from a Portal DB Provider, then the provider has to be explicitly included in the transport set you are exporting. Otherwise, export/import the provider beforehand.

10.8.5 Migrating Your Oracle Reports Components

Oracle Reports objects may be moved from development to production using the export/import utilities described in this document. Individual components can be moved to the target system, only if the first export migrates the entire page group from the source portal to the target portal instance. Subsequent transport sets can then export individual components.

Table 10-9  Oracle Reports Object Types

Object Type	Description
Server Access	Exports the Server Access file.
Combined Availability Calendar	Exports the Combined Availability Calendar.
Simple Availability Calendar	Exports the Simple Availability Calendar.
Report Definition File	Exports the Report Definition file.
Printer Access	Exports the Printer Access file.

The Portal DB Provider owner creates every Report Security Access component (RWSVR,RWPRN,RWCAL,RWCPC,RWREP). Once the owner is migrated, all of the dependent components, shared components, and report security access components are migrated as well.

Available options include:

• Remove the reports server integration from the pages being exported on the source system (this would also include removing page parameters associated with or dependent on the reports objects).

• Export/import the page group and verify that the pages imported on your target system display correctly.

• Import reports on the target (through the Portal DB Provider). Integrate the reports server objects with the imported page on your target system.

10.8.6 Migrating Your Search Components

There a number of options for adding search components to your pages. You can add a simple Basic Search to match search criteria entered into the Search field; an Advanced Search, and a Custom Search to create an automatically executed search.

10.8.6.1 Basic and Advanced Search Portlets

Basic Search portlets and Advanced Search portlets can be exported and imported. After import, the portlets should appear as they did in the source portal including the user preferences (if the user preferences were being imported).

10.8.6.2 Custom Search Portlets

Custom Search portlets can have many customizations which refer to other objects in the portal, such as page groups to search, attributes to search on, image on submission form, style for results, page for the results, attributes for the results, default values for category, perspective and item type attributes. These can be referred to as dependencies. When a custom search portlet is exported and imported its dependencies are not automatically exported and imported. Therefore, it is possible that a custom search portlet is customized in the source but the dependencies do not exist in the target.

Also, a custom search portlet in the source may have been customized and then the dependency is removed from the portal and the custom search portlet's customizations are not updated. In this case when the custom search portlet is used for a search the missing reference is ignored. When the custom search portlet is re customized and the customizations saved the missing reference is removed.

On export, all the custom search portlets that have been selected for export are checked and any missing references are removed. The customizations are then included in the transport set.

On import, a pre-check will determine if any dependencies are missing in the target after import. Messages are written to the log, for each custom search portlet that has missing dependencies, the log will show the reference path of the custom search portlet and the missing dependencies and what will happen on import.

The page on which the custom search portlet resides will be flagged with a warning. On the actual import the custom search portlet customizations are modified to have the correct ID's of all the same dependencies in the target and the customizations are copied into the target.

Note: Search results saved using the Saved Searches portlet are not imported or exported. You should submit the same search in the new target and save the latest set of search results.

10.8.7 Migrating Your External Applications

Portal export/import does not migrate any data that is in the Single Sign-On schema, ORASSO. However, portal pages that are migrated may contain instances of the external applications portlet, which refers to external applications that are defined in the ORASSO schema, along with user credentials for these applications.

Pages may also contain portlets from providers that are defined to include an associated external application for automatically authenticating to an external application that the provider is integrated with. In these cases, the referenced external application needs to be migrated along with the provider information.

The external application information is treated as external dependencies by the portal export/import utility. See Section 10.4.1, "Creating Transport Sets" for more details on the types of objects. When migrating portal content that references external applications, the references are expected to be present on the target portal during the import. For this reason, you will need to migrate any external applications that may be referenced before completing your import into the target portal.

The portal export/import utility does not assume that the external application identifiers will be the same on the source portal and the target portal.

Note: The portal export/import utility matches external applications by checking that the external application in the target portal's SSO server has the same name as the external application defined on the source portal's SSO server.

This association by name also enables you to manually synchronize external application definitions between the source and the target portal's SSO servers.

10.8.7.1 User Populations

If the user population is different between the source and the target portal, you may not want to manually migrate the external application definitions and credentials using the ssomig utility, see Section 10.8.7.2, "The Export and Import SSO Utility".

If the user population is the same on the source and the target, then the credentials can be transferred. Pages must be migrated with security. If the export is done without security and without preferences, the external application portlets are still migrated and loose-wired, but without any of their customizations. See Table 10-10 for more details.

Table 10-10  Dataset Options

Dataset Options Criteria	Migration of External Application Portlets	Loose Integration of External Application	External Application Customizations
Without security and without preferences	Yes	Yes	No
With security and without preferences	Yes	Yes	Yes
With security and with preferences	Yes	Yes	Yes

10.8.7.2 The Export and Import SSO Utility

The utility ssomig (ssomig.bat in Windows) uses Perl, Oracle SQL*Plus, and the tools EXP and IMP to move data between two version 9.0.4 servers. The two operational modes, export and import, must be run separately.

For more information on the SSO Export/Import utility (ssomig), refer to the Oracle Application Server Single Sign-On Administrator's Guide.

10.8.8 Migrating Your Portal Across Databases

Oracle EXP and IMP utilities can be useful when deploying identical content across multiple OracleAS Portal instances.

Note: In the following steps, the ORACLE_HOME is meant to reference the database Oracle home and not the Oracle Application Server Oracle home. It is important that when running database scripts that the correct version is used from the proper Oracle home corresponding to the actual database instance in which portal is being imported.

The migration is a multi-step process that involves:

1. Listing the schemas to be exported. It is necessary to identify all of the schemas that need to be exported, including the portal schema, the portal "Public" schema, and any schemas used for Database Providers or Portlet Builder components. To list all the schemas run the following query from SQL*Plus as the Portal schema owner:

   SELECT USERNAME, DEFAULT_TABLESPACE, TEMPORARY_TABLESPACE FROM DBA_USERS
   WHERE USERNAME IN (user, user||'_PUBLIC', user||'_DEMO', user||'_APP')
   OR USERNAME IN (SELECT DISTINCT OWNER
   FROM WWAPP_APPLICATION$
   WHERE NAME != 'WWV_SYSTEM');
   
   

   Note: This will only list schemas that are directly related to Database Providers or Portlet Builder components registered in portal. If any of these schemas additionally reference objects in other schemas, then they should be added to the list of schemas to be exported.

2. Listing the tablespaces in the source database. To list the tablespaces used in the source database run the following query from SQL*Plus as the SYS user:

   SELECT DISTINCT TABLESPACE_NAME FROM DBA_SEGMENTS WHERE OWNER IN (<list of 
   schemas>)
   UNION 
   SELECT DISTINCT DEFAULT_TABLESPACE FROM DBA_USERS WHERE USERNAME IN (<list 
   of schemas>) 
   UNION 
   SELECT DISTINCT TEMPORARY_TABLESPACE FROM DBA_USERS WHERE USERNAME IN (<list 
   of schemas>)
   
   

3. Running the Oracle EXP utility.

   EXP \'sys/<password of sys user>@<Connect String> as sysdba\'  
   FILE=portal.dmp OWNER=<List of Schemas> LOG=portal.log 
   
   

   The export should terminate without any errors. If there are any ORA- 00942 errors reported in this step, run the following script from SQL*Plus as the SYS user:

   ORACLE_HOME/rdbms/admin/catexp.sql
   
   

   Note: The difference in syntax between Unix and NT platforms, you should omit the '\'. For example, 'sys/<password of sys user>@<Connect String> as sysdba.

4. Creating a backup of the target database. Backup the target database before proceeding to the next step.

5. Preparing the target database for import. Before importing the portal schemas into the target database, it is necessary to ensure that the necessary pre-requisite packages have been installed.

   Note: The target database must meet the same minimum requirements necessary as a database for an Oracle Application Server Metadata Repository.

   • PTLASST must be run in SYSOBJECTS mode.

   • Run ORACLE_HOME/rdbms/admin/catldap.sql.

   • Recompile all invalid objects by running ORACLE_HOME/rdbms/admin/utlrp.sql

   • Initialize the portal login trigger for import. Run as SYS

   • ORACLE_HOME/portal/admin/plsql/wwhost/insttrig.sql SYS

6. Creating or altering tablespaces in the target database. Check that the required tablespaces exist in the target database. The tablespaces in the target database must be the same as the source tablespaces.
   • Check that the list of tablespaces identified in Step 2 exists in the target database. To list all the tablespaces on the target, run the following script from SQL*Plus as the SYS user:

     SELECT TABLESPACE_NAME FROM DBA_TABLESPACES; 
     
     

   • To create a new tablespace, use the CREATE TABLESPACE or CREATE TEMPORARY TABLESPACE commands. For example:

     CREATE TABLESPACE <tablespace_name> 
     DATAFILE '<datafile_location>' SIZE 20M 
     DEFAULT STORAGE (INITIAL 1M NEXT 2M MINEXTENTS 2) AUTOEXTEND ON; 
     
     

     <datafile_location> is the file location for the dbf file. On UNIX, for example, the location may be: /u02/oracle/data/tbsa01.dbf.

   For any tablespaces that already exist in the target database, it is recommended that they be set to autoextend or they must be sized large enough to hold the imported portal schemas. The following script can be used to enable autoextend on all datafiles:

   SET DEFI OFF
   SPOOL DATAFILES.SQL
   SELECT 'ALTER DATABASE DATAFILE '''||FILE_NAME||''' AUTOEXTEND ON;' 
   FROM DBA_DATA_FILES ; 
   SPOOL OFF
   @DATAFILES.SQL 
   
   

7. Creating the portal schema. Change directories to ORACLE_HOME/portal/admin/plsql/wwv and run the following script from SQL*Plus as the SYS user.

   @wdbisys.sql <Portal Schema> <Portal Default Tablespace> <Portal Temporary 
   Tablespace> WDBISYS.LOG
   
   

   This creates the portal schema and grants all of the necessary privileges. Use the results of the query from Step 1 to find the names of the default and temporary tablespaces for the portal schema.

8. Creating the portal_public schema. Change directories to ORACLE_HOME/portal/admin/plsql/wws run the following script as the SYS user.

   @cruser.sql <Portal Schema> <Portal Default Tablespace> <Portal Temporary 
   Tablespace>
   
   

   This creates the PORTAL_PUBLIC schema.

9. Creating placeholders for the schemas. Check that the list of schemas that will be imported from Step 1. If the schemas already exist in the target database, then it is recommended that they be dropped. Before dropping any schemas, ensure that those schemas are not in use by other applications. To create a new users, use the following syntax:

   GRANT CONNECT, RESOURCE TO <user> IDENTIFIED BY <password>;
   
   

   A user must be created for each user in the list from Step 1. Use the ALTER USER command to adjust any user properties as necessary. For instance, the default and temporary tablespaces should be set to the ones specified by the results from the query in Step 1.

10. Running the Oracle IMP utility.

    IMP \'sys/<password of sys user>@<Connect String> as sysdba\' FROMUSER=<LIST 
    OF SCHEMAS> TOUSER=<LIST OF SCHEMAS> FILE=PORTAL.DMP LOG=PORTAL_IMP.LOG
    
    

    The following Import error can be ignored as it is expected:

    IMP-00041: Warning: object created with compilation warnings.
    
    

11. Compiling all the invalid objects. Compile all the invalid objects in all the imported schemas. Run the ORACLE_HOME/rdbms/admin/utlrp.sql as the SYS user.

12. Dropping the temporary login trigger. Change directories to ORACLE_HOME/portal/plsql/admin/wwhost and run the following script from SQL*Plus as the SYS user.

    @droptrig.sql.
    
    

13. Granting connect through portal. Perform the following commands from SQL*Plus as the portal user:

    SET HEAD OFF 
    SET LINES 4000 
    SPOOL DBUSERS.SQL 
    SELECT DISTINCT `ALTER USER '||DB_USER ||' GRANT CONNECT THROUGH '|| WWCTX_
    API.GET_PRODUCT_SCHEMA||';' 
    FROM WWSEC_PERSON$;
    SPOOL OFF 
    
    

    Run DBUSERS.SQL in the target portal instance to grant connect through privilege to database users associated with portal users.