Oracle9iAS Portal Developer Kit
A Primer on Portal Export / Import

Oracle9iAS Portal includes export-import tools to migrate page group and database provider objects from one instance to another. Using export-import functionality, users can develop content on a development server, push the content through QA for validation and finally stage the content on production servers.

Important! Portal supports export and import between Portal instances of the same release only; you can not export and import between two different releases of Portal.

PRE-REQUISITES

Before exporting or importing, 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 Portal during the export-import process. The export-import process sets up background processes - make sure the database parameter JOB_QUEUE_PROCESS is set to a value greater than 0.

You must have the following privileges to export and import in Portal:

- Portal Admin privilege
- Portal Transport Set Manage Privilege

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 Portal instance. The following information is needed during this process:

· Portal Schema name

· Portal Schema password

· Portal Connect String information

· Portal User name

· Portal User password

· Company name (if applicable)

Export/Import Process

Portal export-import is a multi-step process that involves the following steps:

- Step 1: Creation of transport sets and marking of objects for export
- Step 2: Export to dump file
- Step 3: Import of dump file
- Step 4: Resolution and merge of objects into target

Step 1: Creation of transport sets and marking of objects for export

A transport set can be created by clicking the Export link found under Actions in 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 mentioned above in the pre-requisites section. Clicking the export link next to a particular object marks that object for export. Two options are provided at this time, either to create a new transport set for the selected object or to use an existing transport set. The latter is useful when a handful of objects need to be migrated (e.g. a database provider or a page group which contains pages with portlets from the database provider).

The following portal object types can be marked for export via the UI (through navigator or performing a search/ bulk action):

Page Group Objects:

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

Portal DB Providers

o Portal DB Provider - Exports the entire portal db provider and the shared components it references.

o Form - Exports the form and the shared components they reference.

o Report - Exports the report and the shared components they reference.

o Chart - Exports the chart and the shared components they reference.

o Calendar - Exports the calendar and the shared components they reference.

o Dynamic Page - Exports the dynamic page and the shared components they reference.

o XML Component - Exports the XML component and the shared components they reference.

o Hierarchy - Exports the hierarchy and the shared components they reference.

o Menu - Exports the menu and the shared components they reference.

o URL - Exports the URL and the shared components they reference.

o Frame Driver - Exports the frame driver and the shared components they reference.

o Link - Exports the link and the shared components they reference.

o List of Values - Exports the list of values and the shared components they reference.

o Data Component - Exports the data component and the shared components they reference.

Portlet Providers

· Only the metadata stored about the portlet providers (web and db) in Portal is exported. These providers cannot be marked for export; they are implicitly exported whenever pages containing portlets from these providers are exported.

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

Once the objects are selected for export and added to the transport set, the user has the choice to either finalize the transport set for immediate processing or save the transport set. When the transport set is finalized, a background process is initiated that copies the objects to a temporary location (transport tables) and makes them available for export via command line. Additionally, the background process also determines the dependencies for the selected objects (style required by a page for proper display, etc.) and marks and copies those objects as well to the temporary location for export. When the transport set is saved, it can be used to add additional objects (add to existing transport set in the export wizard) and finalized at a later time. This option also allows the user to choose export of security privileges for the objects marked for export by editing the transport set via the transport set portlet found in the administration tab of design-time page (builder page).

The user is presented a Download Scripts and View Log screen when the transport set is finalized by clicking the Export Now button. From here, the user can view the progress of the data extraction and download the scripts necessary for performing the next step.

Step 2: Export to dump file

Save the downloadable script from the Download Scripts and View Log screen for the operating system in use. On some systems, the downloaded UNIX script may require setting the execute permission correctly before attempting to run it. Once the scripts are saved (give a .csh or .cmd extension to identify the scripts easily), the extraction step can be performed by running the script in export mode. Running the script without any parameters gives its usage (example below assumes the user gave myFirstExp.csh as the name of the script):

> >     solaris::6>myFirstExp.csh

> >     Usage: opeiasst.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> <-check_mode>

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

> >                                NONE for no company

> >        -c connect_string       TNS Connection Information to remote database

> >                                (Mandatory)

> >        -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 need to 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

> >        -overwrite_mode         Overwrite existing objects with imported

> >                                objects

