4 Import Export Tool

This chapter describes the features of the Import Export tool and how to use it to import items into and export items from the Oracle Enterprise Repository.

This chapter contains the following topics:

• Section 4.1, "Overview"

• Section 4.2, "Using the Import/Export Tool"

• Section 4.3, "Starting the Import/Export Tool"

• Section 4.4, "Export Items from Oracle Enterprise Repository"

• Section 4.5, "Importing Items into Oracle Enterprise Repository"

4.1 Overview

The Oracle Enterprise Repository Import/Export Tool is designed to allow the interchange of assets and related metadata between instances of Oracle Enterprise Repository.

Archives must be completely self-contained. That is, all dependent data required to fully describe all exported items will also be exported. The dependencies are as follows:

• Assets, Compliance Templates, and Policies rely on Types

• Asset Types, Compliance Template Types, and Policy Types rely on Categorization Types and Relationship Types

For example, when exporting a single Asset, the resultant archive will contain that Asset, its associated Asset Type, and any Categorization Types and Relationship Types on which that Asset Type depends. When importing, all data contained within the archive will be imported into the destination instance of Oracle Enterprise Repository. Conflicts resulting from the existence of items with the same name are resolved in the following manner:

• Assets, Compliance Templates, Policies, and their respective Types must have unique names within the system. When an imported item has the same name as an item already in the destination Oracle Enterprise Repository instance, "v2" will be appended to the name of the new (imported) item. Each iteration of this occurrence will result in a new version of the item: "v3," "v4," and so on. If the name of an imported item is already appended with a 'Vn" designation, "v2" will be further appended to that name.

• Categorization Types merge data in the event of a destination Categorization Type of the same name. Categorizations in the source archive that are not present on the destination system will be added to the existing (destination) Categorization Type.

• Source and destination Relationship Types sharing the same name and type are ignored; existing descriptive text is retained on the destination system. When source and destination Relationship Types share the same name, but are of different types, the name of the source Relationship type is appended with "v2," as described above, upon import to the destination system.

Note: If your instance of Oracle Enterprise Repository is or will be configured to be secured by Siteminder, you will need to configure the policy server to ignore (or unprotect) the following URL to allow the Import/Export tool to function properly http://appserver.example.com/oer/services/

4.2 Using the Import/Export Tool

This section describes how you can use the Import/Export tool to import or export objects into or from Oracle Enterprise Repository. This section contains the following topics:

• Section 4.2.1, "Overview"

• Section 4.2.2, "The parameter.properties File"

• Section 4.2.3, "The Default Import Behavior"

4.2.1 Overview

The Import/Export tool is available from within Oracle Enterprise Repository in the Admin tab, Import Export page. The Oracle Enterprise Repository user is required to have the Admin role specified by the system setting "Admin Role" (enterprise.security.roletype.admin).

The Import/Export tool is a Java WebStart program that downloads and launches when invoked.

The Export operation allows you to search for objects in Oracle Enterprise Repository to export. You can search for Asset Types, Assets, Categorization Types, and Relationship Types. The result of the Export operation is a .zip file with the searched for objects and all dependencies of that object. By default, no parameter.properties file is contained within the resulting .zip file.

The Import operation takes a .zip file that was exported by the Import/Export tool and load the contained items into Oracle Enterprise Repository. The behavior for the Import will be determined by META-INF/parameter.properties or a series of default actions.

Oracle Enterprise Repository Administrators who need to move data between different instances of Oracle Enterprise Repository need to use the Import/Export tool or the Oracle Enterprise Repository OpenAPI. When the Import/Export tool choice is utilized, a parameter.properties file should be added to the .zip bundle produced by the Export operation prior to performing the Import operation.

4.2.2 The parameter.properties File

Each import bundle contains a /META-INF directory. Optionally, this directory can contain a parameter.properties file that controls how the Import/Export tool behaves when the bundle is imported.

4.2.2.1 Supported Parameters in the parameter.properties File

The supported parameters in the properties file are listed with the legal values for the parameter:

PreserveUUIDs

• Used by: Asset

• Description: This parameter retains the UUIDs of assets in the bundle rather than randomly generating new UUIDs

• Values:

  • true - UUIDs on newly created assets are UUID specified in the import bundle

  • false - UUIDs on newly created assets are randomly generated by Oracle Enterprise Repository

