19 Using Variables in the Oracle BI Repository

This chapter describes how to use variables in the Oracle BI 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.

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:

Working with Repository Variables

This section provides information about working with repository variables, and contains the following topics:

About Repository Variables

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:

About Static Repository Variables

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.

About Dynamic Repository Variables

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.

Creating Repository Variables

This section explains how to create repository variables.

To create a repository variable:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, select Action > New > Repository > Variable.

  3. 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.

  4. Select the type of variable: Static or Dynamic.

  5. 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.

  6. 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.

  7. Click OK.

Using Repository Variables in Expression Builder

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.

Working with Session Variables

This section provides information about working with session variables, and contains the following topics:

About Session Variables

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:

About System Session Variables

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 19-1 describes the available system session variables.

Table 19-1 System Session Variables

Variable Description

USER

Holds the value the user enters as his or her logon name. This variable is typically populated from the LDAP profile of the user.

USERGUID

Contains the global unique identifier (GUID) of the user, typically populated from the LDAP profile of the user.

GROUP

Contains the groups to which the user belongs. Exists only for compatibility with previous releases. Legacy groups are mapped to application roles automatically.

When a user belongs to multiple groups, include the group names in the same column, separated by semicolons (for example, GroupA;GroupB;GroupC). If a semicolon must be included as part of a group name, precede the semicolon with a backslash character (\).

ROLES

Contains the application roles to which the user belongs.

When a user belongs to multiple roles, include the role names in the same column, separated by semicolons (for example, RoleA;RoleB;RoleC). If a semicolon must be included as part of a role name, precede the semicolon with a backslash character (\).

ROLEGUIDS

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.

PERMISSIONS

Contains the permissions held by the user, such as oracle.bi.server.manageRepositories.

PROXY

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.

WEBGROUPS

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.

When a user belongs to multiple Catalog groups, include the Catalog group names in the same column, separated by semicolons (for example, WebgroupA;WebgroupB;WebgroupC). If a semicolon must be included as part of a Catalog group name, precede the semicolon with a backslash character (\).

DISPLAYNAME

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.

LOGLEVEL

The value of LOGLEVEL (a number between 0 and 5) determines the logging level that the Oracle BI Server uses for user queries.

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 LOGLEVEL defined in the repository has a value of 0 (zero), the value of 0 applies.

DESCRIPTION

Contains a description of the user, typically populated from the LDAP profile of the user.

USERLOCALE

Contains the locale of the user, typically populated from the LDAP profile of the user.

DISABLE_CACHE_HIT

Used to enable or disable Oracle BI Server result cache hits. This variable has a possible value of 0 or 1.

DISABLE_CACHE_SEED

Used to enable or disable Oracle BI Server result cache seeding. This variable has a possible value of 0 or 1.

DISABLE_SUBREQUEST_CACHE

Used to enable or disable Oracle BI Server subrequest cache hits and seeding. This variable has a possible value of 0 or 1.

SELECT_PHYSICAL

Identifies the query as a SELECT_PHYSICAL query. See "Syntax and Usage Notes for SELECT_PHYSICAL" for more information.

DISABLE_PLAN_CACHE_HIT

Used to enable or disable Oracle BI Server plan cache hits. This variable has a possible value of 0 or 1.

DISABLE_PLAN_CACHE_SEED

Used to enable or disable Oracle BI Server plan cache seeding. This variable has a possible value of 0 or 1.

TIMEZONE

Contains the time zone of the user, typically populated from the LDAP profile of the user.

WEBLANGUAGE

Used for Oracle BI Presentation Services. Holds the Oracle BI Presentation Services user interface display language. Users can select a language on the sign-in page for Oracle BI EE, or they can change the language setting on the Preferences tab of the My Account dialog after signing in.

AUTHINITBLOCKONLY

Determines if the initialization blocks required for authentication are executed. This variable has a value of Yes. The value is case-insensitive.

PORTALPATH

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).

REQUESTKEY

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.

SKIN

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 SKIN variable points to an Oracle BI Presentation Services folder that contains the nonalterable elements (for example, figures such as GIF files). Such directories begin with sk_. For example, if a folder were called sk_companyx, the SKIN variable would be set to companyx.


