Oracle® Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition (Oracle Fusion Applications Edition) 11g Release 1 (11.1.1) Part Number E20836-01 |
|
|
PDF · Mobi · ePub |
You can use variables in a repository to streamline administrative tasks and dynamically modify metadata content to adjust to a changing data environment. There are two classes of variables: repository variables and session variables.
A repository variable has a single value at any point in time. There are two types of repository variables: static and dynamic.
Session variables are created and assigned a value when each user logs on. There are two types of session variables: system and nonsystem.
Initialization blocks are used to initialize dynamic repository variables, system session variables, and nonsystem session variables.
You can use the Variable Manager in the Administration Tool to define variables. The Variable Manager dialog has two panes. The left pane displays a tree that shows variables and initialization blocks, and the right pane displays details of the item you select in the left pane. Repository variables and system and nonsystem session variables are represented by a question mark icon. The icon for an initialization block is a cube labeled i.
Caution:
Values in repository and session variables are not secure, because object permissions do not apply to variables. Anybody who knows or can guess the name of the variable can use it in an expression in Answers or in a Logical SQL query. Because of this, do not put sensitive data like passwords in session or repository variables.This chapter contains the following topics:
A repository variable has a single value at any point in time. Repository variables can be used instead of literals or constants in Expression Builder in the Administration Tool. The Oracle BI Server substitutes the value of the repository variable for the variable itself in the metadata.
This section contains the following topics:
The value of a static repository variable is initialized in the Variable dialog. This value persists, and does not change until an administrator decides to change it.
For example, suppose you want to create an expression to group times of day into different day segments. If Prime Time were one of those segments and corresponded to the hours between 5:00 PM and 10:00 PM, you could create a CASE
statement like the following:
CASE WHEN "Hour" >= 17 AND "Hour" < 23 THEN 'Prime Time' WHEN... ELSE...END
where Hour is a logical column, perhaps mapped to a timestamp physical column using the date-and-time Hour(<<timeExpr>>)
function.
Rather than entering the numbers 17 and 23 into this expression as constants, you could use the Variable tab of the Variable dialog to set up a static repository variable named prime_begin
and initialize it to a value of 17
, and create another variable named prime_end
and initialize it to a value of 23
.
Static repository variables must have default initializers that are either numeric or character values. In addition, you can use Expression Builder to insert a constant as the default initializer, such as Date, Time, and TimeStamp. You cannot use any other value or expression as the default initializer for a static repository variable.
In previous releases, the Administration Tool did not limit the values of default initializers for static repository variables. Because of this, if your repository has been upgraded from a previous release, you may see warnings in the Consistency Checker similar to the following:
The variable, 'Current Month' does not have a constant default initializer.
If you see warnings similar to this, update the relevant static repository variables so that the default initializers have constant values.
You initialize dynamic repository variables in the same way as static variables, but the values are refreshed by data returned from queries. When defining a dynamic repository variable, you create an initialization block or use a preexisting one that contains a SQL query. You also set up a schedule that the Oracle BI Server will follow to execute the query and periodically refresh the value of the variable.
When the value of a dynamic repository variable changes, all cache entries associated with a business model that reference the value of that variable are purged automatically.
Each query can refresh several variables: one variable for each column in the query. You schedule these queries to be executed by the Oracle BI Server.
Dynamic repository variables are useful for defining the content of logical table sources. For example, suppose you have two sources for information about orders. One source contains recent orders and the other source contains historical data.
You need to describe the content of these sources on the Content tab of the Logical Table Source dialog. Without using dynamic repository variables, you would describe the content of the source containing recent data with an expression such as:
Orders.OrderDates."Order Date" >= TIMESTAMP '2001-06-02 00:00:00'
This content statement becomes invalid as new data is added to the recent source and older data is moved to the historical source. To accurately reflect the new content of the recent source, you would have to modify the fragmentation content description manually. Dynamic repository values can be set up to do it automatically.
Another suggested use for dynamic repository values is in WHERE
clause filters of logical table sources, defined on the Content tab of the Logical Table Source dialog.
A common use of these variables is to set filters for use in Oracle BI Presentation Services. For example, to filter a column on the value of the dynamic repository variable CurrentMonth, set the filter to the variable CurrentMonth.
This section explains how to create repository variables.
To create a repository variable:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, select Action > New > Repository > Variable.
In the Variable dialog, type a name for the variable.
Names for all variables should be unique. The names of system session variables are reserved and cannot be used for other types of variables.
Select the type of variable: Static or Dynamic.
If you selected Dynamic, use the Initialization Block list to select an existing initialization block that will be used to refresh the value on a continuing basis.
To create a new initialization block, click New. See "Creating Initialization Blocks" for more information.
To add a Default initializer value, type the value in the Default initializer box, or click the Expression Builder button to use Expression Builder.
For static repository variables, the value you specify in the Default initializer window persists. It will not change unless you change it. If you initialize a variable using a character string, enclose the string in single quotes ( ' ). Static repository variables must have default initializers that are constant values.
Click OK.
After they are created, variables are available for use in Expression Builder. In Expression Builder, click the Repository Variables folder in the left pane to display all repository variables (both static and dynamic) in the middle pane by name.
To use a repository variable in an expression, select it and double-click. Expression Builder pastes it into the expression at the active cursor insertion point.
Variables should be used as arguments of the function VALUEOF()
. This happens automatically when you double-click the variables to paste them into the expression.
For example, the following CASE
statement is identical to the one explained in the preceding example, except that variables have been substituted for the constants:
CASE WHEN "Hour" >= VALUEOF("prime_begin")AND "Hour" < VALUEOF("prime_end") THEN 'Prime Time' WHEN ... ELSE...END
Note:
You cannot use variables to represent columns or other repository objects.Session variables are similar to dynamic repository variables in that they obtain their values from initialization blocks. Unlike dynamic repository variables, however, the initialization of session variables is not scheduled. When a user begins a session, the Oracle BI Server creates new instances of session variables and initializes them.
Unlike a repository variable, there are as many instances of a session variable as there are active sessions on the Oracle BI Server. Each instance of a session variable could be initialized to a different value.
Session variables are primarily used when authenticating users against external sources such as database tables or LDAP servers. If a user is authenticated successfully, session variables can be used to set filters and permissions for that session. For information about using session variables when setting up security, see "Managing Session Variables" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.
This section contains the following topics:
System session variables are session variables that the Oracle BI Server and Oracle BI Presentation Services use for specific purposes. System session variables have reserved names that cannot be used for other kinds of variables (such as static or dynamic repository variables and nonsystem session variables).
When you use these variables for Oracle BI Presentation Services, preface their names with NQ_SESSION
. For example, to filter a column on the value of the variable LOGLEVEL
, set the filter to the variable NQ_SESSION.LOGLEVEL
.
Table 18-1 describes the available system session variables.
Table 18-1 System Session Variables
Variable | Description |
---|---|
Holds the value the user enters as his or her logon name. This variable is typically populated from the LDAP profile of the user. |
|
Holds the name of the proxy user. A proxy user is a user that has been authorized to act for another user. See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for more information about the PROXY system session variable. |
|
Contains the groups to which the user belongs. Exists only for compatibility with previous releases. Legacy groups are mapped to application roles automatically. |
|
Specifies the Catalog groups (Presentation Services groups) to which the user belongs, if any. Note that the recommended practice is to use application roles rather than Catalog groups. |
|
Contains the global unique identifier (GUID) of the user, typically populated from the LDAP profile of the user. |
|
Contains the application roles to which the user belongs. |
|
Contains the global unique identifiers (GUIDs) for the application roles to which the user belongs. GUIDs for application roles are the same as the application role names. |
|
Contains the permissions held by the user, such as oracle.bi.server.impersonateUser or oracle.bi.server.manageRepositories. |
|
Used for Oracle BI Presentation Services. It contains the name that is displayed to the user in the greeting in the Oracle BI Presentation Services user interface. It is also saved as the author field for catalog objects. This variable is typically populated from the LDAP profile of the user. |
|
Used for Oracle BI Presentation Services. It identifies the default dashboard the user sees when logging in (the user can override this preference after logged on). |
|
The value of This system session variable overrides a variable defined in the Users object in the Administration Tool. If the administrator user (defined upon install) has a Logging level defined as 4 and the session variable |
|
Used for Oracle BI Presentation Services. Any users with the same nonblank request key share the same Oracle BI Presentation Services cache entries. This tells Oracle BI Presentation Services that these users have identical content filters and security in the Oracle BI Server. Sharing Oracle BI Presentation Services cache entries is a way to minimize unnecessary communication with the Oracle BI Server. |
|
Determines certain elements of the look and feel of the Oracle BI Presentation Services user interface. The user can alter some elements of the user interface by picking a style when logged on to Oracle BI Presentation Services. The |
|
Contains a description of the user, typically populated from the LDAP profile of the user. |
|
Contains the locale of the user, typically populated from the LDAP profile of the user. |
|
Used to enable or disable Oracle BI Server result cache hits. This variable has a possible value of 0 or 1. |
|
Used to enable or disable Oracle BI Server result cache seeding. This variable has a possible value of 0 or 1. |
|
Used to enable or disable Oracle BI Server subrequest cache hits and seeding. This variable has a possible value of 0 or 1. |
|
Identifies the query as a SELECT_PHYSICAL query. See "Syntax and Usage Notes for SELECT_PHYSICAL" for more information. |
|
Used to enable or disable Oracle BI Server plan cache hits. This variable has a possible value of 0 or 1. |
|
Used to enable or disable Oracle BI Server plan cache seeding. This variable has a possible value of 0 or 1. |
|
Contains the time zone of the user, typically populated from the LDAP profile of the user. |
You use the same procedure to define nonsystem session variables as for system session variables.
A common use for nonsystem session variables is setting user filters. For example, you could define a nonsystem variable called SalesRegion that would be initialized to the name of the sales region of the user.
You could then set a security filter for all members of a group that would allow them to view only data pertinent to their region.
When you use these variables for Oracle BI Presentation Services, preface their names with NQ_SESSION
. For example, to filter a column on the value of the variable SalesRegion
, set the filter to the variable NQ_SESSION.SalesRegion
.
This section explains how to create session variables.
To create a session variable:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, select Action > New > Session > Variable.
In the Session Variable dialog, type a variable name.
Names for all variables should be unique. The names of system session variables are reserved and cannot be used for other types of variables.
For session variables, you can select the following options:
Enable any user to set the value. Select this option to set session variables after the initialization block has populated the value (at user login) by calling the ODBC store procedure NQSSetSessionValue()
. For example, this option lets non-administrators to set this variable for sampling.
Security Sensitive. Select this option to identify the variable as sensitive to security when using a row-level database security strategy, such as a Virtual Private Database (VPD). When filtering cache table matches, the Oracle BI Server looks at the parent database object of each column or table that is referenced in the logical request projection list. If the database object has the Virtual Private Database option selected, the Oracle BI Server matches a list of security-sensitive variables to each prospective cache hit. Cache hits would only occur on cache entries that included and matched all security-sensitive variables.
Use the Initialization Block list to select an initialization block that will be used to refresh the value on a continuing basis.
To create a new initialization block, click New. See "Creating Initialization Blocks" for more information.
To add a Default Initializer value, type the value in the Default Initializer box, or click the Expression Builder button to use Expression Builder.
Click OK.
Initialization blocks are used to initialize dynamic repository variables, system session variables, and nonsystem session variables. For example, the NQ_SYSTEM
initialization block is used to refresh system session variables.
This section contains the following topics:
An initialization block contains the SQL statement that will be executed to initialize or refresh the variables associated with that block. The SQL statement must reference physical tables that can be accessed using the connection pool specified in the Connection Pool field in the Initialization Block dialog.
If you want the query for an initialization block to have database-specific SQL, you can select a database type for that query. If a SQL initialization string for that database type has been defined when the initialization block is instantiated, this string is used. Otherwise, a default initialization SQL string is used.
Caution:
By default, when you open the Initialization Block dialog for editing in online mode, the initialization block object is automatically checked out. While the initialization block is checked out, the Oracle BI Server may continue to refresh the value of dynamic variables refreshed by this initialization block, depending on the refresh intervals that are set. When you check in the initialization block, the value of the dynamic variables is reset to the values shown in the Default initializer. If you do not want this to occur, use the Undo Check Out option.This section contains the following topics:
The values of dynamic repository variables are set by queries defined in the Default initialization string field of the Initialization Block dialog. You also set up a schedule that the Oracle BI Server will follow to execute the query and periodically refresh the value of the variable. If you stop and restart the Oracle BI Server, the server automatically executes the SQL statements in repository variable initialization blocks, reinitializing the repository variables.
The Oracle BI Server logs all SQL queries issued to retrieve repository variable information in nqquery.log when the logging level for the administrator account (set upon installation) is set to 2 or higher. You should set the logging level to 2 for the administrator to provide the most useful level of information. You can find the nqquery.log file in:
ORACLE_INSTANCE\diagnostics\logs\OracleBIServerComponent\coreapplication_obisn
For more information about user-level logging, see "Managing the Query Log" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
As with dynamic repository variables, session variables obtain their values from initialization blocks. Unlike dynamic repository variables, session variables are not updated at scheduled time intervals. Instead, the Oracle BI Server creates new instances of those variables whenever a user begins a new session. The values remain unchanged for the duration of the session.
Execution of session variable initialization blocks during session logon can be deferred until their associated session variables are actually accessed within the session. See "Creating Initialization Blocks" for more information.
The Oracle BI Server logs all SQL queries issued to retrieve session variable information if the logging level is set to 2 or higher in the Identity Manager User object, or the LOGLEVEL
system session variable is set to 2 or higher in the Variable Manager.
The default location for the nqquery.log file is:
ORACLE_INSTANCE\diagnostics\logs\OracleBIServerComponent\coreapplication_obisn
For more information about user-level logging, see "Managing the Query Log" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
You can use the row-wise initialization option to create session variables dynamically and set their values when a session begins. The names and values of the session variables reside in an external database that you access through a connection pool. The variables receive their values from the initialization string that you type in the Initialization Block dialog.
For example, suppose you want to create session variables using values contained in a table named RW_SESSION_VARS
. The table contains three columns:
USERID
, containing values that represent the unique identifiers of the users
NAME
, containing values that represent session variable names
VALUE
, containing values that represent session variable values
Table 18-2 shows the table in this example.
Table 18-2 Sample Session Variables Database Table
USERID | NAME | VALUE |
---|---|---|
JOHN |
LEVEL |
4 |
JOHN |
STATUS |
FULL-TIME |
JANE |
LEVEL |
8 |
JANE |
STATUS |
FULL-TIME |
JANE |
GRADE |
AAA |
To use row-wise initialization, create an initialization block and select the Row-wise initialization option (refer to "Creating Initialization Blocks"). For this example, you would provide the following SQL statement for the initialization string:
SELECT NAME, VALUE FROM RW_SESSION_VARS WHERE USERID='VALUEOF(NQ_SESSION.USERID)'
Note that NQ_SESSION.USERID
has already been initialized using another initialization block.
The following session variables would be created:
When John connects to the Oracle BI Server, his session contains two session variables from row-wise initialization: LEVEL
, containing the value 4
, and STATUS
, containing the value FULL_TIME
.
When Jane connects to the Oracle BI Server, her session contains three session variables from row-wise initialization: LEVEL
, containing the value 8
; STATUS
, containing the value FULL-TIME
; and GRADE
, containing the value AAA
.
You can also use the row-wise initialization option to initialize a variable with a list of values. You can then use the SQL IN
operator to test for values in a specified list.
For example, using the table values in the previous example, you would type the following SQL statement for the initialization string:
SELECT 'LIST_OF_USERS', USERID FROM RW_SESSION_VARS WHERE NAME='STATUS' AND VALUE='FULL-TIME'
This SQL statement populates the variable LIST_OF_USERS
with a list, separated by colons, of the values JOHN
and JANE
(for example, JOHN:JANE
). You can then use this variable in a filter, as shown in the following WHERE
clause:
WHERE TABLE.USER_NAME = valueof(NQ_SESSION.LIST_OF_USERS)
The variable LIST_OF_USERS
contains a list of values, that is, one or more values. This logical WHERE
clause expands into a physical IN
clause, as shown in the following statement:
WHERE TABLE.USER_NAME IN ('JOHN', 'JANE')
See "About Using Initialization Blocks with Variables" for more information about initialization blocks.
To create initialization blocks, perform the steps in the following sections:
For repository variables, you can specify the day, date, and time for the start date, as well as a refresh interval.
To assign a name and schedule to initialization blocks:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, from the Action menu, choose New > Repository (or Session) > Initialization Block.
In the [Repository|Session] Variable Initialization Block dialog, type a name for the block. (The NQ_SYSTEM
initialization block name is reserved.)
(Repository initialization blocks only) In the Schedule area, select a start date and time and the refresh interval.
(Session init blocks only) Select the following options when appropriate:
Disabled. If you select this option, the initialization block is disabled.
You can also right-click an existing initialization block in the Variable Manager and choose Disable or Enable. This option enables you to change this property without opening the initialization block dialog.
Allow deferred execution. If you select this option, execution of the initialization block is deferred until an associated session variable is accessed for the first time during the session.
This option prevents execution of all session variable initialization blocks during the session logon stage, giving a shorter logon time. Session variables that are not needed during the session do not have their initialization blocks executed. This saves the resources which would have been used to execute these unnecessary initialization blocks.
The deferred execution of an initialization block also triggers the execution of all unexecuted predecessor initialization blocks. All associated variables of the initialization block and its unexecuted predecessors are updated with the values returned from the deferred execution.
Note: The Allow deferred execution option is unavailable in some circumstances. See "When Execution of Session Variable Initialization Blocks Cannot Be Deferred" for more information.
Required for authentication. If you select this option, this initialization block must succeed for users to log in. In other words, users are denied access to Oracle Business Intelligence if the initialization block fails to execute. Failure to execute can occur if the wrong credentials have been defined in the initialization block, or if there is an error in the default initialization string.
Note that this requirement is waived for internal processes (like Delivers) that use impersonation, if a single user session variable has been associated with the initialization block. In this case, the trusted internal process can connect regardless of whether the initialization block succeeds or fails.
The next step is to select the data source and connection pool.
If you select Database as the data source type for an initialization block, the values returned by the database for the columns in your SQL statement are assigned to variables that you associate with the initialization block. For session variable initialization blocks, you can also select LDAP Server or Custom Authenticator.
It is recommended that you create a dedicated connection pool for initialization blocks where you select Database as the data source type. See "About Connection Pools for Initialization Blocks" for more information.
If you select Database as the data source type:
If you select Database as the data source type, and do not select the Use OBI EE Server option
The SQL statement used to refresh the variable must reference physical tables that can be accessed through the connection pool specified in the Connection Pool field. The tables do not have to be included in the Physical layer of the metadata. At run time, if an initialization string for the database type has been defined, this string is used. Otherwise, the default initialization SQL for the database type is used. You can overtype this string.
When you create SQL and submit it directly to the database (for example, when using database-specific SQL in initialization blocks), the SQL statement bypasses the Oracle BI Server. The order of the columns in the SQL statement and the order of the variables associated with the initialization block determine which columns are assigned to each variable.
You should test this SQL using the Test button in the [Repository|Session] Variable Initialization Block Data Source dialog. If the SQL statement contains an error, the database returns an error message. See "Testing Initialization Blocks" for more information.
If you select Database as the data source type, and select the Use OBI EE Server option
The SQL statement you use to refresh the variable might be written for a specific database. However, it will still work with other data sources because the SQL statement is processed by the Oracle BI Server. The Oracle BI Server can also provide functions (such as PI
) that might not be available in the data source, and the SQL statement will work with other data sources supported by the Oracle BI Server (for example, ADF, SQL Server, Oracle, and XML files). When you select the Use OBI EE Server option, there is no need for a connection pool, because the SQL statement is sent to the Oracle BI Server and not directly to the underlying database.
You can only test this SQL statement using the Test button in the [Repository|Session] Variable Initialization Block Data Source dialog when in online mode. If the SQL statement contains an error, the database returns an error message. See "Testing Initialization Blocks" for more information.
To select a data source and connection pool for initialization blocks:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, double-click the initialization block you want to edit. You can edit Repository initialization blocks, or Session initialization blocks.
Click Edit Data Source next to the Connection Pool field.
From the Data Source Type list, select one of the following types.
Database: For repository and session variables.
LDAP Server: For session variables.
Custom Authenticator: For session variables. See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for more information.
If you selected Database for your data source type, perform one of the following steps:
Select Default initialization string or Use database specific SQL, and then perform the following steps:
Click Browse next to the Connection Pool field to select the connection pool associated with the database where the target information is located. If you do not select a connection pool before typing the initialization string, you receive a message prompting you to select the connection pool.
In the Select Connection Pool dialog, select the connection pool and click Select. You must select a connection pool before typing an initialization string.
By default, the first connection pool under the database object in the Physical layer is not available for selection. This behavior ensures that you cannot use the same connection pool for initialization blocks that you use for queries. See "About Connection Pools for Initialization Blocks" for more information
You can change this behavior so that the first connection pool is available for selection by selecting Allow first Connection Pool for Init Blocks in the Options dialog, although this is not recommended. See "Setting Preferences" for more information.
If you selected Use database specific SQL, then in the Database pane, expand and select the database. Then, enter its associated string.
Otherwise, in the Default initialization string box, type the SQL initialization string needed to populate the variables. See "Examples of Initialization Strings" for examples.
(Optional) Click Test to test the data source connectivity for the SQL statement.
Click OK to return to the Initialization Block dialog.
Select Use OBI EE Server, and then perform the following steps:
In the box, enter the SQL initialization string needed to populate the variables.
The string you enter here is processed by the Oracle BI Server, and therefore as long as it is supported by the Oracle BI Server, the string will work with different data sources.
For example, an initialization block might use the function pi()
, which is specific to SQL Server. However, if you select Use OBI EE Server, the query is rewritten by the Oracle BI Server for the appropriate database. In other words, if you change the SQL Server back-end database to Oracle, the query will still work.
See "Examples of Initialization Strings" for additional examples.
Click OK to return to the Initialization Block dialog.
If you selected LDAP Server for your data source type, perform the following steps:
Click Browse to select an existing LDAP Server, or click New to open the General tab of the LDAP Server dialog and create an LDAP Server.
Click OK to return to the Initialization Block dialog.
The LDAP server name and the associated domain identifier appear in the Name and Domain identifier columns.
If you selected Custom Authenticator for your data source type, perform the following steps:
Click Browse to select an existing custom authenticator, or click New to create one.
Click OK to return to the Initialization Block dialog.
Click OK.
This section contains the following initialization string examples:
Example 18-1 A SQL Statement When Site Uses Delivers
SELECT username, groupname, dbname, schemaname FROM users WHERE username=':USER' NQS_PASSWORD_CLAUSE(and pwd=':PASSWORD')NQS_PASSWORD_CLAUSE
This SQL contains two constraints in the WHERE
clause:
':USER'
(note the colon and single quotes) is the ID the user types when logging in.
':PASSWORD'
(note the colon and single quotes) is the password the user enters. This is another system variable whose presence is always assumed when the USER
system session variable is used. You do not need to set up the PASSWORD
variable, and you can use this variable in a database connection pool to allow passthrough login using the user ID and password of the user. You can also use this variable in a SQL statement.
When using external table authentication with Delivers, the portion of the SQL statement that makes up the :PASSWORD
constraint must be embedded between NQS_PASSWORD_CLAUSE
clauses.
The query returns data only if the user ID and password match values found in the specified table. You should test the SQL statement outside of the Oracle BI Server, substituting valid values for the USER
and PASSWORD
variables and removing the NQS_PASSWORD_CLAUSE
clause.
For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
Example 18-2 A SQL Statement When Site Does Not Use Delivers
SELECT username, groupname, dbname, schemaname FROM users WHERE username=':USER' AND pwd=':PASSWORD'
This SQL statement contains two constraints in the WHERE
clause:
':USER'
(note the colon and the single quotes) is the ID the user types when logging in.
':PASSWORD'
(note the colon and the single quotes) is the password the user enters. This is another system variable whose presence is always assumed when the USER
system session variable is used. You do not need to set up the PASSWORD
variable, and you can use this variable in a database connection pool to allow passthrough login using the user ID and password of the user. You can also use this variable in a SQL statement.
The query returns data only if the user ID and password match values found in the specified table. You should test the SQL statement outside of the Oracle BI Server, substituting valid values for the USER
and PASSWORD
variables.
Example 18-3 A SQL Statement Joining Tables From Multiple Data Sources - When Using the 'OBI EE Server' Setting
select WUSER.name, wuser_detail.email from "db-11g/orcl"."NAME"."WUSER', "sqlexpress"."master"."dbo"."wuser_detail" where username=:USER:
The above query example in the initialization block uses a join query with multiple tables from different data sources (for example, SQLServer, Oracle and XML Files). The query works because when you select the Use OBI EE Server option, the query is rewritten by the BI Server for the specified data sources.
You should test the SQL statement using the Test button or a SQL tool such as the Oracle BI Client utility. If you use a SQL tool, be sure to use the same DSN or one set up identically to the DSN in the specified connection pool.
In online mode, Initialization Block tests do not work with connection pools set to use :USER
and :PASSWORD
as the user name and password. In offline mode, the Set values for variables dialog is displayed so that you can populate :USER
and :PASSWORD
.
To test initialization blocks (optional):
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, double-click the initialization block.
In the [Repository|Session] Variable Initialization Block dialog, click Edit Data Source.
In the [Repository|Session] Variable Initialization Block Data Source dialog, click Test.
Note: The Test button is disabled when the Use OBI EE Server option is selected in offline mode.
In the Set value for the variables dialog, verify the information is correct, and then click OK.
In the View Data from Table dialog, type the number of rows and the starting row for your query, and then click Query.
The Results dialog lists the variables and their values.
The next step is to associate variables with the initialization block.
The SQL SELECT
statement in the Default initializer list can contain multiple columns. The order of the columns in the SQL statement and order of the variables associated with the initialization block determine the column value that is assigned to each variable. Therefore, when you associate variables with an initialization block, the value returned in the first column is assigned to the first variable in the list.
For repository variable initialization blocks, when you open a repository in online mode, the value shown in the Default initialization string field of the Initialization Block dialog is the current value of that variable as known to the Oracle BI Server. The number of associated variables can be different from the number of columns being retrieved. If there are fewer variables than columns, extra column values are ignored. If there are more variables than columns, the additional variables are not refreshed (they retain their original values, whatever they may be). Any legal SQL can be executed using an initialization block, including SQL that writes to the database or alters database structures, assuming the database permits the user ID associated with the connection pool to perform these actions.
If you stop and restart the Oracle BI Server, the server automatically executes the SQL statement in the repository variable initialization blocks, re-initializing the repository variables.
For session variable initialization blocks, you can select Row-wise initialization. The Use caching option is automatically selected when you select the Row-wise initialization option. Selecting the Use caching option directs the Oracle BI Server to store the results of the query in a main memory cache. See "About Row-Wise Initialization" for more information.
The Oracle BI Server uses the cached results for subsequent sessions. This can reduce session startup time. However, the cached results might not contain the most current session variable values. If every new session needs the most current set of session variables and their corresponding values, you should clear this option.
See "About Using Initialization Blocks with Variables" for more information.
To associate variables with initialization blocks:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, double-click the initialization block you want to edit. You can edit repository initialization blocks, or session initialization blocks.
Click Edit Data Target.
In the [Repository|Session] Variable Initialization Block Variable Target dialog, perform one of the following steps:
Associate variables with the initialization block by doing one of the following:
Click New, and in the Variable dialog, create a new variable. See "Creating Repository Variables" or "Creating Session Variables" for information about creating variables.
Click Link to associate an existing variable with an initialization block. Then, in the Browse dialog, select the variable to be refreshed by this initialization block and click OK.
Note:
For the Custom Authenticator data source type (Session variables only), the variableUSER
is required.Select Row-wise initialization. This option is for session variable initialization blocks only. See "About Row-Wise Initialization" for more information. If you select Row-wise initialization, the Use caching option becomes available.
To reorder variables, select a variable and click Up or Down.
To remove a variable from association with this block, select the variable and click Remove.
Click OK.
The next step is to establish execution precedence.
When a repository has multiple initialization blocks, you can set the order (establish the precedence) in which the blocks will be initialized.
First, you open the block that you want to be executed last and then add the initialization blocks that you want to be executed before the block you have open. For example, suppose a repository has two initialization blocks, A and B. You open initialization block B, and then specify that block A will execute before block B. This causes block A to execute according to block B's schedule, in addition to its own.
To establish execution precedence:
In the Administration Tool, select Manage, then select Variables.
In the Variable Manager dialog, double-click the last initialization block that you want to be initialized.
In the [Repository|Session] Variable Initialization Block dialog, click Edit Execution Precedence.
In the [Repository|Session] Variable Initialization Block Execution Precedence dialog, click Add.
Add is only available if there are initialization blocks that have not yet been selected.
In the Browse dialog, select the blocks that should be initialized before the block that you have open, and then click OK.
To remove a block, in the [Repository|Session] Variable Initialization Block Execution Precedence dialog, select the block you want to remove and click Remove.
Click OK.
If you want the initialization block to be required, in the [Repository|Session] Variable Initialization Block dialog, select the Required for authentication option.
Click OK.
Note:
When you select the Use OBI EE Server option for an initialization block:Execution precedence does not apply, because during user login, an initialization block with the Use OBI EE Server option selected is executed after initialization blocks with the Use OBI EE Server option not selected.
The Required for authentication option is dimmed, because this type of initialization block is executed after authentication.
Execution of session variable initialization blocks cannot be deferred in some circumstances, including when row-wise initialization is being used and when the Required for authentication option has been selected. When the execution of session variable initialization blocks cannot be deferred, a message is displayed that explains why. See "Assigning a Name and Schedule to Initialization Blocks" for more information.
The following list summarizes the scenarios in which execution of session variable initialization blocks cannot be deferred:
The Row-wise initialization option is selected in the Session Variable Initialization Block Variable Target dialog
Example message: "The execution of init block 'A_blk' cannot be deferred as it is using row-wise initialization."
The Required for authentication option is selected in the Session Variable Initialization Block dialog.
Example message: "The execution of init block 'A_blk' cannot be deferred as it is required for authentication."
The Data Source Type is not Database.
Example message: "The execution of init block 'A_blk' cannot be deferred as it does not have a connection pool."
The initialization block is used by session variables named PROXY
or USER
.
Example message: "The execution of init block 'A_blk' cannot be deferred as it is used by session variable 'PROXY'."
The initialization block is used by session variables where the Security Sensitive option is selected in the Session Variable dialog.
Example message: "The execution of init block 'A_blk' cannot be deferred as it is used by session variable 'A' which is security sensitive."
The initialization block is a predecessor to another initialization block which does not have the Allow deferred execution option selected.
Example message: "One of the successors for init block 'A_blk' does not have "Allow deferred execution" flag set. Init block 'B_blk' does not have "Allowed deferred execution" flag set.
You can use the Variable Manager in the Administration Tool to enable and disable initialization blocks.
To enable or disable an initialization block:
In the Administration Tool, select Manage, then select Variables. The Variable Manager appears.
In the left pane, select Initialization Blocks under Repository or Session, depending on whether you want to enable or disable repository initialization blocks or session initialization blocks.
In the right pane, right-click the initialization block you want to enable or disable.
Choose Enable or Disable from the right-click menu.
Close the Variable Manager and save the repository.