Standard.saver.assettype.props.duplicate.matching

• Used by: Asset Type

• Description: This parameter specifies how the import tool identifies that an asset type in the bundle is a duplicate of something that already exists in Oracle Enterprise Repository.

• Values:

  • UUID - A duplicate is determined if the UUID of the asset type specified in the import bundle matches the UUID of an asset type in Oracle Enterprise Repository.

  • Name - A duplicate is determined if the Name of the asset type specified in the import bundle matches the Name of an asset type in Oracle Enterprise Repository.

Standard.saver.assettype.props.duplicate.handling

• Used by: Asset Type

• Description: This parameter specifies how the import tool handles asset types in the bundle that are identified to be Duplicates of asset types in Oracle Enterprise Repository.

• Values:

  • Create New Version - Create a new asset type with the UUID and archetype from the import bundle, but a name which is versioned with a suffix of a "V" and a number (for example, Service V2). The asset type has a new UUID.

  • Ignore - Ignore the duplicate asset type from the bundle. Do not import the asset type and do not modify the asset type in Oracle Enterprise Repository.

  • Merge - Merge the asset type in Oracle Enterprise Repository with the duplicate asset type from the bundle. The Merge operation does not modify any of the elements of the asset type in Oracle Enterprise Repository. The operation is additive, appending elements in the asset type from the bundle to the asset type in Oracle Enterprise Repository. Matching of the elements is by the XML Mapping of the element. The rules are:

    • If the element's XML Mapping exists, then ignore the element.

    • If the element's XML Mapping does not exist, then add it. The element is added by first locating the element's tab, and then creating the tab if it does not exist. The element is then added to the end of the tab.

  • Overwrite - Replace the asset type in Oracle Enterprise Repository with the duplicate asset type from the bundle. The assets of the asset type in Oracle Enterprise Repository is not modified, although the display of these assets is affected.

Standard.saver.relationshiptype.props.duplicate.handling

• Used by: Relationship Type

• Description: This parameter specifies how the import tool handles relationship types in the bundle that are identified to be Duplicates of relationship types in Oracle Enterprise Repository. Duplicate relationship types are always matched by the Name and Direction characteristics of the relationship type.

• Values:

  • Ignore - Ignore the duplicate relationship type from the bundle. Create any asset relationships that use this relationship type and do not already exist in Oracle Enterprise Repository.

  • Overwrite - Replace the relationship type in Oracle Enterprise Repository with the duplicate relationship type from the bundle. This will overwrite all information for the relationship type. This will also create any asset relationships that use this relationship type and do not already exist in Oracle Enterprise Repository.

Standard.saver.metadata.props.duplicate.handling

• Used by: CMF Metadata

• Description: This parameter specifies how the import tool handles blocks of CMF Metadata in the bundle that are identified to be Duplicates of CMF Metadata in Oracle Enterprise Repository. Duplicate CMF Metadata is always matched by the UUID of the metadata.

• Values:

  • Ignore - Ignore the duplicate CMF Metadata from the bundle.

  • Overwrite - Replace the CMF Metadata in Oracle Enterprise Repository with the duplicate CMF Metadata from the bundle. This will overwrite all information for the CMF Metadata.

Standard.saver.metadata.props.duplicate.handling

• Used by: CMF Metadata Entry Types

• Description: This parameter specifies how the import tool handles CMF Metadata Entry Types in the bundle that are identified to be Duplicates of CMF Metadata Entry Types in Oracle Enterprise Repository. Duplicate CMF Metadata Entry Types are always matched by the Name of the metadata entry type.

• Values:

  • Ignore - Ignore the duplicate CMF Metadata Type from the bundle.

  • Overwrite - Replace the CMF Metadata Entry Type in Oracle Enterprise Repository with the duplicate CMF Metadata Entry Type from the bundle. This will overwrite all information for the CMF Metadata Entry Type.

4.2.2.2 Sample parameter.properties File

A sample parameter.properties file with all options included is as follows:

##Name: parameter.properties
##Location: import_bundle.zip/META_INF/
##Legend:

## a double ## indicates a comment
## a single # indicates a command which can be used in an import bundle
## the text between []'s is the set of valid values for the parameter with comma
 separating individual values