> >        -ignore_warnings        Ignore warnings raised during import

> >        -check_mode             Perform a run of import and display potential

> >                                errors - do not save the import

> >     NOTE : Replace the name of the script mentioned in the usage

> >            with the name with which the script was saved.

> >            For eg:- if the script was downloaded as myFirstExp.csh,

> >            then the command to run would be:

> >     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> <-check_mode>

To perform the extract, run the script in -mode export, see example below:

    solaris::7>myFirstExp.csh -mode export

This will prompt the user for additional information such as schema name (source), password, dump file name(s), etc and create 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> <-overwrite_mode> <-ignore_warnings> <-check_mode>

Note: The first time an export is performed, the entire page group or db provider needs to be exported and imported. This will ensure 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.

The process of this step can be summarized into following tasks:

- Marking objects for export (from Navigator for page groups and database providers or search results/bulk actions for page groups)
- Clicking on Export Now (During creation phase if security export is not required or during edit phase if security export is required)
- Checking log for errors and downloading the script file
- Running the myFisrtExp script in export mode and saving the contents of the dump file.

Step 3: Import from dump file

To import an object, the contents of the transport set needs to be first imported on to the target portal system. This is done by calling the same script used during export phase in import mode.

    %myFirstExp.csh -mode import

This will prompt the user for additional information such as schema name (target), pasword, dump file, portal username, 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.

Step 4:Resolution and merge

A transport set that is available for import can be accessed from the administration tab of design-time pages (builder page) in the transport set portlet. Once the transport set is selected and Import button clicked, the user is taken to a import manager that offers several options for the import:

- Overwrite existing objects with imported objects - this option determines if the objects that already exist in the target portal system will be reused or overwritten with changes from source
- Ignore warnings during import - this options determines whether to ignore warnings that may arise during import and proceed with the rest of the import
- Check only - this option is used in conjunction with the Overwrite existing objects with imported objects and a log is displayed at the end; no changes are applied to the target portal system when this option is selected

After selecting the options that best suits the needs, the Import Now button is clicked. This action submits a background process that resolves the objects found in the transport set and merges them on to the target portal system. A View Log screen is displayed from where the progress made during import can be monitored.

Note: It is a good idea to use check only at the beginning of the import to test and make sure the actions performed (overwrite existing objects, reuse existing objects, etc) have the desirous effect. The next step would be then to run the import again in non-check mode and merge the content.

Clicking OK saves changes to the transport set for later resolution and merge (i.e. none of the actions described above are executed).

The process of this step ca n be summarized into following tasks:

- Running the myFirstExp script in import mode and importing the contents of the dump file into target portal
- Clicking the Import (found in transport set portlet under administration tab in portal design-time page)
- Selecting the options for import and clicking Import Now
- Checking the log and making sure there are no errors; verifying that the imported objects have no errors

Note: The search portlet (which includes categories, perspectives, basic and advanced searches among others) gets reset during import. Recent objects and favorites portlets that are placed in the exported page display only the recent objects and favorites of the target. If the security was not marked for export, then the user that performed the import operations is granted manage privilege on the objects.

Additional Notes:

Login server export is handled using scripts located in the wwu directory which exists under the directory in which the Portal is installed. See example below for the usage of login server export/ import scripts:

Example

From the command line on UNIX, enter the following command to run the Single Sign-On export data script:

    ssoexp.csh [-e <export name>] [-s <sso_schema>] [-p <sso_password>] [-d <dump_file_name>] [-c <connect_string>]

From the command line on DOS, the command to run Single Sign-On export would look like:

    ssoexp.cmd [-e <export name>] [-s <sso_schema>] [-p <sso_password>] [-d <dump_file_name>] [-c <connect_string>]

From the command line on UNIX, enter the following command to run the Single Sign-On import data script:

    ssoimp.csh [-e <export name>] [-s <sso_schema>] [-p <sso_password>] [-m reuse] [-d <dump_file_name>] [-c <connect_string>]

From the command line on DOS, the command to run Single Sign-On import would look like:

    ssoimp.cmd [-e <export name>] [-s <sso_schema>] [-p <sso_password>] [-m reuse] [-d <dump_file_name>] [-c <connect_string>]

Revision History

- April 4, 2002