Oracle® Life Sciences Data Hub Application Developer's Guide Release 2.3.1 E35298-02 |
|
![]() Previous |
![]() Next |
This section contains information on the following topics
To reach the Work Area Properties screen, click the Applications tab and navigate to the Application Area that contains the Work Area, then click the Work Area's hyperlink. You can also use the Search field from many other Oracle LSH screens.
You can see information about the Work Area as a whole and about all the object instances it contains.
Work Area information and actions:
Object instance information and actions:
Oracle Life Sciences Data Hub (Oracle LSH) Work Areas are designed to allow many people to work simultaneously on developing different parts of a single application. In addition, depending on your company's policies, you may have one or more Work Areas of your own to work in. You may or may not be able to create Work Areas yourself.
As you define the objects required for a particular application, you must install them in the database before you can run the executable objects or write data to tables; see "Installing a Work Area and Its Objects".
A Work Area itself has the following properties:
Usage Intent Work Areas have a special property called Usage Intent that interacts with the validation status of the Work Area and its contained object instances to enforce certain system behavior. The valid usage intent values are the same as the validation status, except for Retired. They are Development, Quality Control, and Production.
For an explanation of the interaction of usage intent and validation status, see "Work Area Usage Intent and Validation Status" in the Oracle Life Sciences Data Hub Implementation Guide.
Validation Status The validation status of the Work Area itself. You cannot promote a Work Area to a higher validation status until every object it contains has a validation status equal to or greater than the new Work Area validation status.
Status A Work Area's status is either Installable or Non Installable. The status is Installable only if every object instance contained in it is Installable. However, even if the status is Non Installable, you can run the installation job as follows:
You can run upgrade or partial installation if you omit the noninstallable objects.
You can run full installation. If an executable object is noninstallable, the system automatically performs automatic mapping by name for any unmapped target Table Descriptors, looking for Table instances of the same name in the current Work Area. If any target Table Descriptors remain unmapped, the system creates Table instances from them in the current Work Area and maps them. The executable object may then be installable.
You can install individual objects; see "Installing Individual Objects".
Note: Even if a Work Area's status is Installable, you cannot install it if the source definition of any of its object instances is checked out by another user.However, if you have the Checkin Administrator privileges you can check in all objects that are checked out by other users and install the Work Area. The system displays a warning indicating that you are checking in objects checked out by other users. Normal object security privileges on the Work Area and its objects is also required. |
Version The current version of the Work Area. (You can see information about previous versions by selecting View Version History from the Actions drop-down list.)
Cloning Label If this Work Area was the source or target of a Work Area clone, the system displays the label entered at the time of clone.
Version Label If a user has applied a label to this version of the Work Area, the system displays it here. To create a label for the current Work Area version, select Version Label from the Actions drop-down list.
Domain The system displays the Domain in which the Work Area is located.
Application Area The system displays the Application Area in which the Work Area is located.
Forward Chain Enabled If checked, Programs and other executables in the Work Area can be part of a forward chaining execution process if they are set up to do so. If unchecked, no Program or other executable in the Work Area can be part of a forward chaining process even if they are set up for it; see "Forward Chaining" for more information.
To see a record of each previous installation of the Work Area, do the following:
From the Actions drop-down, select Installation History.
Click Go. The system displays the Work Area Install History screen.
The Install History screen includes the following information:
Installation Attempt The system assigns a number x.y
to each installation attempt, where x
is the version number and y
is installation attempt on that version represented by the row. For example, if the current Work Area version number is 3 and there have been 5 installation attempts on version 3, then the most recent installation attempt number is 3.5, and the previous one is 3.4.
Install Status The system displays the final status of the installation attempt. If the installation was successful, the status is Installed. If the installation was not successful, the system displays the status corresponding to the last installation phase completed successfully. See "Work Area Installation Phases and Statuses".
Install Mode The system displays the mode used to run the installation: Full, Partial, or Upgrade. See "Installation Modes" for further information.
Force to Regenerate Scripts If set to Yes, the installation process regenerated installation scripts even for objects that had not changed since the previous successful installation. If set to No, the installation process generated installation scripts only for objects that had changed since the last successful installation.
Installed By The username of the person who initiated the installation attempt.
Installation Date The date on which the installation was completed.
View Log Click the icon in the View Log column to see the log file for the installation. See "Reading the Log File" for further information.
To see the Work Area's version history, do the following:
From the Actions drop-down, select View Version History.
Click Go. The system displays the Work Area's Version History screen.
The Version History screen includes the following information:
Name The Work Area version's name.
Description The Work Area version's description.
Version The Work Area version's version number.
Status The installation status: either Installable or Non Installable.
Validation Status The validation status of the Work Area: either Development, Quality Control, or Production.
Usage Intent The usage intent of the Work Area: either Development, Quality Control, or Production.
Last Modified By The username of the person who last made any changes to the Work Area, including checking out any object instance in the Work Area.
Last Modified The date of the last modification to the Work Area.
To view additional details about a Work Area version, click the Show hyperlink or its plus (+) icon. The system displays the following information, if it exists:
Cloned From If the Work Area version was created by cloning another Work Area onto this one, the system displays the name of the original Work Area.
Cloning Label If the Work Area version was created by cloning another Work Area onto this one, the system displays the label created for the cloning operation.
Version Label If a user created a label for the Work Area version, the system displays the label.
Work Areas have a special property called Usage Intent that interacts with the validation status of the Work Area and its contained object instances to enforce certain system behavior. The valid usage intent values are the same as the validation status, except for Retired. They are Development, Quality Control, and Production.
For an explanation of the interaction of usage intent and validation status, see "Work Area Usage Intent and Validation Status" in the Oracle Life Sciences Data Hub Implementation Guide. For a discussion of Work Area usage, see "Work Areas" in Oracle Life Sciences Data Hub Implementation Guide.
When a Work Area is first created, its usage intent is set to Development.
Special privileges are required to modify a Work Area's usage intent.
To modify the usage intent, do the following:
From the Actions drop-down list, select Update Usage Intent.
Click Go.
In the Description field, enter the reason you are making the change.
From the Usage Intent drop-down, select the value you want to apply: Development, Quality Control, or Production.
Click Apply. The system makes the change and returns you to the Work Area's Properties screen.
The Work Area properties screen can display the following information about each object instance contained in the Work Area. You can reduce the number of columns displayed and change the right-to-left order in which they are displayed by clicking the Customize button or selecting a different view; see "Personalizing Your Work Area Properties Screen".
You can change the top-to-bottom display order of a Work Area's objects by sorting on the fields with an asterisk (*) below.
Name* The name of the object instance. The name is hyperlinked; click it and the system opens the Properties screen for that object instance.
Type* The object type.
Technology* For executable object instances, this is the technology type; for example, SAS or PLSQL for Programs; Oracle Clinical Labs or SAS for Load Sets. For Table instances, it is the processing type; for example Staging or Transactional with Audit.
Description The object description entered by its Definer.
Latest Version The number of the latest version of the object instance.
Installed Version The number of the version of the object instance that is currently installed.
Status* Objects can have the following statuses:
Installable. The object either is installed or can be installed.
Non Installable. The object has problems that prevent it from being installed. See Appendix A, "Installation Requirements for Each Object Type" for the reasons each object type may be noninstallable.
Note: The Install option for single object instances is always available, even for objects with a status of Non Installable. The system automatically addresses the problem of unmapped Table Descriptors during installation; see "Installing Individual Objects". |
Upgradable. This status applies only to Table instances. If a Table instance is Upgradable, you can install it using any mode. If it is Non Upgradable, you cannot install it in upgrade mode. See information on Upgrade mode under "Installation Modes".
Note: An object instance of any type is not installable if its source definition is checked out by a user different from the person initiating the installation (except a Checkin Administrator), or if its source definition is not installable for any other reason. |
Validation Status* Development, Quality Control, Production, or Retired; See "Validating Objects and Outputs" for further information.
Has Data* This field applies only to Table instances. If set to Yes, the Table instance contains data. If set to No, the Table instance does not contain data.
Definition Checked Out By* If the source definition of the object instance is checked out, the system displays the username of the person who has checked it out.
Created TS * Timestamp when the object was created.
Created By* User ID of the person who created the object.
Last Modified TS* Timestamp of the most recent modification of the object.
Last Modified By* User ID of the person who most recently modified the object.
Installed TS* Timestamp of the most recent installation of the object.
Last Submit TS* This field applies only to executable instances: timestamp of the most recent submission of the object.
Last Refresh TS* This field applies only to Table instances: timestamp of the most recent job that wrote data to the Table instance.
Browse Data, Install, Launch, Submit See "Object Instance Actions" below.
You can take actions on individual object instances by one or more of the following methods:
The following actions are available on each object's row if your view displays them:
Browse Data This action applies only to Table instances. It opens the Browse Data screen for the Table instance; see "Viewing Data within the Oracle Life Sciences Data Hub".
Install This action installs a single object at a time. For Table instances, it performs an upgrade installation.
Launch This action applies only to Program and Business Area instances. It opens the integrated development environment for the appropriate technology for the object.
Submit This action applies only to executable instances. The system displays the Submission screen based on the default Execution Setup. You can modify Parameter values as required and submit the job.
Additional actions are available in the drop-down list.
Select an object.
Select an item from the Select Object and: drop-down list. The following actions are available:
Add Source Table This action applies only to executable instances. It allows you to create a Table Descriptor from an existing Table instance for the selected executable instance.
Browse Data This action applies only to Table instances. It opens the Browse Data screen for the Table instance; see "Viewing Data within the Oracle Life Sciences Data Hub".
Copy See "Copying Objects" for information. You can select and copy multiple objects at the same time.
Clone See "Cloning Objects" for information. You can select and clone multiple objects at the same time.
Default Execution Setup Displays the default Execution Setup for that instance. You can then modify it; see "Creating, Modifying, and Submitting Execution Setups".
Execution Setup Displays the Execution Setup listing screen for the executable instance. You can then select any Execution Setup defined for the executable and modify or submit it; see "Creating, Modifying, and Submitting Execution Setups".
Remove The system immediately removes the object from the user interface so that it is no longer visible. The object is not deleted from the database until the next Work Area installation, at which point the system automatically drops it. You can select and remove multiple objects at the same time.
Note: If you remove a Table instance, you lose all the data it contains. |
To protect data, when you try to remove a Table instance:
The system does not remove the Table instance if its validation status is Production.
If the Table instance is mapped to a Table Descriptor in one or more Programs, Load Sets, Data Marts, or Business Areas, the system displays a warning listing the executable objects to which it is mapped. It also displays the validation status of the Table instance, and whether or not the Table instance is installed.
If the Table instance is not mapped to any Table Descriptors, the system displays a confirmation message.
View All Outputs This action applies only to executable objects. It displays a list of all outputs produced by the instance. You can click the links to view the actual outputs.
View Output This action applies only to executable objects. It displays the most recent output produced by the default Execution Setup for the instance.
To add an object to a Work Area, do the following:
From the Add drop-down list, select the type of object you want to add.
Click Go. The system displays the Create screen for the type of object you want to add.
For instructions on creating objects, see the chapter on each object or click Help from the Create or object properties screen.
You can add, remove, or move labels to or from the data in any or all of the Table instances in a Work Area at the same time.
By default, the system displays the most recent snapshots of all audited Table instances in the Work Area that contain data. If you want to work with an older snapshot, perform a query; see "Querying for Snapshots".
This section contains the following topics:
To add, remove, or move a label from one or more snapshots that are not the most current, start by searching for the Table instance snapshots you want to act on:
In the Work Area Properties screen, select Manage Snapshot Labels from the Actions drop-down list. The system opens the Manage Snapshot Labels screen.
Blinding Status. Tables that contain blinded data have two partitions, one that contains the real, sensitive, blinded data, and one that contains dummy data. You can apply different labels, one at a time, to snapshots of the blinded and dummy partitions. You must specify whether you want the system to query for blinded or dummy.
The system always queries for snapshots of nonblinded Table instances (Table instances that do not contain blinded data).
Select one of the following:
Most Recent Refresh Timestamp as of. To search by timestamp, click the button next to Most Recent Refresh Timestamp as of and then select a date and time from the drop-down list.
Snapshot Label. To search by label, click the button next to Snapshot Label and then select a label from the drop-down list.
Click Search. The system populates the lower portion of the screen with the Table instance snapshots in the Work Area that satisfy the search criteria.
The system displays the following information for each snapshot that satisfies the search criteria you specified in the upper portion of the screen:
Table. The name of the Table instance of which this is a snapshot.
Blinding Status.
If Blinded, the action you are about to take affects the blinded partition of a Table instance that contains blinded or unblinded data.
If Dummy, the action you are about to take affects the dummy partition of a Table instance that contains blinded or unblinded data.
If Not Applicable, the Table instance does not contain blinded or unblinded data.
Writing Instance Type. The object type that writes data to this Table instance: either a Load Set instance or a Program instance.
Writing Instance Name. The name of the Writing Instance.
Job ID. The unique ID of the job that wrote the data to the Table instance at the time in the Refresh TS column.
Snapshot Label. The snapshot label or labels currently applied to the Table instance snapshot.
Source Currency Information. Currency (timestamp) of the Table instances or external tables or views that the Writing Instance (Program or Load Set) read from when writing to the Table instance snapshot. If the Writing Instance is a Load Set, source timestamp comes from the Load Set execution time for all Load Set types except Oracle Clinical Load Sets; Oracle Clinical type Load Sets get source timestamp from the Oracle Clinical system.
Refresh TS. The timestamp that defines the snapshot of the Table instance.
To add, remove, or move a snapshot label, do the following:
The most current snapshots available are displayed by default. If you want to work on older snapshots, enter a query; see "Querying for Snapshots".
Specify the label to want to add, remove, or move. Either enter it in the Snapshot Label field or, if the label you want to add or remove has already been used in this Work Area, do the following:
Click the Search icon for the Snapshot Label field. The system opens a Search pop-up window.
Enter the label you are looking for, or use special characters if you do not know the exact label. Special characters are explained in the "Searching" chapter of the Oracle Life Sciences Data Hub User's Guide.
Click Go. The system returns all the labels that fit the criteria.
Click the Quick Select icon for the label you want.
The system returns to the Manage Snapshot Label screen with the label you selected in the Snapshot Label field.
Click the Select checkbox to select the snapshots to which you want to add, or from which you want to remove, the label.
Click one of the following:
Add Snapshot Label. The system adds the label you specify to the snapshot(s) you specify.
Remove Snapshot Label. The system removes the label from the snapshot(s) you specify.
Add/Move Snapshot Label. For each Table instance you specify, if the label you specify is currently applied to any snapshot, the system removes the label from that snapshot and moves it to the snapshot you specify.
So much information is available on the objects in the Work Area that it does not fit easily onto a standard computer screen. You can free up space by removing columns you don't use or changing the order in which columns are displayed so that the ones you need most often are easily visible. You can scroll to any columns you do not remove.
You can select an alternative view from the View drop-down if other views are available, or create your own custom view. After you create your view, other people can use it too.
To personalize your view of the Work Areas Properties screen:
Click the Customize button.
Do one of the following:
If you want to use an existing view without changes, select Yes in the Display View column in the view's row. Skip to the last step: click Apply.
If you want to create a new view beginning with the default values, click Create View. The system opens the Update View screen displaying the default settings.
If you want to create a new view beginning with an existing view, select a view and click Duplicate. The system opens the Update View screen displaying the settings of the view you duplicated.
To modify an existing view, click the pencil icon in its Update column. The system opens the Update View screen displaying the settings of the view.
Enter values in the following fields:
View Name. Enter a name for your view or change the existing name.
Number of Rows to Display: From the drop-down, select a number of rows to display in the Work Area screen at a time. The options are 5, 10, 25, and 50.
Set as Default. Check this box to display this view each time you enter the Work Area Properties screen.
Description. (Optional) Enter a description. For example, you can provide information that will help other people decide if they want to base their own view on this one.
Remove columns from display (optional). If you want to remove columns, move them from the Columns Displayed list to the Available Columns list, either by double-clicking on them or by selecting them and using the Remove button. You can also use Remove All and then add the columns you want using the Move button.
Note: You cannot remove the Name column. |
Change column display order (optional). The left-to-right display order of columns on the Work Area Properties screen is determined by the top-to-bottom order of columns in the Columns Displayed list. The topmost column here is displayed farthest to the left. Select a column whose order you want to change and use the up and down arrows to move it relative to the other columns.
Change the Sort settings (optional). Use the Sort settings to determine the order in which object instances are displayed by default. You can also change the Sort order directly in the Work Area Properties screen at any time (by clicking on column headings) without affecting the view.
Column Name. From the drop-down list in the First Sort row, select the column you want to sort on.
Sort Order. From the drop-down list, select the order you want to use: Ascending or Descending.
You can define a Second Sort to control the order of objects within the limits of the First Sort, and a Third Sort to control the order of objects within the limits of the Second Sort.
Rename Columns and Set Totalling. Click the Rename Columns/Totalling button.
Rename Columns. You can change the displayed heading for most columns. Enter the replacement text in the New Column Name text box next to the default column heading.
Display Totals. This option is displayed by default for numeric columns. However, it is not useful in these cases to check this option.
Click Apply.
This section contains the following topics:
To use a Table, Program, Load Set, Data Mart, Report Set, Workflow, or Business Area definition that you have created in Oracle LSH, you must create an instance of it in a Work Area and install the instance and the Work Area itself. The first time you install a particular Work Area, the system does the following:
Creates an Oracle LSH Schema—a set of database schemas; see "Schemas"
Instantiates Table instances as database tables
Instantiates Table Descriptors in executable objects and Business Areas as views onto the tables to which they are mapped
Compiles source code for PL/SQL -type Programs, including PL/SQL Programs contained in Report Sets and Workflows
Note: SAS and Oracle Reports Programs are compiled at runtime by SAS and Oracle Reports, respectively. |
Associates an Oracle Warehouse Builder Task with every executable object, for use in executing the object
After you install a Work Area, the system keeps it under version control. As soon as you change anything in an installed Work Area—check out an object instance, add or delete an object instance, or even change the description—the system creates a new version of the Work Area that contains all the changes you make before re-installing the Work Area.
Note: If you install a single executable object using the Install icon or drop-down item the system tries to map any unmapped Table Descriptors and may create target Table instances; see "Installing Individual Objects". This functionality is not available when you install at the Work Area level. |
Installation Modes Oracle LSH supports three installation modes: Full, Upgrade, and Partial. See the section on the Omitted flag for further details on how each installation mode handles omitted objects.
Full installation drops and replaces the entire set of schemas. All objects—including tables, checked-out objects, and any objects whose Omitted flag is checked but have been previously installed—are dropped, replaced, and checked in. Full installation deletes all data. During a full installation the entire Work Area is locked and no one can modify any object in the Work Area, including objects whose Omitted flag is checked.
Full installation may be useful during development and quality control testing when data may be corrupted and no audit trail is required. When you change an installed Table's blinding flag, you must do a Full Work Area installation to apply the new blinding status to the Table instance.
Upgrade installation compares the Work Area's installed objects to the current objects and adds new objects and replaces objects that have changed—except for Table instances, which are always upgraded rather than replaced so as to save all data.
Upgrade installation never drops an object. If you check the Omitted flag for an object and run Upgrade installation, the object is not installed.
During an upgrade installation the entire Work Area is locked and no one can modify any object in the Work Area, including objects that are omitted from the installation.
Partial installation allows you to specify the action you want the installation job to take on the objects you include in the installation, including explicitly dropping objects. For each table you can specify whether to replace or upgrade the table; if you choose to replace it, the system deletes its data; if you choose to upgrade it, the system upgrades the table to the new version without deleting its data.
During a partial installation, you and other users can continue to work on the objects that are omitted from the installation.
Partial installation is useful during development, when multiple developers are working in the same Work Area and need to install and test their objects at different times.
Note: To safeguard data, Oracle LSH allows only nondestructive installation modes in Work Areas with a Usage Intent of Production. You can use Upgrade mode or Partial mode, but in Partial mode Table instances must have Upgrade as their assigned action. |
Installation Rules The system cannot install a Work Area in the following circumstances:
The Work Area has a status of Retired.
The Work Area version is not the most current version.
The Work Area has a usage intent of Production and the installation mode is set to Full or to Partial with an action other than Upgrade for one or more Table instances.
The validation status of any object included in the installation is less than the usage intent of the Work Area.
No objects have changed in the Work Area since the last successful installation.
A previous attempt to install the same version of the Work Area was unsuccessful, and has not been cancelled by the user.
The source definition of one or more object instances included in the installation have been explicitly checked out by a user other than the person initiating the installation.
Note: People with Checkin Administrator privileges can install objects checked out by other people. |
The system cannot install a Program instance or other executable if the Table instances to which it is mapped are not either already installed or included in the same installation.
If the source code of a PL/SQL Program included in the installation does not compile, the installation fails.
To install a Work Area and one or more of the objects it contains, go to the Work Area and do the following:
Click Installation in the Properties screen of the Work Area you want to install. The system displays the Work Area Installation screen.
Choose a mode of installation. See "Installation Modes" for further information.
Full installation drops and replaces the entire schema with all objects, including tables, deleting all data.
Upgrade installation automatically add and replaces only objects that are new or changed since the last successful installation, and always upgrades tables, rather than deleting them, so that it does not delete data.
Partial installation allows you to specify which objects you want to install and what action you want the installation job to take on the objects you include.
Note: To safeguard data, Oracle LSH allows only nondestructive installation modes in Work Areas with a Usage Intent of Production. You can use Upgrade mode or Partial mode, but in Partial mode Table instances must have Upgrade as their assigned action. |
In the Install Actions drop-down list, select Process Current Installation to Completion. This is the only option currently available.
Choose whether or not to run a batch install:
If you select Batch Install, the system runs the installation as a batch process. The installation job is placed on a queue and the system returns control of the UI to the user. You can abort the installation if necessary.
If you do not select Batch Install, the system runs the installation in interactive mode. The installation job does not go onto a queue and therefore can run more quickly than in batch mode. However, you cannot do anything else in Oracle LSH until the installation has completed. You cannot abort the installation. Interactive mode is appropriate when you are installing a small number of objects.
Choose whether or not to Force Script Regeneration. During installation, the system generates two sets of scripts for objects that have changed since the last successful installation:
DDL scripts for each object included in the installation. The system uses these scripts to create the actual schema objects during installation.
Scripts to be used at runtime for some of the objects; for example, a SAS script for a SAS-based Program that establishes the appropriate SAS views for accessing Oracle LSH data.
If you select this option, the system generates new scripts for all objects in the installation, even if they have not changed. All objects are either replaced or, if they are Tables, upgraded. This is useful if your schema has become corrupted and you want to recreate all objects without losing any data.
Checking this attribute has an effect only in Upgrade mode. In Full mode the system always regenerates scripts for every object regardless of the setting of this attribute. In Partial mode the system uses the action you specify in the Actions column for each object to determine whether to regenerate the scripts.
Review the objects to be installed. You can sort the objects in the Work Area by clicking most of the column headings, including: Name, Type, Installable, Upgradable, Definition Checked Out By, and Current Version Installed?.
Check the box in the Omitted column for each object you want to omit from the installation. The system automatically checks this box for objects whose status is Non Installable. You can also use the Omit All and Omit None buttons.
You can omit any object in any installation mode and, if the object you omit has never been installed, it will be truly excluded from the installation process. However, if it has already been installed, the system takes a different action depending on the installation mode:
Full. In Full mode, the installation process drops the object and replaces it with the same version that was already installed. If a Table instance has already been installed and you run a Full installation on its Work Area, the system drops and replaces the Table instance and deletes all its data, even if you check its Omitted checkbox.
Upgrade. In Upgrade mode, objects marked as Omitted are not installed.
Partial. In Partial mode, when you check an object's Omitted checkbox, the system automatically sets the Action for the object to No Action. If you leave Action set to No Action, the object is omitted. If you change this setting, the installation does not omit the object, but performs the action you specify.
Note: Objects with a value of No in the Installable column are automatically omitted from the installation in all modes. |
To save your changes but install later, click Apply.
To install now, click Apply and Install.
Note: Before the installation can begin, the system must wait for all job executions of Work Area Programs, Load Sets, Report Sets, or Workflows currently running to complete. The system prevents new jobs from starting. |
You can install any object by clicking the Install icon in its row. If the object is not installable the system automatically performs automatic mapping by name for any unmapped target Table Descriptors, looking for Table instances of the same name in the current Work Area. If any target Table Descriptors remain unmapped, the system creates Table instances from them in the current Work Area and maps them. The executable object may then be installable; see Appendix A, "Installation Requirements for Each Object Type".
If the object is installable, the system performs an upgrade installation for the selected instance and any of the Table instances to which it is mapped that are not already installed. If the object being installed or any of its mapped Table instances is not installable, the installation fails and the system displays an error message with the name of the noninstallable object.
If the object being installed is an Oracle Clinical SAS or Oracle Data Extract Load Set and there are no target Table Descriptors defined, the system automatically creates target Table Descriptors, Table instances, and Table definitions based on all the active SAS or Oracle Data Extract views defined for the selected Oracle Clinical study or study set, and maps the Table Descriptors and corresponding Table instances.
When you start an installation, the system displays the Installation Processing Monitoring screen. It has the same information as the Installation screen. If you are running installation in interactive (not batch) mode, all the fields are read-only. In batch mode you can use the Abort button to stop the installation job.
When the installation completes, a different display appears depending on whether the installation completed successfully or failed; see:
If the installation fails, the system displays the status Install Failed. The Installation Status displays the last phase the installation process reached. See "Installation Rules" for some of the reasons an installation may fail, and "Work Area Installation Phases and Statuses".
Note: You must cancel the installation by clicking Cancel or Cancel Installation before you can try again to install the Work Area. |
You cannot roll back any changes made by the installation process.
To see what actions the installation took, look at the log file.
Finding the Log File To view the log file, do the following:
Click Cancel to return to the main Work Area screen.
From the Actions drop-down list, select Installation History.
Click Go. The system displays the Installation History screen.
Click the View Log link for the most recent installation attempt. The system displays the log file.
Reading the Log File In the log file, you see a record of all the phases the installation process passed through before failing. See "Work Area Installation Phases and Statuses" for information on these phases.
The log file contains information about parts of the installation that failed, with an error message. Each failed activity is called a "unit." This is an Oracle Warehouse Builder term and can be a package or other unit.
For example, if the installation fails because the PL/SQL code in a Program did not compile, the log file contains a message like the following:
Calling Create deployment Unit Name=PKG_CDR_W4_170DAE141_1_$CREATE_7 ORA-00900: invalid SQL statement Unit Name=PKG_CDR_W4_170DAE141_1_$CREATE_7 ORA-04042: procedure, function, package, or package body does not exist fail to complete create deployment Set install status to $INSTSTATUSES$CREATEACTIVE set work area status to install failed
Note the name of the unit and then look at the bottom of the log file for further details about the problem(s) with the unit.
If the installation succeeds, the system displays a status of Installed and an installation status of Installation Completed Successfully.
Each object included in the installation is displayed, and you can click the View Script link for any object to see the DDL scripts the system generated for that object.
Click View Installation Log to see the log file.
This section contains the following topics:
During installation, Oracle LSH uses Oracle Warehouse Builder (OWB) to convert Work Area definitional objects to database objects.
Each Work Area is installed to its own set of Oracle database schemas, collectively called an Oracle LSH schema. An Oracle LSH schema encompasses all the installation targets, including Oracle database schemas and file systems.
Each Oracle LSH schema includes a primary Oracle database schema and one or more auxiliary Oracle database schemas. Auxiliary schemas contain compiled PL/SQL code and private synonyms to resolve naming conflicts.
Primary Schema Each Oracle LSH schema includes one primary schema that owns all installed database objects except the compiled PL/SQL code. The primary schema is name Wcccc_nnnn, where cccc is the company ID and nnnn is the internal hexadecimal ID of the Work Area.
Auxiliary Schemas Auxiliary schemas contain all the Work Area's compiled PL/SQL code and private synonyms that resolve the object instances referenced in the PL/SQL code to the actual Tables in the primary schema or in the primary schemas of other Work Areas (see"Object Name Resolution").
The auxiliary schemas are named Wcccc_nnnn_x, where nnnn is the internal hexadecimal ID of the Work Area and x is a unique identifier for the auxiliary schema.
Because you can reuse Oracle LSH object definitions such as Tables, Table Descriptors, and Programs in Oracle LSH, there can be naming conflicts within a Work Area. For example, two PL/SQL Programs may refer to two different Tables called Adverse Events, one of which contains raw source data, while the other contains transformed data.
Oracle LSH resolves any naming conflicts in PL/SQL programs (including Oracle Reports Programs and including Report Sets, Workflows, Load Sets, and Data Marts) by using private synonyms in as many auxiliary schemas as necessary. For each PL/SQL Program, the system records the name of the auxiliary schema that resolves its Table Descriptors' naming conflicts.
For security reasons, PL/SQL Programs cannot be stored in the primary schema. They are stored in an auxiliary schema. If a PL/SQL Program includes multiple packages, they are all installed in the same auxiliary schema.
The system analyzes the PL/SQL Programs to be created for a Work Area, determines the number of auxiliary database schemas needed, and creates them. This analysis is performed in Oracle LSH metadata tables during the installation Preparation in Progress phase; the actual auxiliary schemas and their private synonyms are created during installation.
Oracle Warehouse Builder converts defined objects in a Work Area to Oracle LSH schema objects as follows:
Table Instance A Table instance becomes a database table, with any user-defined constraints and any system-defined or user-defined indexes as well as a data manipulation view, an associated Instead-Of trigger, and supporting PL/SQL package.
If a Table instance is defined as a pass-through view, it becomes a view in the database.
Executables For each executable object—Program, Load Set, Report Set, Workflow, or Data Mart—the system creates its Table Descriptors as views onto the Table instances to which they are mapped and generates a PL/SQL package.
Source Table Descriptors each become a view that does the following:
resolves the Table Descriptor to the real table
maps Table Descriptor Columns to real table columns
implements Oracle LSH's dynamic security mechanism
implements currency snapshotting
implements incremental data access
implements blinding
Target Table Descriptors each become a view that does the following:
resolves the Table Descriptors to the DML View
maps Table Descriptor Columns to underlying table columns
implements Oracle LSH's dynamic security mechanism
PL/SQL Programs, including those contained in Report Sets and Workflows, become:
compiled PL/SQL code in an auxiliary schema or schemas
synonyms to map names used in the PL/SQL Program to the proper source or target view in the primary schema
synonyms to map names of external package references to packages in another auxiliary schema
For SAS and Oracle Reports Programs, OWB creates an OWB Task to call the DP Server and to grant access to the appropriate database tables.
The Work Area installation process includes many phases. As the job progresses through these phases the system assigns it different installation statuses. The system displays the highest status reached during the process when the process is complete. You can also see the job's progress from phase to phase in the log file.
After completing each phase, the system checks the value of the Abort flag. If the installation is running in batch mode and the user has clicked the Abort button to stop the installation, the system stops the job. You cannot roll back any changes the job may have made up to that point.
Installation Specification The system gathers the attribute settings for the installation: Batch Mode (Yes/No), Force Script Regeneration (Yes/No), Installation Mode (Full, Upgrade, Partial), Install Status of the previous installation, if any (statuses noted after each phase in this list), Installation Number (current installation number for this Work Area version plus one).
Related Installation Status: SPECIFIED (Specification phase complete)
Preparation The system performs all tasks required before the Generation Phase, including obtaining the necessary locks, identifying the objects to be installed and the actions to be taken on them, checking in objects, and ensuring that the installation is valid (see "Installation Rules").
Related Installation Status: PREPARED (Preparation phase complete)
Generation In a full or upgrade installation the system determines how many schemas are necessary to hold the installed objects and which objects to place in which schema. The system generates the DDL scripts that will be used to install, drop, drop and replace, or upgrade each object included in the installation and, in a full or upgrade installation, the schemas themselves.
Related Installation Statuses: GEN_ACTIVE (Generation phase in progress), GENERATED (Generation phase complete)
Quiescence If the Work Area is currently being installed, the system prevents jobs from starting that are based on the submission of Oracle LSH Programs, Load Sets, Report Sets, Workflows, or Data Marts installed in the Work Area, and waits for any jobs currently running to complete. In a partial installation, the system prevents or waits for job executions only of the objects being installed; the execution of objects not included in the partial installation can proceed.
Related Installation Status: QUIESCING (quiescing runtime processing)
Unit Definition Oracle LSH calls the Oracle Warehouse Builder (OWB) interface packages to create the deployment units that OWB will use to carry out the required actions on each object in the installation.
Related Installation Statuses: DEF_ACTIVE (Unit Definition phase in progress), DEFINED (Unit Definition phase complete)
Schema Activities The system creates the Oracle schemas required by the installation if they do not yet exist. In a full installation the system drops existing schemas creates new schemas.
Related Installation Statuses: SCHEMA_ACTIVE (Schema Activities in progress), SCHEMA_COMPLETE (Schema Activities complete)
Upgrade Prepare OWB compares the proposed table and table-related changes to the state of the objects in the database schema and prepares an upgrade plan script to implement the upgrade. This phase applies only to upgrade installations and partial installations where the action on an object is Upgrade.
Related Installation Statuses: UPGPREP_ACTIVE (Upgrade prepare in progress), UPGPREPARED (Upgrade prepare complete), UPGPREP_FAILED (Upgrade prepare failed)
Upgrade Deploy OWB carries out the upgrade plan and stores the initial state of the tables and their data in backup tables. This phase applies only to upgrade installations and partial installations where the action on an object is Upgrade.
Related Installation Statuses: UPGDEPL_ACTIVE (Upgrade deployment in progress), UPGDEPLOYED (Upgrade deployment complete), UPGDEPL_FAILED (Upgrade deployment failed)
Upgrade Finalization OWB discards the backup tables. The upgraded tables contain the data. This phase applies only to upgrade installations and partial installations where the action on an object is Upgrade.
Related Installation Statuses: UPGFIN_ACTIVE (Upgrade finalization in progress), UPGFINALIZED (Upgrade finalization complete)
Drop OWB performs the deployment units for any dropped objects.
Related Installation Statuses: DROP_ACTIVE (Drop phase in progress), DROPPED (Drop phase complete)
Create OWB performs the deployment units for any objects being created.
Related Installation Statuses: CREATE_ACTIVE (Create phase in progress), CREATED (Create phase complete)
Completion The system performs the following clean-up tasks:
For full and upgrade installations the Work Area Status is set to Installed. If there are any objects that are checked out in the Work Area (due to being omitted from the installation) the system then checks out the Work Area and changes its status to In Definition.
For partial installations, if the Work Area contains omitted objects whose current version has not been installed, the Work Area is checked in with a status of Partial Install and checked out again with a status of In Definition.
If the Parameters or Parameter settings for a newly installed program have changed, existing repeating, deferred, or backchain submissions are cancelled without notification.
The system releases the state of quiescence.
The system releases the installation lock.
Related Installation Status: INSTALLED (Installation completed successfully)
As the Work Area moves through its life cycle of development, installation, modification, reinstallation, and retirement, the system assigns it a Work Area Status as follows:
In Definition The Work Area has been defined but not yet installed, or has been installed and is now being modified.
Locked for Installation The Work Area and all its object instances are locked. No one can check them out or run any jobs. This status applies to full and upgrade installations.
Locked Partial The object instances included in a partial installation are locked. No one can check out locked objects or submit locked executables for execution.
Partial Install The Work Area has never had a full installation but has been through a successful partial installation.
Installed The Work Area has been successfully installed and is available for use.
Retired The Work Area still exists in the database but you cannot submit any of its executable objects for execution; see "Retired" for further information.
Oracle LSH supports cloning Work Areas so that you can make an exact copy of a Work Area and all the objects it contains and install it to a new Oracle LSH Schema to create a test or production data environment.
When you first create an object of any kind, including a Work Area, its validation status is set to Development. Your company should develop standards for promoting objects to the validation status Quality Control, and from Quality Control to Production. Oracle LSH enforces rules concerning the interaction of the validation statuses of a Work Area and each of its objects, and the value of the Work Area's Usage Intent attribute, to support the validation process.
Tools Oracle LSH uses the following tools to support validation and separate environments for testing and production:
Usage Intent Attribute. Work Areas have attribute called Usage Intent with the possible values Development, Quality Control, and Production.
Cloning. Work Areas have an operation called cloning that creates an exact duplicate of the Work Area and all its object instances.
Validation Status. All object definitions and instances, including Work Areas, have a validation status with the possible values Development, Quality Control, Production, and Retired.
When all the object instances in a Work Area, and the object definitions on which they are based, reach a higher validation status than the Work Area's Usage Intent, a user with the necessary privileges can clone the Work Area and set the new Work Area's Usage Intent attribute to the next higher value. See Figure 12-1, "Application Development and Validation Process".
Rules Oracle LSH enforces the following rules:
To be installed in a Work Area, object instances must have a validation status equal to or greater than the Usage Intent of the Work Area.
A Work Area cannot be promoted to a validation status higher than the validation status of any of its object instances.
No executables can be run in a Work Area until the Work Area's validation status is equal to or greater than its Usage Intent value, except by users with the special Install Qualify Submit privilege on the Work Area. This is to allow testing of a Work Area before making it available to the full set of users with security access to it.
Full installation is not allowed in Work Areas with a Usage Intent of Production. This is to protect production data from deletion.
The intended Work Area usage includes the following stages: Development, Quality Control, and Production. Figure 12-1, "Application Development and Validation Process" shows these stages.
Figure 12-1 Application Development and Validation Process
Development When you create a Work Area, the system sets both its Usage Intent attribute and its validation status to Development. When you create an object definition or instance, the system sets its validation status to Development. When you have successfully conducted unit testing on an object, according to your organization's standards, set the object's validation status to Quality Control (or request a privileged user to change the status, depending on your security design).
When all the object instances in a Work Area have a validation status of Quality Control, a privileged user clones the Work Area, creating duplicates of all object instances, with pointers to the same object definitions and the same validation statuses as the originals. The version number of the new object instances is 1. The system creates a label for both Work Areas indicating that they are identical at the time of cloning. The privileged user enters text for the label and creates the new Work Area with a Usage Intent of Quality Control. However, its validation status should remain at Development.
Quality Control Install the new Quality Control Work Area. While its validation status (Development) is lower than its Usage Intent (Quality Control), only a user with the Install Qualify Submit privilege can run executables. That privileged user loads fresh data and tests the installation. The privileged user then promotes the Work Area validation status to Quality Control. Users with normal security access to the Quality Control Work Area can then test the objects.
If testers find bugs or other problems, developers should fix them in the Development Work Area. To do this, you can clone the QC Work Area onto the development Work Area, overwriting the old one, perform a full installation, and load fresh data. When all objects have been fixed and tested, and their validation status upgraded, you can clone the development Work Area onto the QC Work Area.
Note: If new objects are being developed in the Development Work Area, do not clone the QC Work Area onto the original Development Work Area or they will be lost. Instead, do one of the following:
|
Promote each object definition and instance to Production when it meets your production standards. Clone the QC Work Area to create a Production Work Area.
Production Install the new Production Work Area. While its validation status is lower than its Usage Intent, only a user with the Install Qualify Submit privilege can run executables. That privileged user loads fresh data and tests the installation. The privileged user then promotes the Work Area validation status to Production. Users with normal security access to the Production Work Area can then run the application.
Run the application as necessary for your business purposes. Using the same cloning procedures described above, modify the objects as necessary over time. Make modifications through the Development Work Area, test each modified object definition in the QC Work Area, and clone the QC Work Area to the Production Work Area.
Note: The cloning operation replaces only objects that have been modified. Cloning does not replace Production Table instances or data. |
Retired When you close a trial, you can set its Production Work Area's validation status to Retired. This prevents anyone from running any executables within the Work Area. However, you can still use the data as input to a Program or other executable in a different Work Area. For example, you can merge and analyze the data with data from other closed or current trials.
When you retire a Work Area, you may also want to change its user group assignments so that only a very limited group of people can change its validation status back to Production and run Programs or other executables on the data.
If you need to run a Program in a Production Work Area after you have set its validation status to Retired, you must set its validation status back to Production. For example, to track patients and update their adverse event records after the trial has closed, set the Work Area's validation status back to Production, run the necessary Programs, and set the validation status back to Retired. Alternatively, create a new Work Area for this purpose.
You can use the cloning operation together with the Usage Intent Work Area attribute and object validation statuses (Development, Quality Control, Production, and Retired) to create clean, controlled, distinct environments for application development, testing, and production. See "Application Life Cycle".
The cloning operation is similar to the copy operation except that it is possible to clone a Work Area over an existing Work Area, so that the clone overwrites the existing Work Area. For example, if you already have a Quality Control usage intent Work Area, and several objects fail quality control testing, you can update the objects in the Development Work Area and then clone the whole Development Work Area onto the QC Work Area, creating a new version of the QC Work Area.
Object instances in the Work Area clone point to the same source definitions in the same location that the instances in the original (source) Work Area did.
Note: If you clone onto a Work Area that contains objects, the cloning operation replaces only those objects that have a different version number from the same object in the source Work Area. |
When you clone a Work Area, you specify a label that the system applies to the source and target Work Area version. The label is proof that the source and target Work Area versions are identical. All the object instances in the two Work Areas are identical, and corresponding objects' validation status is the same. If you clone the same version of the same Work Area more than once, the system uses the same label each time.
To clone a Work Area, do the following:
You can begin a cloning operation in two different places:
In the original Work Area's Properties screen, click Clone.
In the main Application Development screen, click the icon in the Clone column for the original Work Area.
The system opens the Step 1 Clone Work Area screen.
In the Clone Label field, enter the text for the label. This text will be displayed in the relevant version of the source and target Work Areas.
From the Usage Intent drop-down, select the Usage Intent you want to set for the target Work Area.
In the Clone Destination area, click the button in the Select column to specify the target.
If you select an Application Area, the cloning operation creates a new Work Area in that Application Area. The new Work Area's name is the same as the source Work Area with "_1" appended.
If you select an existing Work Area, the cloning operation overwrites that Work Area.
Click Review. The system displays information about the source (original) and target Work Areas, including all object instances in the source, for you to review. For each object, the system displays the action to be taken in the target Work Area:
Create. If the object does not exist in the target Work Area, the system creates it.
Replace. If the object exists in the target Work Area and has been modified in the source Work Area since the last clone, the system replaces the target object with the source object.
Remove. If the object exists in the target Work Area but not in the source Work Area, the system removes the object in the target Work Area.
No Action. If the object exists in the target Work Area and has not been modified in the source since the last clone, the system does not modify the target object.
If you see a problem, click Cancel to cancel the cloning operation and return to the Work Area.
To run the cloning operation, click Finish. The system performs the cloning operation and opens the Properties screen of the target Work Area, displaying a confirmation message that the clone was successful.