Exporting and importing in OracleAS Portal

| Definition | Additional Information |

Definition

OracleAS Portal provides a set of export/import utilities which enable you to copy portal content between portal installations. Perhaps the most common use of these utilities is for copying or updating portal page groups and portlets between a development instance and a production instance of OracleAS Portal.

Other uses of export/import include the following:

• Export/import utilities can be used for consolidating multiple portal instances. Consolidation may be driven by a need to reduce the number of active instances or other business considerations. For example, a customer may wish to import their multiple OracleAS Portal installations to a single OracleAS Portal instance.
  
  
• Repeat installs of OracleAS Portal Objects. Export/import utilities can be useful when deploying identical content across multiple OracleAS Portal instances. In this case, the OracleAS Portal Objects (portlets, page groups, etc.), could be created in one instance, and propagated to multiple instances using the export/import utilities.

Note: Export and import functions only within the same release of OracleAS Portal. You cannot export and import between two different releases.

Before you begin

Before exporting and importing, make sure you've considered the following: ensure that your system meets the minimum system requirements. Also, plan to perform the export and import process during non-business hours, and to disable access to OracleAS Portal during the process.

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.

In addition, 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 OracleAS Portal instance.

Also, gather the following information:

• OracleAS Portal Schema Name
• OracleAS Portal Schema Password
• OracleAS Portal Connect String Information
• OracleAS Portal User Name
• OracleAS Portal User Password
• Company Name (used only for hosted portal installations) - leave blank in
  most cases.

Pre-Requisites Web and Database Providers

OracleAS Portal export import only migrates the registration information found in portal – no actual migration of the web or database providers happens. For this reason, it is important that the providers are available on the import portal instance in the same manner in which they are available in the export portal.

In the case of web providers, since this provider is identified by a url this could remain the same. For database providers, an additional step is necessary for successful migration of pages that reference the database provider’s portlets:

1. Database(s) used b schemay 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 above migration
2. Database schema(s) used by Database Providers whose portlets are in the pages marked for export
   • Use Oracle EXP/IMP utilities to migrate the database schema(s)
   • Ensure that the provider package is migrated correctly and valid – register the provider with the import portal with the same name as in the export portal.
3. If there are a handful of web providers that are referenced by the pages in the export portal, you can also register them ahead of time in the import portal with the same name as the export portal. A different URL for the development (source) and production (target) web providers can also be used. Pre-register the provider with the same name but pointing to the appropriate URL's from the source and target portal servers. This information would then be reused during import of the web provider registration information.

Exporting and Importing

The export and import process is a multi-step process that involves:

1. Creation of transport sets and extracting content to transport tables (both done via the User Interface)
2. Migration of the transport tables from one system (source) to another (target) using Oracle EXP/ IMP utilities (done via command line)
3. Followed by resolution and import of objects on target (done via UI).

Note: It is recommended that to limit any concurrency issues that one person be responsible for maintaining a transport set.

Export Process

The steps can be summarized as follows:

1. Mark objects for export (from the Navigator or search results -> bulk actions for page groups).

2. Choose Export Now, or select the Save for Later option which allows you to add more objects, amend the security options, rename the transport set and export later.

3. Check the log for errors and download the script file.

4. Run the script using -mode export as the option (additional options such as the schema name can also be used).

5. Note the name of the dump file created.

A transport set can be created by clicking the Export link found under Actions in the Navigator (Page Group tab, DB Provider tab). This action can also be accessed from the Bulk Action screen. This action is only visible to those users whose the privilege is described in the Notes section. Clicking the export link next to a particular object marks that object for export.

The export links are not available for all objects (for example, seeded page groups such as portlet repository, documentation, etc cannot be exported, the same is true for certain providers such as web providers, internal provider, provider group, etc.)

For page group objects, perform a search to select objects for export. Then use the bulk action of export on the results returned. This targets a set of objects for export. Then you can add them to the transport set using bulk actions by clicking the Export link in the bulk actions UI.

Two options are provided, either to create a new transport set for the selected object or to use an existing transport set.

The user can also select whether to export the access control lists associated with the objects in the transport set. For the Users/Groups which are part of the access control lists, choose whether to include their preferences. Also, choose whether to ignore any warnings which may occur while exporting an object. The Advanced Logging option will produce a detailed log of the export process.

Note: When providing a name for the transport set, make it 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.

Dependency Manager

