14 Exporting and Importing Data

This chapter explains how to move data between two or more single sign-on servers. Various conditions dictate whether you export and import data. Perhaps you want to stage data on a test server before transferring it to a production server. Or maybe you want to consolidate multiple servers as one server. Or you may simply want to back up an existing server.

The chapter contains the following topics:

What's Exported and Imported?
Export and Import Script: Syntax and Parameters
Exporting Data from One Server to Another
Consolidating Multiple Servers
Verifying That Export and Import Succeeded
Error Messages

14.1 What's Exported and Imported?

The export and import script, ssomig, moves three categories of data:

Definitions and user data for external applications
Registration URLs and tokens for partner applications
Connection information used by OracleAS Discoverer to access various data sources

If you need to move user accounts, use LDAP command-line scripts such as ldapsearch to extract data from the source directory. Use ldapadd or ldapmodify to load data into the target directory. To learn how to use these scripts, see the syntax chapter in Oracle Identity Management Application Developer's Guide.

14.2 Export and Import Script: Syntax and Parameters

The ssomig script uses Perl, Oracle SQL*Plus, and the database export and import tools exp and imp to move data between two release 10.1.2 servers. You must run the export and import modes separately. You can find ssomig at ORACLE_HOME/sso/bin.

14.2.1 Script Syntax

Use this syntax to run ssomig:

ssomig -s sso_schema
       -p sso_password
       -c net_service_name
       -log_d log_dir
       {
         -export [-prompt]
                 [-noextappusrs]

         -import {-merge | -overwrite}
                 [-discoforce | -disconoforce]
       }
        [-log_f log_file]
        [-d dump_file_name]
        [-help]

14.2.2 Script Parameters

Table 14-1 defines the parameters passed to ssomig.

Table 14-1 Parameters Passed to ssomig

Parameter	Description	Additional Information
-s	Database schema name for OracleAS Single Sign-On.	The default is `ORASSO`.
-p	Database schema password for OracleAS Single Sign-On.	The password is randomized during installation of the OracleAS infrastructure. To obtain the password, see Appendix B.
-c	Net service name for the OracleAS Single Sign-On database.	-
-log_d	Name of the log directory.	This directory must be writable. The log file, the export configuration file, and the dump file are written here. Use the absolute path for the directory when running the script. The default is `ORACLE_HOME/sso/log`.
-export	Extracts data from single sign-on tables and places it into a dump file.	-
-prompt	Exports partner and external applications selectively.	Use with `export`.
-noextappusrs	Specifies that external application users not be exported.	Use with `export`. Choose this mode if you are moving data from a staged server to a production server and do not want to move test users.
-import	Extracts data from a dump file and places it into single sign-on tables.	-
-merge	Imports only partner and external applications that do not already exist in the target server.	Choose this mode after you have imported the first of multiple servers. Use with `import`.
-overwrite	Imports all partner and external applications, regardless of whether some already exist in the target server.	Choose this mode when migrating the first of multiple servers. Use with `import`.
-discoforce	Imports OracleAS Discoverer information, replacing Discoverer information in the target server.	-
-disconoforce	Imports OracleAS Discoverer information only if the target server contains no Discoverer data.	-
-log_f	Log file name.	This file provides export results and the runtime status of tools such as SQL*Plus, `exp`, and `imp`. The default file name is `ssomig.log`.
-d	Dump file name.	The default is `ssomig.dmp`.
-help	Describes the syntax and parameters for `ssomig`.	-

14.3 Exporting Data from One Server to Another

The scenarios under which the export and import script is run fall into two categories: export from a single server and export from multiple servers. The choice of one category or the other dictates whether the script is run in overwrite mode or merge mode. It also dictates whether partner and external applications are exported selectively. This section examines single-server export and import. For multiple-server export and import, see "Consolidating Multiple Servers".

This section contains the following topics:

Export and Import Scenarios and Script Examples
Running the Script

14.3.1 Export and Import Scenarios and Script Examples

What follows are scenarios that you are likely to encounter when moving data from one single sign-on server to another. The command appropriate for each scenario is provided.

Note:

The following examples are described with UNIX in mind, but they work with Windows as well. Simply substitute a backslash for the forward slash in the log directory path.

14.3.1.1 Export Scenarios

Export all partner and external applications. Export OracleAS Discoverer data entirely. This command is appropriate when you want to back up a server:
```
ssomig -export -s orasso -p password -c net_service_name -log_d /tmp
```
Selectively export partner and external applications. Export OracleAS Discoverer data entirely. Run this command when you want to move staged data to a production server:
```
ssomig -export -prompt -s orasso -p password -c net_service_name -log_d /tmp
```
Selectively export partner applications. Selectively export definitions for external applications. Do not export user data for external applications. Export OracleAS Discoverer data entirely. Run this command when you want to move staged data to a production server, but do not want to move external application information for test users:
```
ssomig -export -prompt -noextappusrs -s orasso -p password -c net_service_name -log_d /tmp
```

14.3.1.2 Import Scenarios

Import partner and external applications. Overwrite only entries that are the same as the entries that you are importing. Exclude OracleAS Discoverer data. This command is useful if you are not deploying Discoverer:
```
ssomig -import -overwrite -s orasso -p password -c net_service_name -log_d /tmp
```
Import partner and external applications and OracleAS Discoverer data. Overwrite all entries, regardless of whether they are the same as the entries you are importing. Run this command if you need to refresh data in the target server:
```
ssomig -import -overwrite -s orasso -p password -c net_service_name -log_d /tmp -discoforce
```
Import partner and external applications. Overwrite all entries, regardless of whether they are the same as the entries you are importing. Import OracleAS Discoverer information only if none is present in the target server:
```
ssomig -import -overwrite -s orasso -p password -c net_service_name -log_d /tmp -disconoforce
```