About Nonsystem Session Variables

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.

Creating Session Variables

This section explains how to create session variables.

To create a session variable:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, select Action > New > Session > Variable.

  3. 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.

  4. 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 stored procedure NQSSetSessionValue(). For example, this option lets non-administrators to set this variable for sampling.

      Note that the NQSSetSessionValues() stored procedure is not supported for use through the Issue SQL page in Oracle BI Presentation Services Administration.

    • 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.

  5. 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.

  6. To add a Default Initializer value, type the value in the Default Initializer box, or click the Expression Builder button to use Expression Builder.

  7. Click OK.

Working with Initialization Blocks

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:

About Using Initialization Blocks with Variables

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:

Initializing Dynamic Repository Variables

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.

Initializing Session Variables

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.

About Row-Wise Initialization

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 19-2 shows the table in this example.

Table 19-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.

Initializing a Variable with a List of Values

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')

Creating Initialization Blocks

See "About Using Initialization Blocks with Variables" for more information about initialization blocks.

To create initialization blocks, perform the steps in the following sections:

Assigning a Name and Schedule to Initialization Blocks

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:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, from the Action menu, choose New > Repository (or Session) > Initialization Block.

  3. In the [Repository|Session] Variable Initialization Block dialog, type a name for the block. (The NQ_SYSTEM initialization block name is reserved.)

  4. (Repository initialization blocks only) In the Schedule area, select a start date and time and the refresh interval.

  5. (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.

Selecting and Testing 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. In addition, if an initialization block fails for a particular connection pool during Oracle BI Server start-up, no more initialization blocks using that connection pool are processed. Instead, the connection pool is blacklisted and subsequent initialization blocks for that connection pool are skipped. 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:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, double-click the initialization block you want to edit. You can edit Repository initialization blocks, or Session initialization blocks.

  3. Click Edit Data Source next to the Connection Pool field.

  4. From the Data Source Type list, select one of the following types.

  5. 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:

      1. 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.

      2. 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 Administration Tool Options" for more information.

      3. 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.

      4. (Optional) Click Test to test the data source connectivity for the SQL statement.

      5. Click OK to return to the Initialization Block dialog.

    • Select Use OBI EE Server, and then perform the following steps:

      1. 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.

      2. Click OK to return to the Initialization Block dialog.

  6. If you selected LDAP Server for your data source type, perform the following steps:

    1. 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.

    2. 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.

  7. If you selected Custom Authenticator for your data source type, perform the following steps:

    1. Click Browse to select an existing custom authenticator, or click New to create one.

    2. Click OK to return to the Initialization Block dialog.

  8. Click OK.

Examples of Initialization Strings

This section contains the following initialization string examples:

Example 19-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 19-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 19-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.

Testing Initialization Blocks

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):

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, double-click the initialization block.

  3. In the [Repository|Session] Variable Initialization Block dialog, click Edit Data Source.

  4. 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.

  5. In the Set value for the variables dialog, verify the information is correct, and then click OK.

  6. 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.

Associating Variables with Initialization Blocks

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:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, double-click the initialization block you want to edit. You can edit repository initialization blocks, or session initialization blocks.

  3. Click Edit Data Target.

  4. 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 variable USER 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.

  5. To reorder variables, select a variable and click Up or Down.

  6. To remove a variable from association with this block, select the variable and click Remove.

  7. Click OK.

The next step is to establish execution precedence.

Establishing 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:

  1. In the Administration Tool, select Manage, then select Variables.

  2. In the Variable Manager dialog, double-click the last initialization block that you want to be initialized.

  3. In the [Repository|Session] Variable Initialization Block dialog, click Edit Execution Precedence.

  4. 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.

  5. In the Browse dialog, select the blocks that should be initialized before the block that you have open, and then click OK.

  6. To remove a block, in the [Repository|Session] Variable Initialization Block Execution Precedence dialog, select the block you want to remove and click Remove.

  7. Click OK.

  8. If you want the initialization block to be required, in the [Repository|Session] Variable Initialization Block dialog, select the Required for authentication option.

  9. 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.

When Execution of Session Variable Initialization Blocks Cannot Be Deferred

