17 Exporting and Importing Objects
This chapter contains the following topics:
- About Exporting and Importing Objects
The Oracle Life Sciences Data Hub export and import utility (also called the release utility) allows you to export all or part of a single Domain to a file and then read from the file to import the included objects to an Oracle LSH instance—either the same one or a different one—for example, to: - Objects Included and Excluded
There are objects you need to include and others you need to exclude. - Source Independence
The utility is designed to detect that an object is the same object even if it was imported first from one location and then from another location, and even if it has a different container object. - Exporting Objects
If you have the required role and privileges, you can fully or partially export objects. - Importing Objects
The import script checks to determine whether a Domain with the same name as the Domain being imported already exists. If it does, it checks whether the existing Domain was also created using the import script. - Installing Objects
You can run the install script to install objects in the imported Domain after you accept an import by committing changes to the target Oracle LSH database instance. - Preserving Customizations
If you have made changes to imported objects in the target instance that you want to preserve, use the Move operation to move the customized object definitions into a different Domain.
About Exporting and Importing Objects
The Oracle Life Sciences Data Hub export and import utility (also called the release utility) allows you to export all or part of a single Domain to a file and then read from the file to import the included objects to an Oracle LSH instance—either the same one or a different one—for example, to:
- Set up a new Oracle LSH instance within your organization.
- Make an Oracle LSH application that you developed available to others.
- Provide upgrades to previously imported objects.
The export and import utility includes three scripts:
- cdrruexport.sql exports objects to a file.
- cdrruimport.sql imports objects from a file.
- cdrruwainstall.sql installs imported objects.
The scripts are stored in the following location by default:
$CDR_TOP/patch/115/sql/
script_name
.sql
You must run these scripts from the command line on the computer where the Oracle LSH database server is installed. There is no user interface to run these scripts.
- Required Setup
Each script requires access to a local directory on the database server machine from within SQL*Plus. - Required Oracle Life Sciences Data Hub User Roles
Although you run the scripts as the userapps
, each script has input parameters requiring the username and password of an Oracle LSH user account with certain privileges.
Parent topic: Exporting and Importing Objects
Required Setup
Each script requires access to a local directory on the database server machine from within SQL*Plus.
All of the scripts write log files to this directory. The export script writes the export file to the directory and the import script reads from the file in the directory.
But since a SQL script cannot directly refer to a directory created using the operating system (OS), you must create a local database directory from SQL*Plus and map it to the local OS directory. Instructions are included in the sections on running the scripts.
You need to move the file from the export environment to the import environment through an upload and download, FTP, or any method that you use to transfer files.
Parent topic: About Exporting and Importing Objects
Required Oracle Life Sciences Data Hub User Roles
Although you run the scripts as the user apps
, each script has input parameters requiring the username and password of an Oracle LSH user account with certain privileges.
See Roles and Privileges Required for Exporting and Roles and Privileges Required for Importing Domains.
Parent topic: About Exporting and Importing Objects
Objects Included and Excluded
There are objects you need to include and others you need to exclude.
This section contains the following topics:
- Objects Included
The following object types can be included: - Objects Excluded
The following objects are not exported:
Parent topic: Exporting and Importing Objects
Objects Included
The following object types can be included:
- All organizational (container) objects: Domains, Application Areas, and Work Areas. If you export a whole Domain, all nested Domains and other organizational objects contained in it are included. If you export objects at a lower level of the object hierarchy, the utility automatically includes all parent objects up to the top-level Domain.
- All object definitions of the following types contained in the included Domains and Application Areas: Tables, Load Sets, Programs, Variables, Parameters, Parameter Sets, and Business Areas.
- All the object instances of the same types contained in the Work Areas: Table instances, Load Set instances, Program instances, Parameter Set instances, and Business Area instances.
- Underlying object definitions for the included object instances that are contained within the Domain specified for export. That is, if you specify an object instance for export but not its underlying object definition, the system automatically includes the definition if it is included in the same Domain.
Note:
If the underlying object definition of an included object instance is located in a Domain outside the one you specify, the object instance cannot be imported correctly and the export log file contains a warning. - Secondary objects contained in primary object definitions:
- Table definition: Columns and Table Constraints
- Load Set definition: Table Descriptors, Planned Outputs, and Parameter Set instances
- Program definition: Table Descriptors, Parameter Set instances, Source Code definitions and instances, and Planned Outputs
Note:
A single line of source code text that has more than 32765 characters does not get exported correctly. - Business Area definition: Table Descriptors, Joins, and Hierarchies
- Secondary objects contained in the following primary object instance types:
- Table instance: Table Constraints
- Load Set instance: Mappings
- Program instance: Mappings
- Business Area instance: Mappings
In addition to the above objects, the following Oracle LSH object components are also exported:
- Version labels
- All runnable active Execution Setups for all instances being exported, including backchain Execution Setups
Note:
All versions of versioned objects are included, except for Work Areas, for which only the most recent version is included. Domains and Application Areas are not versioned.
Parent topic: Objects Included and Excluded
Objects Excluded
The following objects are not exported:
- All validation supporting information including all supporting outputs and supporting documents.
- The classification hierarchy assigned to any object. On import, the default of the target Oracle Life Sciences Data Hub instance's classification is used for that object type.
- The subtype of any object. On import the default subtype of the target Oracle LSH instance is used for each object type.
- Checkin and checkout comments.
- Execution and Work Area installation data (jobs, outputs, data).
- All other object types: Adapter Domains, Adapter Areas, Workflows, Report Sets, Data Marts.
- Other Oracle LSH metadata: Users, User Groups, Roles, Subtypes, Adapter Security, Database Accounts, Remote Locations and Connections, Service Locations, Hierarchies, Terms, and Subtypes.
Parent topic: Objects Included and Excluded
Source Independence
The utility is designed to detect that an object is the same object even if it was imported first from one location and then from another location, and even if it has a different container object.
- Recognizing the Same Object Imported from Different Sources
The utility preserves each object's original Company ID and Object ID in an import archive table on the target database. - Updating Namespaces
The export includes the current parent of each included object, and the parent's current parent, and so on, up to the top-level Domain. - Updating Mappings
If an object is imported from a different source location than a previous version of the same object, the import process duplicates the object's source and target mappings from the most recent source in the target location.
Parent topic: Exporting and Importing Objects
Recognizing the Same Object Imported from Different Sources
The utility preserves each object's original Company ID and Object ID in an import archive table on the target database.
(The Company ID is the same for all objects in a database and, with the Object ID, forms the primary key of each object.) Imported objects also receive a new Company ID and Object ID on the target database.
When you export objects, the export process checks if each included object was previously imported—that is, has a record in the import archive table—and if it was, exports the object with its original Company ID and Object ID.
The import script checks the Company ID and Object ID of each object being imported against the Company ID and Object ID of records in the import archive table. If it finds a match it compares the version numbers and upgrades if a newer version is being imported.
For example, if you:
- export an Application Area from Location A to Location B
- and then export the same Application Area from Location A to Location C
- and then modify one of the Programs it contains on Location C
- and then import the Application Area from Location C to Location B
then the import process running on Location B recognizes that the Program is the same as the existing Program originally imported from Location A, compares the version numbers of the matching Programs, and upgrades the Program in Location B to the newer version.
Parent topic: Source Independence
Updating Namespaces
The export includes the current parent of each included object, and the parent's current parent, and so on, up to the top-level Domain.
The export script checks if each parent object was itself imported—that is, has a record in the import archive table. If the current parent object was imported, it is included in the export with its original Company ID and Object ID. If the current parent was not imported, it is included using its current Company ID and Object ID. This ensures that each object is exported with its current object ownership hierarchy, even if some objects were originally imported and others were not.
Parent topic: Source Independence
Updating Mappings
If an object is imported from a different source location than a previous version of the same object, the import process duplicates the object's source and target mappings from the most recent source in the target location.
Parent topic: Source Independence
Exporting Objects
If you have the required role and privileges, you can fully or partially export objects.
The export script:
- Checks in all the objects being exported, with the checkin comment "Checked in by IEU."
- Creates a zipped file with the name of the Domain as filename
(
domain_name
.zip). This file contains the metadata for exportable objects contained in the Domain. - Places the log file (domain_name.log) separately in the same directory; see Export Log File Content.
- Full and Partial Export
When you run the export script, you must enter a parameter value to indicate whether you want to perform a full or partial export. - Roles and Privileges Required for Exporting
When you execute the script you must supply an Oracle Life Sciences Data Hub user account that has the following privileges: - Creating the Directory and Running the Export Script
To run the export process, do the following from the database server where you have the Oracle Life Sciences Data Hub source database instance installed: - Export Log File Content
The script does not run at all if you provide incorrect usernames (database and/or application user) or an incorrect database directory name. Rerun the script with correct parameter values in that case.
Parent topic: Exporting and Importing Objects
Full and Partial Export
When you run the export script, you must enter a parameter value to indicate whether you want to perform a full or partial export.
When you run the export script, you must enter a parameter value to indicate whether you want to perform a full or partial export.
- Full export. The export script automatically includes the Domain you specify and almost all the objects it contains (see Objects Included and Objects Excluded).
- Partial export. You must populate a database driver table with a list of the objects to be included. The script automatically includes objects contained in the objects you specify, including objects contained in those objects and objects required for those objects to exist, as described in Populating the Driver Table and within the limits described in Objects Included and Objects Excluded.
This section contains the following topic:
- Populating the Driver Table
The driver table must include a single column that contains the object ID of objects you want to include in the export.
Parent topic: Exporting Objects
Populating the Driver Table
The driver table must include a single column that contains the object ID of objects you want to include in the export.
The driver table must include a single column that contains the object ID of objects you want to include in the export. You do not need to list every object. Within the limits described in Objects Included and Objects Excluded, the utility automatically includes additional objects as follows:
- Domains. If you enter the object ID of a Domain in the driver table, the utility exports all definitions in the Domain, all Application Areas in the Domain, and all objects in the Application Areas, including object definitions, Work Areas, object instances in the Work Areas, and the object definitions and container objects required for them to exist; see "Object Definitions and Instances, and their Containers" in the Oracle Life Sciences Data Hub Application Developer's Guide for further information.
- Application Areas. If you enter the object ID of an Application Area in the driver table, the utility exports the Application Area and all objects contained in it, including object definitions, Work Areas ,and object instances in the Work Areas, and the object definitions and container objects required for them to exist.
- Work Areas. If you enter the object ID of a Work Area in the driver table, the utility exports all object instances in the Work Area and the object definitions and container objects required for them to exist.
- Object instances. If you enter the object ID of an object instance in the driver table, the utility exports all objects required for the instance object to exist, including both primary and secondary definitions that are instantiated by the instances, any source and target Table instances, and all container objects above them in the object hierarchy. See the Oracle Life Sciences Data Hub Application Developer's Guide Appendix on "Object Ownership" for further information.
Note:
Some objects may be listed explicitly in the driver table and also included in the export because of their relation to another object. The utility ignores such duplication and exports each object only once.
Parent topic: Full and Partial Export
Roles and Privileges Required for Exporting
When you execute the script you must supply an Oracle Life Sciences Data Hub user account that has the following privileges:
- Modify privileges on all objects types that have to be exported
- The LSH Checkin Admin application role, if there are objects in the Domain that are checked out by a user other than this Oracle LSH application user
These privileges are required because the export script has to check in all checked out objects before proceeding with the rest of the export process.
If the application user does not have sufficient privileges, and the export script needs to check objects in, the export fails.
See Setting Up the Security System for more information on granting roles and privileges in Oracle LSH.
Parent topic: Exporting Objects
Creating the Directory and Running the Export Script
To run the export process, do the following from the database server where you have the Oracle Life Sciences Data Hub source database instance installed:
Parent topic: Exporting Objects
Export Log File Content
The script does not run at all if you provide incorrect usernames (database and/or application user) or an incorrect database directory name. Rerun the script with correct parameter values in that case.
The export process fails if the script is unable to check in some or all exportable objects. This is usually because theOracle Life Sciences Data Hub application user whose username you provide while running the script does not have sufficient privileges or if some other user is modifying the Domain at the same time when you run the export script. The export log lists details of objects that it cannot check in.
When the export process runs successfully the log file lists the following:
- Names of all Remote Locations and Remote Connections used by all Load Sets being exported. This is useful in manually creating the same in the target Oracle LSH instance.
- Names of Source Code CLOBs and BLOBs that the export script converted into files.
- The object name, object type, version number, and container details of:
- All objects that the export script could successfully check in and include in the export
- All objects that could not be included in the export and the reason for that.
Note:
Object instances that refer to definitions outside the Domain being exported will not work in the target Oracle LSH instance.
You must examine the log file, copy object definitions for such instances into the Domain, update the object instances to point to the copied object definitions, and rerun the export script.
Parent topic: Exporting Objects
Importing Objects
The import script checks to determine whether a Domain with the same name as the Domain being imported already exists. If it does, it checks whether the existing Domain was also created using the import script.
If the existing Domain is not an imported Domain, the import script creates a new Domain. If the existing Domain is an imported Domain, it upgrades objects that have new versions, allowing you to deploy new versions of an Oracle LSH application on the target Oracle LSH instance.
This section contains the following topics:
- Upgrading an Existing Domain
This section describes how to upgrade the existing domain with the import script. - Roles and Privileges Required for Importing Domains
When you execute the script you must supply an Oracle Life Sciences Data Hub user account. - Creating the Directory and Running the Import Script
To import an Oracle Life Sciences Data Hub Domain, run the following commands from the database server where your target Oracle LSH instance is installed. - Import Log File Content
The import log file contains any errors that the system encounters while creating objects in the target Oracle Life Sciences Data Hub instance and many other details on objects, locations and connections (for example, results of running install scripts). - Applying Security to an Imported Domain
You must assign at least one user group to a new imported Domain (not required for an upgraded imported Domain) to be able to view and use the other objects imported in it.
Parent topic: Exporting and Importing Objects
Upgrading an Existing Domain
This section describes how to upgrade the existing domain with the import script.
The import script performs the following tasks:
- If any objects are currently checked out in the Domain on the target Oracle Life Sciences Data Hub instance, the script checks them in with the comment "Checked in by IEU".
- Checks out all objects with the comment "Checked out by IEU" and updates the versions of the object definitions and instances if it finds new versions in the export file.
- Checks in object definitions after versioning and applies the comment "Checked in by IEU."
- Creates a log file in the database directory on the target Oracle LSH instance. The log file has the same name as the Domain: domain_name_import.log. See Import Log File Content.
- You must check the log and decide whether or not to
commit
changes to the database on account of the upgrade. You canrollback
the changes if the import log shows problems during upgrading.
Parent topic: Importing Objects
Roles and Privileges Required for Importing Domains
When you execute the script you must supply an Oracle Life Sciences Data Hub user account.
The user account must have the following privileges:
- LSH Checkin Admin application role. This role is essential for importing or upgrading a Domain.
- LSH Bootstrap Admin application role. This role is required only for creating new Domains, not for Domain upgrades. This role allows an application user to create the Domain and objects under it.
- Sufficient privileges to be able to install Oracle LSH Work Areas.
This user does not require any other privileges to run the import because object security is temporarily granted to this user as part of the import process.
See Setting Up the Security System for more information.
Parent topic: Importing Objects
Creating the Directory and Running the Import Script
To import an Oracle Life Sciences Data Hub Domain, run the following commands from the database server where your target Oracle LSH instance is installed.
Parent topic: Importing Objects
Import Log File Content
The import log file contains any errors that the system encounters while creating objects in the target Oracle Life Sciences Data Hub instance and many other details on objects, locations and connections (for example, results of running install scripts).
The import log file contains:
- Errors that the system encounters while creating objects in the target Oracle Life Sciences Data Hub instance.
- Object name, object type, version number, and container details of:
- All objects that the import script could successfully create or upgrade during the import
- All object instances that the import script did not upgrade because the instance objects referenced object definition not contained in the imported Domain. The Import Export Utility allows preservation of user customizations through this feature. See Preserving Customizations.
- Remote Locations and Connections that do not exist in the target instance but are referenced by one or more Load Sets in the imported Domain. Such Load Sets may not be installable until you create the Remote Locations and Remote Connections in the target instance.
- Objects that were installable in the source instance but are noninstallable in the target Oracle Life Sciences Data Hub instance.
- Table instances that were upgradable in the source instance but are nonupgradable in the target Oracle Life Sciences Data Hub instance.
- If you ran the install script, the import log lists details of all
objects successfully installed and errors and warnings, if any. In addition, the
following details are logged for an install:
- Status of all Work Areas imported.
- Submission ID, job ID, and the Execution Setup location and version number for all backchain submissions created.
Parent topic: Importing Objects
Applying Security to an Imported Domain
You must assign at least one user group to a new imported Domain (not required for an upgraded imported Domain) to be able to view and use the other objects imported in it.
You must have the LSH Bootstrap Admin Role for this operation.
From the Domain's properties screen, do the following:
- From the Actions drop-down list, select Apply Security and click Go. The system opens the Manage Security screen.
- Click Assign Group. The system opens the Search User Group screen.
- If you know the name of the user group you want to assign to the Domain, enter it in the Group Name field. You can also enter part of a name and the system will return all groups that include the string you enter in their name. If you leave the field blank, the system returns all user groups.
- Click Go. The system displays all user groups that satisfy your query.
- Select any number of user groups: click their Select check box and click Apply.
- Click Return to return to the Properties screen for the Domain.
Parent topic: Importing Objects
Installing Objects
You can run the install script to install objects in the imported Domain after you accept an import by committing changes to the target Oracle LSH database instance.
If you ran the import script using COMMIT_ON_NO_ERROR and there were no errors, the import script committed the changes to the database. If you ran the import script set to MANUAL_COMMIT you must commit the changes manually after examining the log file.
The install script accepts the same parameters as the import script. You can also run the install script after upgrading a Domain.
You must have the privileges required to install Oracle LSHWork Areas.
The install script performs the following tasks:
- Installs all the installable Work Areas in the imported Domain. For upgraded Domains, only Work Areas that the import script upgraded or added while upgrading, are installed.
- In all successfully installed Work Areas that include imported objects with backchain Execution Setups, the install script submits these Execution Setups and the jobs run in backchain mode.
For upgraded Domains, the install script does not submit backchain Execution Setups in the following cases:
- If the object instance in the upgraded Domain is customized (that is, refers to an object definition outside the Domain)
- If the source object instance does not contain a backchain Execution Setup but the target object instance does
- If the source instance's backchain Execution Setup has not been modified since the last import but the target instance has a new backchain Execution Setup
- Writes details of the installation process to domain_name_import.log stored in the database directory.
See "Installation Requirements for Each Object Type" in the Oracle Life Sciences Data Hub Application Developer's Guide for reasons for a Work Area installation to fail.
This section contains the following topic:
- Running the Installation Script
To run the install script, do the following from the target Oracle Life Sciences Data Hub database instance:
Parent topic: Exporting and Importing Objects
Running the Installation Script
To run the install script, do the following from the target Oracle Life Sciences Data Hub database instance:
Parent topic: Installing Objects
Preserving Customizations
If you have made changes to imported objects in the target instance that you want to preserve, use the Move operation to move the customized object definitions into a different Domain.
The Move operation keeps references intact, so that instances of each moved definition continue to point to the same definition in its new location.
The import utility performs a check so that it never overwrites an object instance that points to a definition outside the imported Domain, even if the object instance is included in the import.
The utility does import definitions from the source that correspond to the definitions you have moved, but they have no effect because no object instances use them.
Parent topic: Exporting and Importing Objects