New features in this release include the export/import Dependency Manager. It's purpose is to ensure that all the dependencies of objects in the transport set are correctly extracted.

The Dependency Manager marks each object as explicit, external, reference or child, based on how the object is extracted. This information is displayed in the manifest in order to provide a granular level of control over the import mode.

Note:

• In order to simplify the manifest, seeded types are not extracted. The suggested practice, would be to create custom types in the shared objects page group based on the existing seeded types. The Dependency Manager will then include these in the manifest.
• The import modes of a parent object must be cascaded to the child, therefore when there are two objects in a hierarchy both cannot exist as explicit objects and only one is displayed. For example,

Page A has a sub page, page B. Page B was selected for export first, followed by page A, therefore page B will no longer appear in the explicit objects section. The list of objects below is where a hierarchy can exist:

• Page Group - All the objects in the page group
• Page - Sub pages
• Category - Sub categories
• Perspective - Sub perspectives
• DB Provider - All the portlets

Explicitly Selected Objects

This section displays the list of objects, which were explicitly selected, from the Navigator or Bulk Actions for export.

Note: When a page contains a portlet from an external provider, the manifest will display the external provider as a dependency. The provider cannot be promoted and will therefore be reused (if present) on the target system.

Referenced Objects

This section displays the list of objects which are directly or indirectly referenced by the explicitly-selected objects. Without this information (if ignore warnings is not set to true) the import of the object may have problems.

For example, if a navigation page fails, then the imported page will not display the navigation page. If ignore warnings is set to true, then the referenced objects are replaced by defaults where possible i.e., use default style of page group for the page that has a style that fails, etc.

External Objects

This subsection displays the list of external objects. External objects ensure that the explicit objects perform on the target portal. For example, external-providers and database-schemas could be considered as external objects.

When the user selects Export Now, the transport set is finalized and the list of objects marked for export are copied to the transport tables for migration. These operations happen in the background.

Further additions of objects can be made by selecting the transport set for reuse. The option is only valid for transport sets with a status of 'Export Complete' or 'Export Failed'. Links are presented in the UI that allow the user to view the progress of the actions being performed or download Windows NT or UNIX command scripts that will be used in the migration.

To edit a transport set (to export security for example);

1. Navigate to the export/import portlet on the Administer tab.
2. Select the transport set from the export list of values.
3. Edit the preferences.

These two actions can extract the content immediately or save the changes for later export. Once a transport set has been finalized (i.e., Export Now is clicked), the next step is to migrate the contents of the transport set from the source to the target portal instance.

The migration step uses the Oracle EXP utility to create transport dump files. From the View Log and Download screen, choose the download script based on the operating system. Save the resulting file to the location where you want to run the export utility.

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

Once the scripts are saved (use a .csh or .cmd extension to identify the scripts), perform the migration step by running the script. Running the script without any parameters gives its usage. The example below assumes that the name of the script is myFirstExp.csh.

%myFirstExp.csh

Usage: myFirstExp.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>

Parameters	Description
-mode 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 (eg: ORACLE)
-c connect_string	TNS Connection Information to remote database
-d dump_file_name(s)	Names(s) of files for Oracle exp or imp utilities to write to or read from. If filename(s) are used, they must be separated by commas and enclosed in double-quotes   E.g.: "FILE1.DMP,FILE2.DMP"
-automatic_merge	Automatically merge contents of dump file on import

To run the export, specify -mode export as the option to the script:

%myFirstExp.csh -mode export

This prompts the user for information such as schema name (source), password, dump file name(s), etc. It also creates a dump file upon completion. The following parameters are for import mode use only:

• <-pu portal_username>

• <-pp portal_userpassword>

• <-company company_name>

• <-automatic_merge>

Note: The first time an export is performed, the entire page group or db provider needs to be exported and imported. This ensures all the necessary dependents are later available for individual export of page group or db provider objects. Also, while it is possible to import an individual db provider object onto a new db provider (one that is different from the source), the same is not true for page groups. Individual page group objects can only be imported into the same page group as the source.

Import Process

The steps can be summarized as follows:

1. Run the script using -mode import as the option (additional options such as schema name can also be used).

2. Select the transport set from the Administer Tab.

3. Import in the transport set manager for the selected transported set.

4. Check log for errors.

5. Go to the imported objects (via the Navigator for example). Verify the object does not have any errors and behaves the same as the source.

To import an object, the contents of the transport set must first be imported to the target system. This is done by calling the same script (used in export) with -mode set to import. i.e.:

%myFirstExp.csh -mode import

This prompts the user for information such as schema name (target), password, etc. After validating the user information, the contents of the dump files are imported and the transport set made available for merging on the target portal system.

Once the import is complete the transport set can be accessed from the UI. To do this, go to the Administer tab (Builder) and click the icon next to import a transport set, select the imported transport set, and click on Import. The import manager is displayed. Select the options for import (such as overwrite or reuse) and click on Import Now. This resolves and imports the exported objects (in the background) to make sure there are no conflicts.

Clicking Save for Later saves changes to the transport set for later resolution and import (i.e., none of the actions described above are executed.)

Note: If the ignore warnings option is selected then any warnings generated are ignored and the import proceeds. However if the ignore warnings option is not selected and warnings exist then the import will fail.

Notes

Single Sign On (SSO) Server

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

Exporting/Importing Page URLs Correctly

By default, generated page URLs contain installation specific ID numbers that change when the object is exported. This causes broken links when pages are imported into a different site. 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=portalr2

The same page has this direct access URL:

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

This direct access URL still works on an imported page, providing the name of the page (e.g. HRBENEFITS) and the names of its parent pages (e.g. HRHOME, HRPAGEGROUP) do not change. 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. Therefore, to ensure that links do not 'break' when pages are imported into a different site, always use Page Link item types or direct access URLs when creating links to pages.

For more information, refer to 'Direct Access URLs' and 'Page Links' in the OracleAS Portal online help.

The following object types can be exported from OracleAS Portal:

Page Groups

• Page Group - Exports the entire page group and the shared objects it references. This should always be done prior to exporting any pages or any other objects from that page group.

• Page - Exports the page and the page type, template, and style it references along with content (item and portlets).

• Category - Exports the category and its sub-categories and the page and style they reference.

• Perspective - Exports the perspective and its sub-perspectives and the page and style they reference.

• Template - Exports the template and the style it references and any content on the template.

• Navigation page - Exports the navigation page and the style it references and any links on the navigation page.

• Style - Exports the style.

• Page type - Exports the page type and the attributes it references.

• Item type - Exports the item type and the attributes it references.

• Attribute - Exports the attribute.

DB Providers

• 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.

Web and Other Providers

Only the registration information stored about the portlet providers (web and database) in OracleAS Portal is exported. These providers (seen in the Navigator) cannot be marked for export; their registration information is implicitly exported whenever pages containing portlets from these providers are exported. For this reason, it is important that the web providers and (more importantly) database provider are available to the portal system where the import will occur.

Under certain circumstances (see the examples below) it would beneficial if the web providers were registered and tested independently (i.e., can the provider's portlets be seen, does registering a portlet from the provider in a test page fail, etc.) before performing any migration work.

Example Conditions

• There are only a few web providers set up in the development instance

• The web providers need to point to a different URL from the one specified in the development instance

• It uses proxies in production instance whereas no proxies are required in development instance

Note: That while the providers could point to different URL's, the providers themselves must be the same - they must have the same "internal" name, and they must have the same portlets (i.e., the id of the portlet is the same).

Example, if SAMPLE_WEB_PROVIDER is the name on the export portal, use the same name when manually registering the provider on the import portal.

For database providers, make sure the schema referenced in the registration information (in the export portal) is exported and imported first – if the same schema name cannot be used for the database provider in the import portal, create the schema with all the objects required for it to be a database provider, manually register a database provider with the same name as the export portal pointing to this schema before using portal export import.

If for some reason a web or database provider is down, then the import will fail for the portlets belonging to the provider.

The provider metadata information for Page Group and DB Providers are exported along with the page group and db provider objects automatically.

Additional Notes

• To allow for secured control over export/import of shared objects there are now two privileges defined at the infrastructure level .
• Any Transport Set - Manage is the privilege which allows the user 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 having Any Transport Set - Execute privilege can only export/import portal objects excluding shared objects. This privilege is granted to the PORTAL_ADMINISTRATORS group by default during portal installation process.
  
  

  User Privilege	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

• The transport set portlet must reside on a page that the user has access to, unless the user already has access to the Administer tab. Without this, the user will be unable to view the transport set portlet and cannot perform export with security or import.
• For additional security information on DBA groups refer to the Oracle Application Server Portal Security Guide.

Additional Information

On Portal Center:

For more information go to the documentation section of Portal Center.

Copyright © 2005, Oracle. All rights reserved.