Execution of session variable initialization blocks cannot be deferred in some circumstances. 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 and the variables have not been declared explicitly with default values.

    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.

Enabling and Disabling Initialization Blocks

You can use the Variable Manager in the Administration Tool to enable and disable initialization blocks.

To enable or disable an initialization block:

  1. In the Administration Tool, select Manage, then select Variables. The Variable Manager appears.

  2. 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.

  3. In the right pane, right-click the initialization block you want to enable or disable.

  4. Choose Enable or Disable from the right-click menu.

  5. Close the Variable Manager and save the repository.

Working with Multi-Source Session Variables

In addition to supporting regular session variables that are populated from one data source, Oracle Business Intelligence also supports session variables that can be populated from multiple data sources. These multi-source session variables can be used in logical queries or in repository data filters, and contain the union of values from the different data sources. There is no restriction on the number of values that the multi-source session variable can hold. To create a multi-source session variable, you first create row-wise initialization blocks for each source.

Then, you explicitly define session variables for each source. The format for the session variable names must be:

  • <ms_variable_name>____<source>

where the separator must be exactly four underscore characters.

This automatically creates a single multi-source session variable, named:

  • <ms_variable_name>

The component session variable names (<ms_variable_name>____<source>) appear separately in the Variable Manager in the Administration Tool, but the Expression Builder displays only the single multi-source session variable name (<ms_variable_name>).

Note:

While the main focus of this section is on the definition and usage of multi-source session variables, you may also select the VALUEOF the component session variables in logical queries and data filters.

If any of the row-wise initialization blocks returns null results, this is logged in the Oracle BI Server log, nqserver.log. Values can still be added to the multi-source session variable from other component initialization blocks that succeed in returning values. The multi-source session variable will fail only if all of the component initialization blocks return null values.

You can set execution precedence and deferred execution with multi-source session variables, similar to regular session variables.

Example to Illustrate the Creation and Usage of Multi-Source Session Variables

The following example illustrates how to create and use a multi-source session variable:

  1. In the Variable Manager in the Administration Tool, select Action > New > Session > Initialization Block.

  2. Create a row-wise initialization block called mvcountry_sebl_init with the following SQL for Default initialization string:

    select distinct 'MVCOUNTRY____SEBL', country from siebel_table
    
  3. Create a second row-wise initialization block called mvcountry_orcl_init with the following SQL for Default initialization string:

    select distinct 'MVCOUNTRY____ORCL', country from oracle_table
    
  4. Still in the Variable Manager, select Action > New > Session > Variable.

  5. Create a session variable called MVCOUNTRY____SEBL, making sure to include four underscores between the variable name and the source name. For Initialization Block, select mvcountry_sebl_init.

  6. Create a second session variable called MVCOUNTRY____ORCL, making sure to include four underscores between the variable name and the source name. For Initialization Block, select mvcountry_orcl_init.

While the component session variables appear in the Variable Manager, the multi-source session variable that has been created, MVCOUNTRY, will appear in Expression Builder.

Using the Multi-Source Session Variable in a Logical Query

You can now use the multi-source session variable MVCOUNTRY in a logical query.

For example:

select lastName, firstName, country from employee 
where country=VALUEOF(NQ_SESSION.MVCOUNTRY)

Using the Multi-Source Session Variable in a Data Filter

To use the multi-source session variable MVCOUNTRY in a data filter, perform the following steps:

  1. In the Administration Tool, select Manage, then select Identity.

  2. In the Identity Manager dialog, in the tree pane, select BI Repository.

  3. In the right pane, select the Application Roles tab, then double-click the application role for which you want to set data filters.

  4. In the Application Role dialog, click Permissions.

  5. In the User/Application Role Permissions dialog, click the Data Filters tab.

  6. In the Data Filters tab, create the data filter expression:

    • Country=VALUEOF(NQ_SESSION.MVCOUNTRY)

    Surrounding text describes mssv_perms.gif.

Note that the Expression Builder, as shown in the image that follows, displays only the multi-source session variable MVCOUNTRY, and not the regular session variables that were used during the creation of the multi-source session variable.

Surrounding text describes mssv_expr.gif.