## for assets:
## This parameter will retain the UUIDs of assets in the bundle rather than
 randomly generating new UUIDs

#PreserveUUIDs=[true,false]
## for assettypes:
#Standard.saver.assettype.props.duplicate.handling=[Create New Version, Ignore,
 Merge, Overwrite]

#Standard.saver.assettype.props.duplicate.matching=[UUID, Name]
## for relationship types:
#Standard.saver.relationshiptype.props.duplicate.handling=[Ignore, Overwrite]
## For CMF metadata

#Standard.saver.metadata.props.duplicate.handling=[Ignore, Overwrite]
## For CMF metadata entry types

#Standard.saver.metadataentrytype.props.duplicate.handling=[Ignore, Overwrite]
## for categorization types:
## no properties

## for acceptable value lists:
## no properties

4.2.3 The Default Import Behavior

If the parameter.properties file does not exist in a .zip bundle, the default behavior on Import is as follows:

Asset Type

• An asset already exists, if an asset with the same name and version is in Oracle Enterprise Repository.

• Assets, which already exist, are then evaluated on the UUID.

  • Assets, which have the same name, version and UUID are ignored.

  • Assets, which have the same name and version, but a different UUID yield a new asset with a random UUID, same version, but a name that is versioned with a suffix of a "V" and a number (for example, Service Asset V2).

• An asset which does not already exist is created with the name and version specified in the import bundle. The UUID is randomly generated.

• When both assets in a relationship are included in the import bundle, the relationships are created.

Acceptable Value List

• An acceptable value list already exists if an acceptable value list with the same name is in Oracle Enterprise Repository.

• Acceptable Value lists, which already exist, are merged. The values, which appear in the import bundle, but not in Oracle Enterprise Repository are added to Oracle Enterprise Repository. The values in Oracle Enterprise Repository are not modified.

• An acceptable value list, which does not already exist, is created with the same name and contents specified in the import bundle.

Categorization Type

• A categorization type already exists if a categorization type with the same name is in Oracle Enterprise Repository.

• Categorization Types, which already exist, are merged. Categorization items, which appear in the import bundle, but not in Oracle Enterprise Repository are added to Oracle Enterprise Repository. Categorization items in Oracle Enterprise Repository are not modified.

• A categorization type, which does not already exist, is created with the same name and contents specified in the import bundle.

Relationship Type

• A relationship type already exists if a relationship type with the same name is in Oracle Enterprise Repository.

• A relationship type, already exists if a relationship type with the same name, is in Oracle Enterprise Repository.

  • Relationship Types, which have the same name and direction, are ignored.

  • Relationship Types, which have the same name and a different direction, yield a new relationship type with the bundle specified direction and a name that is versioned with a suffix of a "V" and a number.

• A relationship type, which does not already exist, is created with the same name and direction specified in the import bundle.

Metadata Entries

• A metadata entry already exists if a metadata entry with the same UUID is in Oracle Enterprise Repository.

• Metadata Entries, which already exist in Oracle Enterprise Repository, are overwritten by the Metadata Entry in the Import Bundle.

• A Metadata Entry, which does not already exist, is created with the same UUID specified in the import bundle.

Metadata Entry Type

• A metadata entry type already exists if a metadata entry type with the same UUID is in Oracle Enterprise Repository.

• Metadata Entry Types, which already exist in Oracle Enterprise Repository, are overwritten by the Metadata Entry Type in the Import Bundle.

• A Metadata Entry Type, which does not already exist, is created with the same UUID specified in the import bundle.

4.3 Starting the Import/Export Tool

The Import/Export Tool can be run as a stand-alone client or launched from within Oracle Enterprise Repository from the Admin screen. The Import/Export Tool requires JDK 1.4.2 or later.

4.3.1 Launching from Oracle Enterprise Repository

To enable launching from the Admin tab, a new property must be configured and added and set to True:

cmee.importexport.enabled

This will enable an Import/Export section in Oracle Enterprise Repository. Due to the nature of the Import/Export Tool and the amount of data required for a comprehensive backup, the tool is restricted to users who are assigned the Admin role, such as the built-in admin user. The link to launch the Import/Export Tool is visible only to users with the Admin role.