14.3.2 Running the Script

To export data:

Log in to the computer that you are exporting from.
Set the Oracle home environment variable, ORACLE_HOME, to point to the Oracle home of the release 10.1.2 single sign-on server.

Run the script. (See "Export and Import Scenarios and Script Examples".)

This action creates the dump file ssomig.dmp, the log file ssoconf.log, and the single sign-on configuration file ssoconf.log. All three are created in the log directory.

Note:

When you run ssomig in export mode with the prompt option, the script asks you to identify applications that you do not want to export. At the same time, it asks you to press any key when you are finished making your selections. Press the Return or Enter key instead. The script ignores other keys.

To import data:

Log in to the computer that you are importing data to.
Set the environment variable ORACLE_HOME to point to the Oracle home for the release 10.1.2 single sign-on server.
Make sure that the log_d parameter points to the log directory where the log files for export are located. The script must reference the files ssomig.dmp and ssoconf.log when it runs in import mode. You may have to copy these files from the computer on which the export server is located.
Run the script, choosing import mode. (See "Export and Import Scenarios and Script Examples").

14.4 Verifying That Export and Import Succeeded

After completing export and import operations, open ssomig.log and check for errors. To interpret the messages that you encounter in the file, see "Error Messages".

14.5 Consolidating Multiple Servers

This scenario is applicable if several departments in your enterprise maintain departmental single sign-on servers. You may want to consolidate these servers into a unified identity management service.

Use the following approach to export and import multiple servers:

Export data from all of the servers involved except the target server. To learn how to run the script, see "Exporting Data from One Server to Another".
Run the script in import mode, overwrite option, for the first single sign-on server that you migrate. For help, see the section "Import Scenarios".
For subsequent servers, run the script in merge mode. Import partner and external applications to the target server, importing the servers one at a time:
```
ssomig -import -merge -s orasso -p password -c net_service_name -log_d /tmp -d ssomig.dmp
```
This command merges only partner and external applications.

Note:
when importing multiple servers, you can run the script in overwrite mode to cancel the result of a previous run.

14.6 Error Messages

Any one of the following messages may appear during the course of export and import. Table 14-2 defines these messages to aid problem resolution.

Table 14-2 Error Codes for Export and Import

Error	Cause	Action
SSO-80000: The operation was unsuccessful.	Import or export or both failed because of one or more errors.	Determine the error from the log file or from screen output.
SSO-80001: The environment variable ORACLE_HOME is not set.	The variable has not been set for the release 10.1.2 Oracle home.	Follow the instructions in "Running the Script".
SSO-80002: Invalid ORACLE_HOME specified.	The directory represented by `ORACLE_HOME` does not exist or required scripts under it are unavailable.	Set the Oracle home to a valid Oracle instance.
SSO-80004: Invalid log directory. String is not writable.	You lack write permission for the log directory specified.	Specify a directory for which you have write permission.
SSO-80005: Invalid log directory. String is not directory.	The log directory specified does not exist.	Specify a valid directory.
SSO-80008: Duplicate option string.	The command-line parameter string is repeated or both options that compose a set of complementary options are provided.	Avoid repeating the command-line parameter string. Avoid including both options that compose a set of complementary options—`export` and `import`, for instance.
SSO-80009: Mandatory parameter missing: string.	A mandatory command-line parameter string is missing	Specify the parameter string, including any relevant values.
SSO-80010: Invalid SSO Server version detected.	The script does not support the version of the source or destination server.	Make sure that you are using release 10.1.2 servers to perform export and import operations.
SSO-80011: Invalid option string.	The parameter string is not a recognized command-line parameter	Use the option `help` to obtain a list of valid parameters.
SSO-80012: Invalid SSO schema information.	The schema name, password, or net service name is invalid.	Reenter the command.
SSO-80014: Invalid log file. String is not writable.	You lack write permission for the log file that you specified.	Specify a log file for which you have write permission.
SSO-80015: Failed to drop temporary tables.	An expected script file was missing, or an operating system error or database error was encountered.	View the log files for details. Correct any errors that you find.
SSO-80050: Data export unsuccessful.	The export operation failed because of one or more errors.	Determine the error from the log file or from screen output.
SSO-80051: Copying data into the temporary tables failed.	A script file is missing or an operating system error or database error was encountered.	View the log file for details. Correct errors that you find.
SSO-80052: Invalid dump file. String not writable.	You lack write permission for the dump file specified.	Specify a dump file for which you have write permission.
SSO-80076: Cannot determine NLS information.	A script file is missing or an operating system error or database error was encountered.	View the log file for details. Correct errors that you find.
SSO-80077: The file string does not exist.	The file string has been deleted or renamed externally.	Ensure that the file string is not touched externally during execution of the script.
SSO-80078: Creating the table that represents the config file failed.	A script file is missing or an operating system error or database error was encountered.	View the log file for details. Correct errors that you find.
SSO-80100: Data import unsuccessful.	The import operation failed because of one or more errors.	Determine the error from the log file or from screen output. Correct errors that you find.
SSO-80101: Cannot read the import dump file: string.	You lack read permission for the dump file string.	Obtain read permission for the specified dump file.
SSO-80102: The dump file string is of size zero.	An error occurred during export.	View the log file. Correct errors that you find.
SSO-80103: Config file not found: string.	This error appears if required configuration files such as dump and log are missing during import.	Ensure that the configuration files are present in the log directory.
SSO-80104: Corrupted or invalid config file.	The configuration file has been altered.	Ensure that the configuration file is not altered when transferred from the source to the destination.
SSO-80150: Package loading into the SSO schema failed.	A script file is missing or an operating system error or database error was encountered.	View the log file for details. Correct errors that you find .