Weblogic console & OEM Fusion Middlewere Not opening in OBIEE 11g

Hi Friends,

Some days back i faced a weird issue in OBIEE 11g server, where all opmn components were up & analytics was logining fine. But as an admin i had to do manual repository migration through Oracle Enterprise Manager Fusion Middleware. Considering that you might be knowing the process of rpd migration through OEM Fusion middleware, i am mentioning here for the solution to the issue i faced.


Issue - Weblogic console & OEM Fusion Middlewere Not opening.

Major Identification - While validating Admin Server Logs from
$DOMAIN_HOME/servers/AdminServer/logs/AdminServer.log

[Note - To save time always search logs with respect to timestamp, there can be many other techniques]

On Validating the AdminServer.log, i get the error as below:
-------------------------------------------------------------------------------------------------------------------------------
####<Apr 19, 2015 1:21:09 PM EDT> <Critical> <WebLogicServer> <$HOSTNAME> <AdminServer> <main> <<WLS Kernel>> <> <> <1429464069767> <BEA-000386> <Server subsystem failed. Reason: java.lang.NumberFormatException: null
java.lang.NumberFormatException: null
at java.lang.Integer.parseInt(Integer.java:417)
at java.lang.Integer.parseInt(Integer.java:499)
at weblogic.ldap.EmbeddedLDAP.validateVDEDirectories(EmbeddedLDAP.java:1104)
at weblogic.ldap.EmbeddedLDAP.start(EmbeddedLDAP.java:242)
at weblogic.t3.srvr.SubsystemRequest.run(SubsystemRequest.java:64)
at weblogic.work.ExecuteThread.execute(ExecuteThread.java:209)
at weblogic.work.ExecuteThread.run(ExecuteThread.java:178)

-------------------------------------------------------------------------------------------------------------------------

Root Cause –
Server subsystem failed. Reason: java.lang.NumberFormatException: null

Error points to Embedded LDAP for Weblogic

Embedded LDAP file (From Path - $DOMAIN_HOME/servers/AdminServer/data/ldap/conf) - replicas.prop size was 0 byte.

Action Taken –
Renamed replicas.prop to replicas.prop_old & restarted admin services.

Result - Success :) ...
Admin Services started & new replicas.prop ( embedded ldap server file with 14 bytes in my case) file created. Weblogic Console & Oracle Fusion Middleware also started working fine.

Hope it helps all in need :)

Enjoy


Write Back Setting in OBIEE 11G

Write Back is the ability to enter values directly into a report and have those values written in the database & used in calculations and charts in the report.
Please follow the steps listed below to configure Write Back in OBIEE 11g.

A- Repository Level Changes in all 3 layers to set Write Back Column :

Step 1:Physical Layer - From Physical Table Properties Go to-> General tab dialog box. Uncheck Cacheable

Step 2: Business Model & Mapping Layer -  Logical Column Properties Go to-> General tab. Check Writable option.

Step 3: Presentation Layer - Presentation Column Properties Go to-> General tab -> Permissions -> Set permission -> Read / Write (Radio Button), on the User / Application Role which you want to authenticate for WriteBack feature.

Step 4Presentation Layer - Go to -> Manage-> Identity Manager -> Identity Management (Left pane) -> Select Application Role (to which you need Write Back Permission) -> Permission -> Query Limits (tab) -> Select Database (to which you need direct database execution rights) -> Change option from ignore to allow to the field named "Execute Direct Database Requests".

Now we are done with Repository level changes for WriteBack column. Let us proceed with other changes.

B- Changes in the File Level :

Step 1: Enable Write Back. Add the LightWriteback tag within  the serverinstance tag of instanceconfig.xml file  ( file path - $ORACLE_INSTANCE/config/OracleBIPresentationServicesComponent/coreapplication_obips1 )

<LightWriteback>true</LightWriteback>

If this entry already exists then no modifications required, else restart OracleBIPresentationServicesComponent for this change to be effective.

Step 2: WriteBack Template. You may give any name for the writeback.xml file. Here for example i am using the file name as writeback_sample.xml

Things to do before you start the Template:

  • Identify the columns that are to be referenced. 
  • We can use the column position or by column id in the XML definition. 
  • We must include both insert and update statements in the template.
Template to be placed in the path:
$ORACLE_INSTANCE/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/analyticsRes/customMessages