Note: Since Import/Export is a self-contained tool utilizing REX, you will be required to log in again after launching it from Oracle Enterprise Repository.

4.3.2 Launching from Command Line

Ensure that the JDK (1.4.2 or later) is on the command path and that JAVA_HOME is set. Copy the impexp/ directory from the install media and execute the following:

• Win32 Platforms

  • impexp.bat

• Unix/Linux Platforms

  • sh./impexp.sh

4.3.3 Initial Startup

Upon launching the Import/Export Tool, the user is prompted to enter connection information for Oracle Enterprise Repository, as shown in Figure 4-1.

Note: You are not always prompted for credentials, except in the SSO environment.

Figure 4-1 Oracle Enterprise Repository Import/Export Utility

• OER URL

  Path to the Oracle Enterprise Repository installation, usually the same as the servlet path, as defined in the system settings. Example: http://appserver.example.com/oer/

• Username

  Name of a user who has been granted the Admin role within Oracle Enterprise Repository.

• Password

  Password for the user specified above.

To set a maximum time in milliseconds that an Import/Export tool can run before it is automatically killed by the job monitor, a new system setting must be configured:

cmee.extframework.impexp.monitor.maxruntime

4.4 Export Items from Oracle Enterprise Repository

This procedure is performed on the Oracle Enterprise Repository Admin screen.

1. Click Import Export in the Admin sidebar.

2. Click Import/Export Client. The Import/Export Client is displayed.

3. Click the Export tab.

   Figure 4-2 Export Tab

   
   

4. Enter the appropriate filename in the Select Target File text box or click Browse to select the target file for export.

5. Use the Select Entities to Export to identify the entities to be exported. This selection determines the specific behaviour of the export client in subsequent steps.

6. Click Next. The Select Assets to Export dialog is displayed, as shown in Figure 4-3, as determined by the selection in Step 5.

   Figure 4-3 Select Assets to Export Dialog

   
   

7. Use Search or click List All to display a list of items in the Available column.

8. Use the << and >> buttons to move selected items between the Available and the Selected columns.

9. Click Next. If more than one selection was made in Step 5 (Select Entities to Export), repeat Step 7 and Step 8 in the next Select dialog to select the next group of items for export.

10. Click Next. A list of the files to be exported is displayed in the Ready to Perform Export dialog, as shown in Figure 4-4.

    Figure 4-4 Ready to Perform Export Dialog

    
    

11. Click Next. A progress bar indicates the status of the export process.

    
    

    Note: Variations in the size and complexity of the exported items will affect the speed of this process and the behavior of the progress bar.

    
    

    A summary of the export is displayed on completion, as shown in Figure 4-5.

    Figure 4-5 Performing Export Operation Dialog

    
    

    On Microsoft Windows platforms, Windows Explorer will open to the folder where the archive was saved (assuming system permissions allow shell execution from the application).

4.5 Importing Items into Oracle Enterprise Repository

This procedure is performed on the Oracle Enterprise Repository Admin screen.

1. Click Import Export in the Admin sidebar.

2. Click Import/Export Client. The Import/Export Client page is displayed.

3. Click the Import tab.

4. Enter the appropriate filename in the Select File to Import text box or click Browse to select the source file for the import in Figure 4-6.

   Figure 4-6 Select Source File From Which to Import Dialog

   
   

5. Click Next. The selected source file is listed in the Ready to Perform Import dialog is displayed, as shown in Figure 4-7.

   Figure 4-7 Ready to Perform Import Dialog

   
   

6. Click Next. A progress bar indicates the status of the import process. Variations in the size and complexity of the imported items will affect the speed of this process and the behavior of the progress bar.

   A summary of the import is displayed on completion, as shown in Figure 4-8.

   Figure 4-8 Performing Import Operation Dialog

   
   

Note: When running the Import/Export tool, importing larger data sets may cause available memory issues. To avoid, save the impexp.jnlp file locally by right clicking on the Import/Export Client link and selecting "Save link as..." option from the context menu. Edit the impexp.jnlp file to increase the default max-heap-size amount to better accommodate the size of the data sets being imported. If the machine importing the data set has enough available memory, change the max-heap-size parameter to a higher value, as in the following example: <j2se version="1.6" max-heap-size="1024m"/>