| Oracle® Life Sciences Data Hub Adapter Toolkit Guide Release 2.4 E54091-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Life Sciences Data Hub Adapter Toolkit Guide Release 2.4 E54091-01 |
|
|
PDF · Mobi · ePub |
This section contains the following topics:
Oracle Life Sciences Data Hub (Oracle LSH) includes a generic visualization adapter that allows you to integrate an external tool with Oracle LSH to view data without building a custom adapter. To use this adapter, you do not need to follow instructions in any section of this guide other than this chapter.
To integrate your visualization tool with Oracle LSH:
Use an Oracle LSH view to display, when a user logs in to the visualization tool, the Business Area instances to which the user has access; see Display User's Business Area Instances.
Use Oracle LSH APIs to allow the user to select appropriate blinding and currency settings; see Getting Possible Blinding Types of a Business Area Instance and Getting Snapshot Labels Common to All Tables in a BA Instance for a Given Blinding Access Type.
Use Oracle LSH APIs to initialize the user's selected Business Area instance with those settings and to reset as required; see Initializing the Business Area Instance and Resetting a Generic Visualization Business Area.
Use an Oracle LSH view to Retrieve Table Instance Details for the data you want to display.
To use the adapter, Definers create Business Areas of type Generic Visualization. When a Definer installs a Generic Visualization Business Area instance for the first time, the adapter creates a database schema exclusively for the Business Area instance. As with other Business Areas, data in Table instances mapped to the Business Area's Table Descriptors can be viewed in the visualization tool. Normally users log in directly to the visualization tool through its URL.
Note:
You do not need to define any service locations or service instances for this adapter.The adapter includes public APIs that you can call from the external visualization system.
For more information about using APIs, see the Oracle Life Sciences Data Hub Application Programming Interface Guide.
Use the API CDR_PUB_API_GVA.SETINITIALIZEBA to initialize a particular Generic Visualization Business Area instance with a given currency and blinding access type. This API also looks for an Oracle LSH user account linked to the database account with which the user logged in. If there is a linked user account, the API enforces the security privileges of the user account; if not, the API enforces the security privileges of the database account.
If the currency and the blinding access values are not set by the user, the API uses the default values set in the Business Area instance properties and the user's privileges to determine the data to display; see "Generic Visualization Business Area Instance Attributes" and "Generic Visualization Adapter Security".
Initializing a Business Area Instance Repeatedly in the Same Session You can invoke this API multiple times on the same Business Area instance to change the currency and blinding access types in a single user session.
Initializing Multiple Business Area Instances in the Same Session You can also invoke this API multiple times to allow a user to read data from multiple Business Area instances as long as the user views either real or dummy data across all Business Areas. The Real (BlindBreak) and Real (Unblinded) blinding access types are considered as reading real data while NA/Dummy is considered as reading dummy data.
If the user selects a blinding access type for a Business Area that is incompatible with the blinding access types selected for other Business Areas in the same session, the API errors out with the message, "There is a change in reading dummy data to blinded data or vice-versa. Please reset access to all Business Areas using resetBAAccess api and try again;" see "Resetting a Generic Visualization Business Area".
The following settings and combinations of settings work:
NA/Dummy blinding access type on all Business Areas: The user sees only dummy data in blinded Table instances.
Real (Unblinded) blinding access type on all Business Areas: The user sees unblinded data in all Business Areas. This option is available only if all the Business Area's Table instances whose Blinding flag is set to Yes have a Blinding Status of Unblinded.
Real (Blind Break) blinding access type on all Business Areas: The user sees currently blinded data in blinded Table instances in all Business Areas.
Real (Unblinded) and Real (Blind Break) blinding access types: The user sees unblinded data in Business Areas where this option is available and currently blinded data in others.
Note:
The user must always have the appropriate blinding-related privileges. Without them the user can see only dummy data in Table instances whose Blinding flag is set to Yes. Table instances whose blinding flag is set to No contain data that was never blinded (NA for Not Applicable) and is always available.
PROCEDURE SETINITILIZEBA(
PI_COMPANYID IN CDR_NAMINGS.COMPANY_ID%TYPE,
PI_OBJID IN CDR_NAMINGS.OBJ_ID%TYPE,
PI_OBJVER IN CDR_NAMING_VERSIONS.OBJ_VER%TYPE,
PI_VCURRENCY IN VARCHAR2,
PI_VBLINDINGACCESSTYPE IN VARCHAR2,
X_RETURN_STATUS OUT NOCOPY VARCHAR2,
X_MSG_COUNT OUT NOCOPY NUMBER,
X_MSG_DATA OUT NOCOPY VARCHAR2
Parameters This API has the following parameters:
PI_COMPANYID. Enter the Business Area instance's company ID.
PI_OBJID. Enter the Business Area instance's object ID.
PI_OBJVER. Enter the Business Area instance's object version.
PI_VCURRENCY. Enter the currency value. The allowed values are Current or any snapshot label common to all Table instances mapped to the Business Area's Table Descriptors.
PI_VBLINDINGACCESSTYPE. Enter the blinding access type. The allowed values are: NA/Dummy , Real(Unblinded), or Real(BlindBreak). Note that there is no space between Real and the parentheses/brackets.
Use public API CDR_PUB_API_GVA.RESETBAACCESS to clear all the initializations of Business Area schemas. It is equivalent to logging out and logging back in to the system.
This API has no parameters.
Users cannot select incompatible blinding access types for different Business Areas in the same session. If they do, the initialization API errors out with a message to call this API.
You may want to trap the Initialization API's error message and, if possible, display a dialog box warning the user that the blinding access type is incompatible with open Business Areas (or the visualization tool's equivalent) and give the user the following options:
Continue with the current setting, which will result in closing all other Business Areas. If the user selects this option, run the Reset API and then the Initialization API with the requested setting for the current Business Area.
Change the setting for the current Business Area to be compatible with those already open. If the user selects this option, run the Initialization API with the appropriate setting.
Alternatively, display the Initialization API's error message and provide a way in the UI to invoke the Reset API to close all open Business Areas. Or trap the Initialization API's error message, invoke the Reset API to close all open Business Areas, and display a message. In either case, the user can then select a Business Area and blinding access type as required.
You can allow users with the necessary privileges to specify if they want to view only nonblinded and dummy data, or data that includes unblinded or currently blinded data; see "Generic Visualization Adapter Security".
Use public API CDR_PUB_API_GVA.GETBAVALIDBLINDINGACCESSTYPES to get the possible blinding access types of a Business Area instance in the current session, based on the blinding statuses of underlying Business Area Table instances and the user's privileges.
Note:
The option to read unblinded data is available only if all relevant Table instancesâthat is, all Table instances that are mapped to the Business Area instance's Table Descriptors and have their Blinding Flag set to Yesâhave a Blinding Status of Unblinded.If you do not use the API or the user does not provide a selection, the system displays the data specified for the Business Area instance; see "Default Blinding Access Type".
FUNCTION GETBAVALIDBLINDINGACCESSTYPES(
PI_COMPANYID IN CDR_NAMINGS.COMPANY_ID%TYPE,
PI_OBJID IN CDR_NAMINGS.OBJ_ID%TYPE,
PI_OBJVER IN CDR_NAMING_VERSIONS.OBJ_VER%TYPE)
RETURN BLINDINGACCESSTYPESCOLL PIPELINED;
Return A collection (BLINDINGACCESSTYPESCOLL) of the possible blinding access types. The possible values are: NA/Dummy , Real(Unblinded), or Real(BlindBreak). Note that there is no space between Real and the parentheses/brackets.
Parameters This API has the following parameters:
PI_COMPANYID. Enter the Business Area instance's company ID.
PI_OBJID. Enter the Business Area instance's object ID.
PI_OBJVER. Enter the Business Area instance's object version.
BLINDINGACCESSTYPESCOLL. This is the list of possible blinding access types.
You can allow the user, on login, to choose to view current data or data based on a snapshot label. A snapshot label is available for selection only if all source Table instances have the same label applied. Table instances that are pass-through views can display only current data, so if one or more Table instance is a view, only current data will be available for the Business Area.
Use public API CDR_PUB_API_GVA.GETSNAPSHOTLABELS to get the snapshot labels common to all Table instances mapped to Table Descriptors in a single Business Area instance. The API has an input parameter for blinding access type because snapshot labels may be different for dummy and real data.
If you do not use the API or the user does not provide a snapshot label selection, the system displays the data currency specified for the Business Area; see "Default Currency".
FUNCTION GETSNAPSHOTLABELS(
PI_COMPANYID IN CDR_NAMINGS.COMPANY_ID%TYPE,
PI_OBJID IN CDR_NAMINGS.OBJ_ID%TYPE,
PI_OBJVER IN CDR_NAMING_VERSIONS.OBJ_VER%TYPE,
PI_VBLINDINGACCESSTYPE IN VARCHAR2)
RETURN CURRENCYCOLL PIPELINED;
Return A collection (CURRENCYCOLL) of the snapshot labels for a particular blinding access type in the Business Area instance common to all Tables within a Business Area Instance.
Parameters This API has the following parameters.
PI_COMPANYID. Enter the Business Area instance's company ID.
PI_OBJID. Enter the Business Area instance's object ID.
PI_OBJVER. Enter the Business Area instance's object version.
PI_VBLINDINGACCESSTYPE. Enter the blinding access type. The allowed values are: NA/Dummy , Real(Unblinded), or Real(BlindBreak). Note that there is no space between Real and the parentheses/brackets.
This section includes the following topics:
Use naming view CDR_PUB_GENERIC_BA_V to retrieve all the Generic Visualization Business Area instances on which a user has privileges to read data. You can use this view to build a hierarchy in the visualization tool's user interface that displays each Business Area instance to which the current user has access, in the context of its Work Area, Application Area, and Domain.
This effectively enforces security by allowing the user to select only Business Areas to which he or she has access.
For each Business Area, the view retrieves the following:
COMPANY_ID. NUMBER(6,0) The Business Area instance's company ID.
BA_OBJ_ID. NUMBER(22,0) The Business Area instance's object ID.
BA_OBJ_VER. NUMBER(7,0) The Business Area instance's object version.
BA_NAME. VARCHAR2(200) The Business Area instance's name.
SCHEMA_NAME. VARCHAR2(30) The Business Area instance's unique schema name.
BA_DESCRIPTION. VARCHAR2(2000) The Business Area instance's description, if any.
BA_STATUS_RC. VARCHAR2(30) The Business Area instance's status. The possible values are: $NAMING_STATUS$UPGRADEABLE or $NAMING_STATUS$NONINSTALLABLE. See the Oracle Life Sciences Data Hub Application Developer's Guide for more information.
BA_VALIDATION_STATUS_RC. VARCHAR2(30) The Business Area instance's validation status. The possible values are: $SYSVALDNSTEPS$DEVELOPMENT, $SYSVALDNSTEPS$PRODUCTION, $SYSVALDNSTEPS$QUALITYCONTROL, $SYSVALDNSTEPS$RETIRED.
BA_VERSION_LABEL. VARCHAR2(255) The Business Area instance version's label, if any.
WA_OBJ_ID. NUMBER(22,0) The Business Area instance's parent Work Area's object ID.
WA_OBJ_VER. NUMBER(7,0) The Business Area instance's parent Work Area's object version.
WORKAREA. VARCHAR2(4000) The Business Area instance's parent Work Area's name.
WA_VALIDATION_STATUS_RC. VARCHAR2(30) The Business Area instance's parent Work Area's validation status. The possible values are: $SYSVALDNSTEPS$DEVELOPMENT, $SYSVALDNSTEPS$PRODUCTION, $SYSVALDNSTEPS$QUALITYCONTROL, $SYSVALDNSTEPS$RETIRED.
APPLICATION_AREA. VARCHAR2(4000) The Work Area's parent Application Area's name.
DOMAIN. VARCHAR2(4000) The Application Area's parent Domain's name.
Note:
Multiple levels of Domains are not included in the hierarchy.BA_DEF_OBJ_ID. NUMBER(22,0) The Business Area definition's object ID.
BA_DEF_OBJ_VER. NUMBER(7,0) The Business Area definition's object version.
BA_DEF_NAME. VARCHAR2(200) The Business Area definition's name.
Use view CDR_PUB_GENERIC_BA_TABLES_V to retrieve the Table instance details for a given Generic Visualization Business Area instance in order to determine what data to display.
The view retrieves the following attributes for each mapped Business Area Table Descriptor and Table instance. See the Oracle Life Sciences Data Hub Application Developer's Guide for more information.
COMPANY_ID. NUMBER(6,0) The Table instance's company ID.
BA_OBJ_ID. NUMBER(22,0) The Business Area instance's object ID.
BA_OBJ_VER. NUMBER(7,0) The Business Area instance's object version.
BA_NAME. VARCHAR2(200) The Business Area instance's name.
TD_OBJ_ID. NUMBER(22,0) The Table Descriptor's object ID.
TD_OBJ_VER. NUMBER(7,0) The Table Descriptor's object version.
TD_NAME. VARCHAR2(200) The Table Descriptor's name.
TD_ORACLE_NAME. VARCHAR2(30) The Table Descriptor's Oracle name.
TD_SAS_NAME. VARCHAR2(32) The Table Descriptor's SAS name.
TI_OBJ_ID. NUMBER(22,0) The Table instance's object ID.
TI_OBJ_VER. NUMBER(7,0) The Table instance's object version.
TI_NAME. VARCHAR2(200) The Table instance's name.
BLINDING_FLAG_RC. VARCHAR2(30) The Table instance's Blinding flag setting. The possible values are: $YESNO$YES if the Table instance can contain blinded data or $YESNO$NO if it cannot.
BLINDING_STATUS_RC. VARCHAR2(30) The Table instance's Blinding status. See the Oracle Life Sciences Data Hub Application Developer's Guide for more information.
If the Table Instance's Blinding flag is set to $YESNO$YES, the possible values are: $BLIND_STATS$BLINDEDor $BLIND_STATS$UNBLINDED.
If the Table Instance's Blinding flag is set to $YESNO$NO, the possible values are: $BLIND_STATS$NOTAPPLICABLE or $BLIND_STATS$AUTHORIZED.
Business Area instances of type Generic Visualization have several attributes:
The Definer must enter a unique name for the schema of up to 30 characters. The value is stored in uppercase.
If a schema already exists in the Oracle LSH installation with the same name, the system automatically appends _n to the name, where n is 1 or the next higher integer if there is already a schema name your_name_1 or higher.
The first time the Definer installs the Business Area instance, the installation function creates a database schema with this name exclusively for the Business Area instance.
This setting controls the currency of data viewed by users if they do not explicitly make another selection. The default value is Current. If all the source Table instances mapped to the Business Area have same snapshot label(s) applied, the Definer can select a shared snapshot for users to see by default.
This setting controls the default blinding status of data available to users. Users' privileges also determine which data they can view. The Definer's own privileges determine which values he or she can set. The possible settings include:
NA/Dummy Allows users to see all data in Table instances whose Blinding flag is set to No and the dummy data in Table instances whose Blinding flag is set to Yes. If all Table instances mapped to Business Area Table Descriptors have their Blinding flag set to No, this is the only option available.
Real(Unblinded) If all Table instances whose Blinding flag is set to Yes have a Blinding status of Unblinded, and if the Definer has the Read(Unblind) Business Area Instance operation on the Business Area instance, the Definer can set the Default Blinding Access Type to this value. In these Table instances, users with the necessary privileges can see the real, unblinded data. Users without these privileges must explicitly select the NA/Dummy blinding access type or else they will not be able to see data in the Business Area at all. All users can see all data in Table instances whose Blinding flag is set to No.
Note:
The adapter can allow users with Blind Break privileges on all Table instances whose Blinding flag is set to Yes and whose Blinding Status is set to Blinded to select the Real (Blind Break) option, regardless of the Default Blinding Access Type. All blind breaks are audited.Security for the generic visualization adapter has several components:
You can use normal Oracle LSH security by assigning Oracle LSH user accounts to user groups and assigning user groups to Business Area instances, but if your users do not need Oracle LSH user accounts for other purposes, you can use simplified security requirements that apply only to Generic Visualization Business Area instances.
Users must log in using an Oracle LSH database account. Database accounts can have the following privileges directly assigned, either by the Business Area Definer with Manage BA DB privileges on the Business Area instance or by an Administrator:
Read Data allows the user to see nonblinded and dummy data. All database accounts to be used to access a Generic Visualization Business Area intance should have this privilege.
Read Unblind allows the user to see unblinded data.
Users who should be able to read data that was never blinded, dummy data in blinded Table instances and, optionally, data that has been unblinded, can log in using a database account that has the required privilege(s) directly assigned. They do not need an Oracle LSH user account.
Users who should be able to view currently blinded data must have their own Oracle LSH database account and a linked Oracle LSH user account with the privileges normally required for blind breaks, including:
LSH Data Blind Break User application role
Blind Break privileges on every Table instance whose Blinding Status is Blinded and that is mapped to one of the Business Area instance's Table Descriptors
The user account must be assigned to a user group that is assigned to the Business Area instance
When a user logs in, which requires an Oracle LSH database account, the Initialization API checks for a linked Oracle LSH user account. If there is one, the API uses that account's privileges to determine what data the user can view. If there is no linked Oracle LSH user account, the user has access only to the data to which the database account has access.
To assign privileges to database accounts in the Business Area instance user interface itself, the Definer selects Manage DB Privileges from the Actions drop-down. The security administrator can do the same for any Business Area instance in the Security user interface, BA DB Privilege Access tab. All the database accounts defined in the Oracle LSH instance are available for assignment.
See the Oracle Life Sciences Data Hub System Administrator's Guide for information on creating Oracle LSH user and database accounts and the Oracle Life Sciences Data Hub Implementation Guide for an explanation of Oracle LSH security.
To view data, users must have privileges on a particular Business Area instance. You can use a view to display for selection only the Business Area instances to which the current user has access; see "Display User's Business Area Instances".
During installation the system creates synonyms in the Business Area instance schema for all the Table Descriptors. The synonyms reference source views in the Work Area schema(s) containing the actual database tables corresponding to the Table instances mapped to the Table Descriptors. The source views enforce normal Oracle LSH security.
Note:
It is not necessary to have privileges on the Table instances mapped to the Business Area instance's Table Descriptors unless the user needs to be able to view currently blinded data.You can use APIs to determine the appropriate blinding and currency settings for the current session, based on the state of the data and the user's privileges, and allow the user to select only those settings; see "Getting Possible Blinding Types of a Business Area Instance" and "Getting Snapshot Labels Common to All Tables in a BA Instance for a Given Blinding Access Type".
The adapter audits several actions, recording each in internal tables as follows. You can log in as apps to see the audit trail for each.
CDR_BA_SCHEMA_ACCESS stores a record for each user access to a Business Area instance schema using the initialization API.
CDR_BLIND_BREAKS stores a record of each blind breaks (sessions where a privileged user views currently blinded data).
CDR_BA_DB_PRIVILEGES_A is the FND audit table for the CDR_BA_DB_PRIVILEGES, which stores the association between database accounts and Generic Visualization adapter privileges.
All the defined objects, from the Adapter Domain down, are shipped with Oracle LSH. As shown in Figure 5-1, "Generic Visualization Adapter Components" these include:
Adapter Domain VISUALIZATION_ADAPTER
Adapter Area GENERIC_VISUALIZATION; see Table 4-2, "Sample Adapter Area Settings" for its attribute values.
Program GENERIC_VISUALIZATION_RUNTIME_PROG contains a Source Code definition that includes a single function, the install_function, named CDR_GV_ADAPTER.INSTALL. This function is called whenever a Definer installs a Generic Visualization Business Area instance. It does the following:
If a schema does not exist for the Business Area instance, it creates the schema.
For each Table Descriptor in the Generic Visualization Business Area, it creates or upgrades (as required) a corresponding synonym in the schema that references a source view of the mapped Table instance in its Work Area schema.
If a previously created Business Area instance had a schema with the same name, but that Business Area instance has been deleted, the install function drops all the synonyms in the original schema and creates new ones for the new Business Area.
Work Area GENERIC_VISUALIZATION_WA containing an instance of the Program GENERIC_VISUALIZATION_RUNTIME_PROG. The Adapter Area Work Area is installed in its own Oracle LSH schema.
Technology Type GVA; see Table 4-1, "Sample Technology Type Settings" for its attribute values.
Note:
Generic Visualization Business Area instance attributes Schema Name, Default Currency, and Default Blinding Access Type are not stored in the define-time Parameter Set as in other adapters. They are stored in satellite table CDR_BUSINESS_AREA_REFS so that the public APIs can change their values.Figure 5-1 Generic Visualization Adapter Components
|
 Copyright © 2011, 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|