| Oracle® Life Sciences Data Hub System Administrator's Guide Release 2.4 E52195-02 |
|
|
PDF · Mobi · ePub |
| Oracle® Life Sciences Data Hub System Administrator's Guide Release 2.4 E52195-02 |
|
|
PDF · Mobi · ePub |
This chapter contains the following topics:
Note:
This utility imports and exports metadata. To export data out of Oracle LSH, use Oracle LSH Data Marts. See "Defining Data Marts" in the Oracle Life Sciences Data Hub Application Developer's Guide.The Oracle LSH 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. 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.
Required Oracle LSH 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".
This section contains the following topics:
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.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 LSH 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.
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. (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.
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.
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.
This section contains the following topics:
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".
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".
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 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.When you execute the script you must supply an Oracle LSH 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 Chapter 9, "Setting Up the Security System" for more information on granting roles and privileges in Oracle LSH.
To run the export process, do the following from the database server where you have the Oracle LSH source database instance installed:
Connect to the database instance as the Oracle Applications schema owner; usually apps.
Create an OS directory where you want the output of the export script to be generated; for example, in the Oracle LSH application user's home directory.
The export process creates .log and. xml files that contain Oracle LSH object metadata information that may be sensitive to your organization. Oracle recommends granting full access to the OS directory only to the Oracle user and the user who runs the export process.
For example:
mkdir /user/xyz/exp_imp # Below command removes all rights on the directory from others chmod o-rwx /user/xyz/exp_imp # Assuming the user running export owns the directory and Oracle user is part of a group called orcl chgrp orcl /user/xyz/exp_imp # Grant read,write,execute privileges on the directory to the group chmod g+rwx /user/xyz/exp_imp # Grant read,write,execute privileges on the directory owner chmod u+rwx /user/xyz/exp_imp
Notes:
Do not include any spaces in the OS directory name.
The OS directory must be empty before running the export script.
Map the OS directory to a database directory using the following SQL command:
CREATE DIRECTORY database_directory_name as path_of_the_OS_directory
From the OS directory, enter the following command with appropriate values. Each parameter is described in text below.
sqlplus apps@LSH_source_database_server_name @path_of_cdrruexport.sql LSH_application_user Database_directory_name Export_type Export_table Export_column Domain_name
The parameters are:
LSH Application Username. Enter a valid Oracle LSH application user's username. The script checks in all checked out objects in this user's name. The script prompts for the password.
Database Directory Name. Enter the name of the database directory you created in SQL*Plus that maps to the OS directory.
Export Type. Enter F to perform a Full export or P to perform a partial export; see "Full and Partial Export".
Export Table. If you are performing a partial export, supply the name of the database driver table that stores the object IDs of the objects you are exporting.
If you are performing a full export, enter any value; for example, x.
Export Column. If you are performing a partial export, supply the name of the database driver table column that stores the object IDs of the objects you are exporting.
If you are performing a full export, enter any value; for example, x.
Domain Name. Enter the name of the Oracle LSH Domain that you want to export. The Domain name is case sensitive.
Note:
If the Domain name contains spaces or any special characters, enclose the Domain name in the escape character (\) followed by double quotes (").For example, if the Domain's name is Domain 1, enter it as:
\"Domain 1\"
Note:
If you include an object instance in the export whose underlying definition is not contained within this Domain, the export of the object instance does not succeed. The export log file contains a warning.The export script creates a zipped file and a log file in the database directory. Both the files have the Domain's name as the filename. Check the domain_name.log file for details of the export operation. See "Export Log File Content".
Note:
The zipped filename contains underscores in the place of any spaces in the Domain name. However, regardless of the zipped filename, the Domain created in the target Oracle LSH instance has the same name as the exported Domain in the source Oracle LSH instance.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 the Oracle LSH 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.
This section contains the following topics:
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.
The import script performs the following tasks:
If any objects are currently checked out in the Domain on the target Oracle LSH 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 can rollback the changes if the import log shows problems during upgrading.
When you execute the script you must supply an Oracle LSH user account that has 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 Chapter 9, "Setting Up the Security System" for more information.
To import an Oracle LSH Domain, run the following commands from the database server where your target Oracle LSH instance is installed:
Connect to the database instance as the Oracle Applications schema owner; usually apps.
At least the first time you run the script, create an OS directory where you want the import log to be generated. For example, create it in the LSH application user's home directory so that it is easy to find.
The import process creates a .log file that contains Oracle LSH object metadata information that may be sensitive to your organization. Oracle recommends granting full access to the OS directory only to the Oracle user and the user who runs the import process.
For example:
mkdir /user/xyz/exp_imp # Below command removes all rights on the directory from others chmod o-rwx /user/xyz/exp_imp # Assuming the user running import owns the directory and Oracle user is part of a group called orcl chgrp orcl /user/xyz/exp_imp # Grant read,write,execute privileges on the directory to the group chmod g+rwx /user/xyz/exp_imp # Grant read,write,execute privileges on the directory owner chmod u+rwx /user/xyz/exp_imp
Notes:
Do not include any spaces in the OS directory name.
Before running the import script, be sure that you have only the current domain_name.zip file in the OS directory.
Map the OS directory to a database directory using the following SQL command:
create directory database_dir_name as path_of_the_OS_directory
Go to the OS directory you created and copy the exported Domain file into it.
Note:
If you have not created the exported Domain file yourself, you can receive it from the person who has through a download or an emailâany medium that you use to transfer files.Run the import script as follows:
sqlplus apps@LSH_target_database_server_name @path_of_cdrruimport.sql LSH_application_user Database_directory_name Zipped_Domain_Filename COMMIT_ON_NO_ERROR/MANUAL_COMMIT
The script requires the following command line parameters in this sequence:
LSH Application Username. Enter a valid Oracle LSH application user's username. The import script creates all the imported Domain's objects and performs other required operations on them, such as checking the objects in or out, as this Oracle LSH application user. The script prompts you for a password for this user, when run.
Database Directory Name. Enter the name of the database directory you created in SQL*Plus that maps to an OS directory where you want the import script to generate the import log file; see "Required Setup".
Zipped Domain Filename. Enter the name of the zipped export file (domain_name.zip) that you copied from the source Oracle LSH instance.
COMMIT_ON_NO_ERROR/MANUAL_COMMIT: You must specify one of these options to the import script:
COMMIT_ON_NO_ERROR. If you want Oracle LSH to commit the imported Domain's data to the database, enter this option. Oracle LSH commits the data if there are no errors while importing.
If there are errors, Oracle LSH rolls back the data and you must rerun the import script after fixing the errors.
MANUAL_COMMIT. Enter this option if you want to commit or roll back the data manually after examining the import log.
The import script creates a log file in the database directory with a name in this format: domain_name_import.log. See "Import Log File Content".
The import log file contains the following information:
Any errors that the system encounters while creating objects in the target Oracle LSH instance.
The 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 LSH instance.
Table instances that were upgradable in the source instance but are nonupgradable in the target Oracle LSH 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.
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.
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 LSH Work 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.
To run the install script, do the following from the target Oracle LSH database instance:
Connect to the database instance as the Oracle Applications schema owner; usually apps.
Change to the OS directory you created while running the import script.
Make sure the zipped Domain file exists in the OS directory and that it is the latest exported Domain. For a Domain upgrade, the install script first checks whether or not the exported Domain file has the same or higher version numbers for objects. Installation does not continue if the exported Domain file is not the latest.
Run the install script from the OS directory as follows:
sqlplus apps@LSH_target_database_server_name @path_of_cdrruwainstall.sql LSH_Application_Username Database_Directory_Name Zipped_Domain_Filename
Enter the same values for the parameters that you did while running the import script. See "Creating the Directory and Running the Import Script".
The script adds the install-related messages to the import log file.
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.
|
 Copyright © 2006, 2015, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