Write-Back Template example: Name - eg. writeback_sample.xml
=================================================
<?xml version="1.0" encoding="utf-8" ?>
<WebMessageTables xmlns:sawm="com.siebel.analytics.web/message/v1">
<WebMessageTable lang="en-us" system="WriteBack" table="Messages">
   <WebMessage name="WriteBack_Template_Name">
      <XML>
         <writeBack connectionPool="Connection_pool_name">
            <insert>INSERT INTO Customer VALUES('@1','@2',@3,'@4',@5)</insert>
            <update>UPDATE Customer set Address='@2' where Name='@1'</update>
<!-- Identify the columns that are to be referenced. We can use the column position like @1 for first column, or by column id as you see them in the XML definition. -->
         </writeBack>
      </XML>
   </WebMessage>
<WebMessage name="Template_Name">
      <XML>
         <writeBack connectionPool="ConnectionPool_Name">
            <insert></insert>
            <update>UPDATE Product set Prod_Description='@2' where Name='@1'</update>
         </writeBack>
      </XML>
   </WebMessage>
<WebMessage name="Template_Name">
      <XML>
         <writeBack connectionPool="ConnectionPool_Purchase">
            <insert>INSERT INTO Supplier VALUES('@1','@2',@3,@4)</insert>
            <update></update>
         </writeBack>
      </XML>
   </WebMessage>
