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 API Catalog.

This chapter includes the following topics:

4.1 Overview

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

Note:

When using the Import/Export tool, adhere to the following best practices:
  • Exporting from Oracle API Catalog and importing to Oracle API Catalog is supported

  • Exporting from Oracle Enterprise Repository and importing to Oracle Enterprise Repository is supported

  • Exporting from Oracle API Catalog and importing to Oracle Enterprise Repository is supported

  • Exporting from Oracle Enterprise Repository and importing to Oracle API Catalog is supported only with use of the Export to API Catalog utility. You can use the Import/Export tool to import zip files created by this utility. Using the Import/Export tool in other ways to import assets from OER to OAC is NOT SUPPORTED and NOT RECOMMENDED.

    See "Installing the Export to API Catalog Feature Patch" in Oracle Fusion Middleware Installation Guide for Oracle Enterprise Repository for information about installing the utility and "Exporting API Assets to API Catalog" in Oracle Fusion Middleware Integration Guide for Oracle Enterprise Repository for information about using the utility to export API assets from OER to OAC.

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 API Catalog. This section contains the following topics:

Note:

The Import/Export tool requires Java Web Start. See Section 2.7, "Install Java Web Start" for more information about installing and configuring Java Web Start.

4.2.1 Overview

The Import/Export tool is available from within Oracle Enterprise Repository on the Admin page. The Oracle Enterprise Repository user is required to have the admin role to access the tool.

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

The Export operation enables you to search for objects in Oracle Enterprise Repository to export. You can search for and select single or multiple API assets to export. The result of the Export operation is a .zip file with the selected APIs. By default, a sample parameter.properties file is contained within the resulting .zip file.

Note:

The Import/Export tool will not import or export the icons of APIs in Oracle API Catalog. Duplicate assets in the import bundle already present in OAC are ignored.

The Import operation takes a .zip file that was exported by the Import/Export tool and loads the contained items into Oracle API Catalog. The behavior for the Import is determined by META-INF/parameter.properties or a series of default actions.

Note:

You can also import assets exported from the search results screen, as described in "Exporting Asset Search Results to ZIP" in Oracle Fusion Middleware Developer's Guide for API Catalog.

Oracle API Catalog Administrators who must move data between different instances of Oracle API Catalog must use the Import/Export tool or the Oracle API Catalog OpenAPI. When the Import/Export tool is utilized, a parameter.properties file must be included in the .zip bundle before performing the import operation. The Export operation creates a placeholder file located in the /META-INF directory.

4.2.2 The parameter.properties File

Each import bundle contains a /META-INF directory. This directory contains a file that controls how the Import/Export tool behaves when the bundle is imported. If the parameter.properties file does not exist, it must be created before any Import operation.

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 API Catalog

Standard.saver.assettype.props.duplicate.matching

Note:

This parameter is not used in Oracle API Catalog, but it is present in the parameter.properties file. It is recommended to leave this property as the default value.
  • 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 API Catalog.

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

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

Standard.saver.assettype.props.duplicate.handling

Note:

This parameter is not used in Oracle API Catalog, but it is present in the parameter.properties file. It is recommended to leave this property as the default value.
  • 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 API Catalog.

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

    • Merge - Merge the asset type in Oracle API Catalog with the duplicate asset type from the bundle. The Merge operation does not modify any of the elements of the asset type in Oracle API Catalog. The operation is additive, appending elements in the asset type from the bundle to the asset type in Oracle API Catalog. 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 API Catalog with the duplicate asset type from the bundle. The assets of the asset type in Oracle API Catalog is not modified, although the display of these assets is affected.

Standard.saver.relationshiptype.props.duplicate.handling

Note:

This parameter is not used in Oracle API Catalog, but it is present in the parameter.properties file. It is recommended to leave this property as the default value.
  • 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 API Catalog. 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 API Catalog.

    • Overwrite - Replace the relationship type in Oracle API Catalog with the duplicate relationship type from the bundle. This overwrites all information for the relationship type. This also creates any asset relationships that use this relationship type and do not already exist in Oracle API Catalog.

Standard.saver.metadata.props.duplicate.handling

Note:

This parameter is not used in Oracle API Catalog, but it is present in the parameter.properties file. It is recommended to leave this property as the default value.
  • 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 API Catalog. 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 API Catalog with the duplicate CMF Metadata from the bundle. This overwrites all information for the CMF Metadata.

Standard.saver.metadata.props.duplicate.handling

Note:

This parameter is not used in Oracle API Catalog, but it is present in the parameter.properties file. It is recommended to leave this property as the default value.
  • 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 API Catalog. 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 API Catalog with the duplicate CMF Metadata Entry Type from the bundle. This overwrites 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: parameters.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]
#Standard.saver.asset.props.duplicate.handling=[Create New Version, Ignore, Overwrite]
#Standard.saver.asset.props.duplicate.matching=[UUID, NameVersion]

## 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]

4.3 Starting the Import/Export Tool

The Import/Export Tool can be launched from within Oracle API Catalog from the Admin screen. The Import/Export Tool requires JDK 1.4.2 or later.

4.3.1 Launching from Oracle API Catalog

The Import/Export Tool is launched from the Admin page. 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 Import/Export section on the Admin page is enabled and configured by a property in system settings. If the section is not visible for a user with the admin role, then verify that the following system setting is enabled and set to True:

cmee.importexport.enabled

4.3.2 Launching from Outside of Oracle API Catalog

You may need to use the Import/Export tool when you aren't logged in to Oracle API Catalog locally. You can save the Import Export tool and run it from your local machine.

To run the Import/Export utility from a local machine:

  1. Follow the instructions in Section 2.7, "Install Java Web Start" to configure Java Web Start to run on the system

  2. Click Import Export from the Admin page.

  3. Click the Import/Export Client icon, select Save File or your browser's equivalent, and then save the impexp.jnlp file.

  4. Move the impexp.jnlp file to the location from which you want it to run.

  5. Run the impexp.jnlp file.

    Note:

    You can also run the Import Export tool by saving it locally, and then using the javaws executable, located in <JAVA_HOME>/jre/bin. For example:
    <JAVA_HOME>/jre/bin/javaws -verbose /path_to_file/impexp.jnlp
    

4.3.3 Initial Startup

Upon launching the Import/Export Tool, you may be 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 API Catalog Import/Export Utility

Description of Figure 4-1 follows
Description of ''Figure 4-1 Oracle API Catalog Import/Export Utility''

  • OER URL

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

  • Username

    Name of a user who has been granted the Admin role within Oracle API Catalog.

  • 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 API Catalog

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

  1. Click Import Export from the Admin page.

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

  3. Click the Export tab.

    Figure 4-2 Oracle API Catalog Export Tab

    Description of Figure 4-2 follows
    Description of ''Figure 4-2 Oracle API Catalog Export Tab''

  4. Enter an appropriate file name in the Select Target File field or click Browse to select the directory into which the target file will be exported. Click Next.

  5. The Select Assets to Export dialog is displayed, as shown in Part II, "Select Assets to Export Dialog".

    Figure 4-3 Select Assets to Export Dialog

    Description of Figure 4-3 follows
    Description of ''Figure 4-3 Select Assets to Export Dialog''

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

  7. Use the arrow buttons to move selected items between the Available and the Selected columns.

  8. Click Next. A list of the files to be exported is displayed in the Ready to Perform Export dialog.

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

    Note:

    Variations in the size and complexity of the exported items affects 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-4.

    Figure 4-4 Performing Export Operation Dialog

    Description of Figure 4-4 follows
    Description of ''Figure 4-4 Performing Export Operation Dialog''

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

4.5 Importing Items into Oracle API Catalog

This procedure is performed on the Oracle API Catalog Admin screen.

  1. Click Import Export from the Admin page.

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

  3. Click the Import tab.

  4. Enter the appropriate file name in the Select File to Import field or click Browse to select the source file for the import in Figure 4-5.

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

    Description of Figure 4-5 follows
    Description of ''Figure 4-5 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-6.

    Figure 4-6 Ready to Perform Import Dialog

    Description of Figure 4-6 follows
    Description of ''Figure 4-6 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 affects 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-7.

    Figure 4-7 Performing Import Operation Dialog

    Description of Figure 4-7 follows
    Description of ''Figure 4-7 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"/>