</WebMessageTable>
</WebMessageTables>
<!-- We may also use multiple insert / update commands for same or different connection pools as well based on our need -->
==================================================
[ Note - We need to mention insert & update statements based on our requirement. Above insert & update code is only for sample purpose & content within <!-- #### --> are comments. If we do not want to include SQL commands within the elements, then we must insert a blank space between the opening and closing tags. eg. <insert> </insert> rather than <insert></insert>]

In the above xml file...
Important Tags -

  • WebMessage name - The name here will be used as WriteBack template name in analysis -> Table Properties -> Write Back.
  • Write Back connectionPool - Connection pool name for Write Back.
  • insert - Based on your requirement or leave blank ( if not required)
  • update - Based on your requirement or leave blank ( if not required)
Now we are done with changes in the files. Lets proceed further & know what changes we need to make in analysis for the writeback report...

C- Changes in Analytics :

Step 1Give Privilege to the Role for Write Back ( Administration -> Manage Privilege -> Write Back & add the role for writeback privilege). 

Step 2Now you need to edit Column Properties -> writeback -> Check 'Enable Write Back' of the field needed for writeback, from criteria tab.

Step 3: Now edit Table Properties view -> writeback & check 'Enable Write Back' & mention Template Name as mentioned in writeback file ( WebMessage name="WriteBack_Template_Name). You may also rename Apply, Revert & Done Button & change Button Position if required.

You are now done with all WriteBack settings. You may test the report for set writeback features.

OBIEE enterprise manager adf faces 60097


Today I faced one issue in newly built server while uploading rpd for migration through EM.

I noticed error from coreapplication as :


Then Navigated to MBean to try my luck for rpd uploading from there, but all parameters were showing unavailable Value.




I explored the solution to it & identified as file - <OBIEE_HOME>/user_projects/domains/bifoundation_domain/sysman/mds/partition1/ai/bi/fragments/mdssys/cust/user/weblogic/deployment.jspx.xml was causing the issue. I deleted it & proceeded with full bounce. 
[ Note - deployment.jspx.xml file will get created automatically after you navigate to coreapplication in enterprise manager. But take the backup of the file before deleting it. ]

The issue resolved then & coreapplication & MBean both working fine thereafter...


deployment.jspx.xml got created automatically after navigating to coreapplication from Enterprise Manager.



Math Functions in OBIEE

There are many science, research and development functions which are not much explored or used in business intelligence. Most of such functions belong to Math Functions. I am listing below all Math Functions.

Math Functions

Abs, Acos, Asin, Atan, Atan2, Ceiling, Cos, Cot, Degrees, Exp, Floor, Log, Log10, Mod, Pi, Power, Radians, Rand, RandFromSeed, Round, Sign, Sin, Sqrt, Tan, Truncate

As I am not working in any scientific or research & development project, so I decided to manually create such functions, to describe math functions. I then thought to randomly select some of trigonometric functions & test result through their graph, so I choose sin, cos and tan. But for trigonometric function I had to further make use of pi (you may use degrees as well).

The functions applied in my case for different functions is as below:
Sin - SIN((RCOUNT(1)-1)*PI()/4)
Cos - COS((RCOUNT(1)-1)*PI()/4)
Tan - TAN((RCOUNT(1)-1)*PI()/4)
Angle in Degree - CEILING(DEGREES((RCOUNT(1)-1)*PI()/4))

Where RCOUNT(1)-1 gives numeric value starting from zero & 1 in RCOUNT(1) is numeric symbolizing first column with distinct data & PI()/4 is used to multiply each count to pi/4 ( quarter of semicircle).
Math Function Test
Test Maths
Calculated Attributes
Angle in Degree
Sine Value
Cos Value
Tan Value
0
0
1
0
45
0.707
0.707
1
90
1
0
6.18986E+14
135
0.707
-0.707
-1
180
0
-1
0
225
-0.707
-0.707
1
270
-1
0
2.16235E+14
315
-0.707
0.707
-1
360
0
1
0
405
0.707
0.707
1
450
1
0
1.20485E+14
495
0.707
-0.707
-1
540
0
-1
0
585
-0.707
-0.707
1
630
-1
0
9.01976E+13
675
-0.707
0.707
-1
720
0
1
0
765
0.707
0.707
1
810
1
0
6.77417E+13
855
0.707
-0.707
-1







\





















So as verifying from the graph & tabular value, it is clear to make use of them, leaving tan pi/2 as an exception of giving a finite value. However still aviating, some more scientific calculus functions, which will make obiee full package to be used in scientific research & development projects.
J






To Get Age between two Days in OBIEE Report

For Getting Age between two dates we use SQL Query as :

datediff(d, startdate, enddate) as Age

However default date format in OBIEE is Timestamp. So you need timestamp function (Available under Calendar/Date Function Heading) to get required result.

Syntax:

TIMESTAMPDIFF(interval, timestamp1, timestamp2)

Where:
interval is the specified interval. Valid values are:

SQL_TSI_SECOND

SQL_TSI_MINUTE

SQL_TSI_HOUR

SQL_TSI_DAY

SQL_TSI_WEEK

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_YEAR

timestamp1 and timestamp2 are any valid timestamps.

Example
For Number of Days between two days:
TimestampDiff(SQL_TSI_DAY, “FROM_DATE_COLUMN”, “TO_DATE_COLUMN”)

For Number of Days till current date:
TimestampDiff(SQL_TSI_DAY, “FROM_DATE_COLUMN”, CURRENT_DATE)

*You can also use this function for getting age difference for other time dimension attributes as week, quarter, month or year. All you need to do is change first attribute i.e 'interval' & other attribute's accordingly.

Creating Aggregate Tables in OBIEE


Steps for Creating Aggregate Tables in OBIEE

  1. Create all Dimension Tables, Fact Tables & Hierarchies, which are required to be aggregated.
  2. Go to ToolsàUtilities (from Administration tool menu bar), a dialog box will pop up with all available utilities.
  3. Select Aggregate Persistence Wizard, and then click Execute Button. (See Figure Below).


4.       Now Select appropriate path where you need to generate Aggregate Table SQL.

Note : Click Generate DDL file for first time generation of Aggregate Table. (See Figure Below)


  1. Click Next, to move to next page (Select Business Model & Measure Page)
  2. In Select Business Model & Measure Page, Select Appropriate Business Model & then select associated Fact / Measure.(See Figure Below).


     7.       Click next, to move to next page (Select Dimensions & Levels).

  1. Select appropriate level of dimension & check Use Surrogate Key.



9.       Click next, to move to next page (Select output Connection Pool, Container & Name).





  1. Click next, to move to next page (Aggregate Definition).
  2. Select I am Done (Radio Button).
  3. Click Next.



  1. Then Click Finish. Your Aggregate Table is Created Now & available at the path you specified in “Select File Location” Page.
  2. To view generated script move to - C:\Agg\
  3. Select The Aggregate Table Created & View the Code. Code for above process is mentioned below:

delete aggregates; /* Required only first time, so that any further aggregates can be deleted */
/*However if you create other Aggregate, you dont need it. */ 

create aggregates

"ag_FACTINTERNETSAL"

 for "SALES"."FACTINTERNETSALES"("ORDERQUANTITY")

 at levels ("SALES"."Time"."Year" using_surrogate_key )

 using connection pool "Adventure Works"."Agg CP"

 in "Adventure Works"."AdventureWorksDW2008";

  1. Now the script is ready, we run it using the “nqcmd.exe” utility in the /OracleBI/server/bin directory.

Steps for running Aggregate Script are mentioned below:

Microsoft Windows [Version 6.1.7601]
Copyright (c) 2009 Microsoft Corporation.  All rights reserved.

C:\Users\gaurav.mishra>cd\

C:\>cd oraclebi\server\bin (Click Enter)

C:\OracleBI\server\Bin>nqcmd.exe -u Administrator -p Administrator -d analyticsweb -s \Agg\agg.sql

[ Where : u (Admin User id)  p (Password)  d (analyticsweb)  s (script path) ]
-------------------------------------------------------------------------------
          Oracle BI Server
          Copyright (c) 1997-2009 Oracle Corporation, All rights reserved
-------------------------------------------------------------------------------


delete aggregates
delete aggregates

Statement execute succeeded


create aggregates

"ag_FACTINTERNETSAL"
 for "SALES"."FACTINTERNETSALES"("ORDERQUANTITY")
 at levels ("SALES"."Time"."Year" using_surrogate_key )
 using connection pool "Adventure Works"."Agg CP"
 in "Adventure Works"."AdventureWorksDW2008"
create aggregates

"ag_FACTINTERNETSAL"
 for "SALES"."FACTINTERNETSALES"("ORDERQUANTITY")
 at levels ("SALES"."Time"."Year" using_surrogate_key )
 using connection pool "Adventure Works"."Agg CP"
 in "Adventure Works"."AdventureWorksDW2008"

Statement execute succeeded


Processed: 2 queries

C:\OracleBI\server\Bin>

 
After getting successful aggregate script execution, you need to restart all BI Services.

Now Open your metadata Repository & you will see that new aggregate tables created and registered, and shown in red to show they’re aggregates.


Note : No change in presentation layer, as data is executed from logical table & physical table, so presentation layer remains unaffected. 

Creating Variables in OBIEE


Using Variables in the Oracle BI Repository

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:

  • About Repository Variables
  • Creating Repository Variables
  • About Session Variables
  • Creating Session Variables
  • Working with Initialization Blocks

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
  • About Dynamic Repository Variables

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.

  1. Select the type of variable: Static or Dynamic.
  2. 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.

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

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



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
  • About Nonsystem Session Variables

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

Table a- 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.
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 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition for more information about the PROXY system session variable.
GROUP
Contains the groups to which the user belongs. Exists only for compatibility with previous releases. Legacy groups are mapped to application roles automatically.
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.
USERGUID
Contains the global unique identifier (GUID) of the user, typically populated from the LDAP profile of the user.
ROLES
Contains the application roles to which the user belongs.
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.impersonateUser or oracle.bi.server.manageRepository.
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.
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).
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.
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.
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.
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.



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.

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

  1. To add a Default Initializer value, type the value in the Default Initializer box, or click the Expression Builder button to use Expression Builder.
  2. 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
  • Creating Initialization Blocks
  • Associating Variables with Initialization Blocks
  • Establishing Execution Precedence
  • When Execution of Session Variable Initialization Blocks Cannot Be Deferred
  • Enabling and Disabling Initialization Blocks

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
  • Initializing Session Variables
  • About Row-Wise Initialization

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.

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 Security 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 Below shows the table in this example.

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

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

  • Assigning a Name and Schedule to Initialization Blocks
  • Selecting and Testing the Data Source and Connection Pool

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.

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

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.

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

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

      1. (Optional) Click Test to test the data source connectivity for the SQL statement.
      2. 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.

      1. Click OK to return to the Initialization Block dialog.
  1. 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.

  1. 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.
  2. Click OK.

Examples of Initialization Strings

This section contains the following initialization string examples:

  • Example 18-1, "A SQL Statement When Site Uses Delivers"
  • Example 18-2, "A SQL Statement When Site Does Not Use Delivers"
  • Example 18-3, "A SQL Statement Joining Tables From Multiple Data Sources - When Using the 'OBI EE Server' Setting"

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

  1. In the Set value for the variables dialog, verify the information is correct, and then click OK.
  2. 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.

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.

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.
      • 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. If you select Row-wise initialization, the Use caching option becomes available.
  1. To reorder variables, select a variable and click Up or Down.
  2. To remove a variable from association with this block, select the variable and click Remove.
  3. 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.

  1. In the Browse dialog, select the blocks that should be initialized before the block that you have open, and then click OK.
  2. To remove a block, in the [Repository|Session] Variable Initialization Block Execution Precedence dialog, select the block you want to remove and click Remove.
  3. Click OK.
  4. If you want the initialization block to be required, in the [Repository|Session] Variable Initialization Block dialog, select the Required for authentication option.
  5. 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, 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.

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.

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.


Reference : otn.oracle.com