Oracle® Retail Workspace

Integrating with Oracle BI EE

Delivers Alerts
January 2009
Note: The following is intended to outline our general product
direction. It is intended for information purposes only, and may
not be incorporated into any contract. It is not a commitment to
deliver any material, code, or functionality, and should not be
relied upon in making purchasing decisions. The development,
release, and timing of any features or functionality described for
Oracle’s products remains at the sole discretion of Oracle.
Contents
Overview ...................................................................................................................................1
Creating Scheduler Tables......................................................................................................1
Configuring the Scheduler......................................................................................................2
Configuring Oracle BI Presentation Services to Communicate With Oracle BI
Scheduler..................................................................................................................................4
Specifying the Scheduler Host and Port in the Presentation Services Configuration File ..... 4
Adding Scheduler Administrator Credentials to Oracle BI Presentation Services Credential
Store .................................................................................................................................................... 5
Configuring Oracle BI Presentation Services to Identify the Credential Store ........................ 6

Troubleshooting.......................................................................................................................7
Reference..................................................................................................................................8
Overview
Oracle Business Intelligence Delivers (Delivers) is the interface used to create alerts based on
Oracle Business Intelligence Answers (Answers) results. Delivers works in tandem with
Oracle Business Intelligence Scheduler (Scheduler). iBots deliver reports and alerts to end-
users. They are configured and submitted for execution using Delivers. To create iBots, the
Scheduler must be configured and four tables must be created. The method of configuring
Oracle BI Scheduler depends on the operating system being used. This document covers
how to configure Oracle BI Scheduler under Linux.

Note: This document refers to environment variables that need

to be set.

$ORACLE_BI_HOME: set to the OBIEE server installation directory.

$ORACLE_BI_DATA_HOME: set to the OBIEE server data directory.

Following are the steps required to configure iBots in Oracle Business Intelligence Enterprise
Edition (BI EE):

Creating Scheduler Tables

Oracle BI EE iBots require Scheduler specific tables to be created in a database schema. Make
sure you have a valid database administrator account to create a schema and tables. Use the
following command to create a new schema. Substitute an existing database tablespace for
<mytablespace>.
SQL> create user S_NQ_SCHED identified by <password> default tablespace
<mytablespace> temporary tablespace temp;
SQL> grant create session, create table to S_NQ_SCHED;
SQL> alter user S_NQ_SCHED quota unlimited on <mytablespace>;
Refer to Oracle BI EE documentation for quota requirements for user S_NQ_SCHED.
The scheduler tables are used by Oracle Delivers and are populated with information from
the Scheduler jobs. The tables are:
ƒ S_NQ_JOB – used to store information about scheduled jobs.
ƒ S_NQ_INSTANCE – used to store information about job instances.
ƒ S_NQ_JOB_PARAM – used to store information about job parameters for scheduled
jobs.
ƒ S_NQ_ERR_MSG – used to store information about job instances that do not
complete successfully.
Connect to the S_NQ_SCHED schema using Oracle SQL*Plus and run the following
scheduler script at the SQL> prompt:
SQL> @<ORACLE_BI_HOME>/Server/Schema/SAJOBS.Oracle.sql;
where <ORACLE_BI_HOME> is the Oracle BI EE server installation directory.
Verify that the tables were created by entering the following string at the SQL> prompt:
SQL> select table_name from user_tables where table_name like 'S_NQ%';
Enter Exit at the SQL > prompt to close Oracle SQL*Plus.

Integrating with Oracle BI EE Delivers Alerts 1

Configuring the Scheduler
Once you have created the tables for storing information about Scheduler jobs, you need to
configure Scheduler. For the Linux / UNIX platform, there is no GUI interface available, the
Scheduler configuration options are set using schconfig, a console-based application
located under $ORACLE_BI_HOME/server/Bin where $ORACLE_BI_HOME is the Oracle BI EE
server installation directory.
1. Navigate to the $ORACLE_BI_HOME/setup directory and run the following commands:
$ . sa-init.sh
$ $ORACLE_BI_HOME/server/Bin/schconfig
2. The Delivers Configuration Menu appears. From the Delivers Configuration choices,
select 1 - Configure Scheduler.
Copyright (c) 1997-2006 Oracle Corporation, All rights reserved

***** Delivers Configuration Menu *****

1 - Configure Scheduler
2 - Configure Mail
3 - Configure iBots
4 - Configure Workflow
5 - Configure Java Extension
0 - Quit
>>> Enter Choice: 1
3. The Scheduler Configuration menu appears. Select 1 - Database.
***** Scheduler Configuration *****
1 - Database
2 - General
3 - Advanced
0 - Quit

>>> Enter Choice: 1

You are presented with the following menu options:
***** Scheduler Database Configuration *****
1 - Database Type : Oracle 10g R2
2 - Call Interface : OCI 10g
3 - Data Source Name : orcl (for example)
4 - User Name : s_nq_sched (for example)
5 - Password : *****
6 - Timeout (Minutes) : 60
7 - Maximum Connections : 5
8 - Bulk Fetch Buffer Size (bytes) : 33792
9 - Database Table for Jobs : S_NQ_JOB
10 - Database Table for Instances : S_NQ_INSTANCE
11 - Database Table for Parameters : S_NQ_JOB_PARAM
12 - Database Table for Messages : S_NQ_ERR_MSG
13 - DEFAULT VALUES
0 - Quit
4. Select and set the parameters as shown in Table 1.

2 Oracle Retail Workspace

Table 1. Scheduler Database Configuration Settings

Section Field Input

Database Database Type Select the appropriate Database Type for the database (for
example – Oracle 10g R2).
The Call Interface is automatically updated according to
the Database Type chosen.
Data Source Name The database in which you created the user S_NQ_SCHED
(for example orcl).
Username User name for the database (for example – s_nq_sched).
Password Password for the user S_NQ_SCHED.

5. Select 0 to quit and save changes to the Database configuration when prompted.
6. From the Scheduler Configuration choices, select 2 - General.
***** Scheduler Configuration *****
1 - Database
2 - General
3 - Advanced
0 - Quit

>>> Enter Choice: 2

The Scheduler General Configuration menu appears.
***** Scheduler General Configuration *****
1 - Scheduler Script Path : $ORACLE_BI_HOME/server/Scripts/scheduler
2 - Default Script Path : $ORACLE_BI_HOME/server/Scripts/default
3 - Temporary File Path : $ORACLE_BI_DATA_HOME/tmp
4 - Port Number : 9705
5 - Purge Old instances after X days: 7
6 - Purge DB every X minutes : 5
7 - Minimum Execution Threads : 1
8 - Maximum Execution Threads : 100
9 - Pause When Service Starts : False
10 - Administrator Name : Administrator
11 - Administrator Password : *****
12 - DEFAULT VALUES
0 - Quit
where:
ƒ ‘Administrator Name’ is the administrator of the metadata repository.
ƒ $ORACLE_BI_HOME is the Oracle BI EE server installation directory.

ƒ $ORACLE_BI_DATA_HOME is the Oracle BI EE server data directory.

7. Select and set the parameters as shown in Table 2.

Table 2. Scheduler General Configuration Settings

Section Field Input

General Administrator Name User name for the Scheduler administrator.

Administrator Password User password for the Scheduler administrator.
Confirm the password entry.

Integrating with Oracle BI EE Delivers Alerts 3

 Section Field Input

(Other parameters) The other parameters are set to defaults. The

default port for the Scheduler service is 9705.
To change the Scheduler port, select and set Port
Number.

8. Select 0 to quit and save changes to the General configuration when prompted.
After setting the values of the menu and saving the changes, if you want to send reports
by mail, select "2 - Configure Mail" from the Delivers Configuration Menu to configure
the mail options.

Configuring Oracle BI Presentation Services

to Communicate With Oracle BI Scheduler
The Oracle BI Scheduler and Oracle BI Presentation Services servers work together. This
topic covers their configuration. The following three steps are required:
1. Specify the Scheduler host and port in Presentation Services configuration file.
2. Add Scheduler administrator credentials to Oracle BI Presentation Services credential
store.
3. Configure Oracle BI Presentation Services to identify the credential store.

Specifying the Scheduler Host and Port in the Presentation Services

Configuration File
This step allows the presentation server to know about the server and port details of the
scheduler. The Scheduler host name and port are specified in the instanceconfig.xml file for
Oracle BI Presentation Services that is located in the directory
$ORACLE_BI_DATA_HOME/web/config on UNIX, where $ORACLE_BI_DATA_HOME is the Oracle BI EE
server data directory.
ƒ When Oracle BI Scheduler and Oracle BI Presentation Services components are
installed together on the same server, the installer sets the instanceconfig.xml setting
of the ScheduleServer to the local host and default Scheduler port of 9705.
If Oracle BI Scheduler and Oracle BI Presentation Services are installed on the same
server and Scheduler uses the default port 9705, proceed to topic Adding Scheduler
administrator credentials to Oracle BI Presentation Services credential store.
ƒ When Oracle BI Scheduler and Oracle BI Presentation Services are not installed on
the same server, or if you have changed the Scheduler port from the default port of
9705, you must modify the instanceconfig.xml file for Presentation Services.

Note: Make a back-up copy of the instanceconfig.xml file before

editing it.

4 Oracle Retail Workspace

 Use the following procedure to modify the instanceconfig.xml configuration file with an
entry that points the Oracle BI Presentation Services to the Oracle BI Scheduler server and
port number.
The ScheduleServer element of the instanceconfig.xml holds the server and port information
of the Oracle BI Scheduler. The following is the procedure to set this element:
1. On the BI Presentation Services server, navigate to the Oracle BI data directory at the
location $ORACLE_BI_DATA_HOME/web/config.
Locate the file instanceconfig.xml and make a backup copy.
2. Open the instanceconfig.xml file for editing.
3. Between the <ServerInstance></ServerInstance> tags, locate the tag pair <Alerts> and
</Alerts>. If they do not exist, they need to be created.

4. Between the Alerts tags, create the tag pair <ScheduleServer> and </ScheduleServer>.
5. Between the ScheduleServer tags, insert the name of the Scheduler server.
For example:
<ServerInstance>
. . .
<Alerts>
<ScheduleServer>Schedulerserver</ScheduleServer>
</Alerts>
6. If the Scheduler port has been changed from the default of 9705, specify the Scheduler
port number.
For example:
<ServerInstance>
. . .
<Alerts>
<ScheduleServer>myhost.domain.com:10705</ScheduleServer>
</Alerts>
7. Save the file when you are done.
Changes take effect when the Oracle BI Presentation Services service is restarted.

Adding Scheduler Administrator Credentials to Oracle BI Presentation

Services Credential Store
Oracle BI Presentation Services must be able to identify the Scheduler administrator and
obtain the credentials to establish a connection with the Scheduler. Presentation Services
stores the credentials that it uses in a Presentation Services Credential Store. To obtain the
Scheduler administrator credentials, Oracle BI Presentation Services searches the credential
store for a username-password credential with the alias admin. That’s why the Scheduler
administrator credentials must be added to the credential store, under the alias admin.
Use the following procedure to add the Scheduler administrator credentials to the
Presentation Services credential store with the admin alias. This procedure adds the
Scheduler administrator credentials to a proprietary XML file credential store called
credentialstore.xml. The default location of this file is $ORACLE_BI_DATA_HOME/web/config on
UNIX.
1. Open a command shell on the server where Oracle BI Presentation Services has been
installed.

Integrating with Oracle BI EE Delivers Alerts 5

 2. Navigate to the directory $ORACLE_BI_HOME/web/bin. Then enter in the following
command:
$ . $ORACLE_BI_HOME/setup/sa-init.sh
3. Execute the CryptoTools utility to add the Scheduler administrator credentials to the
Presentation Services credential store:
$ cryptotools credstore -add -infile
$ORACLE_BI_DATA_HOME/web/config/credentialstore.xml
For more information on the CryptoTools utility, its syntax and supported sub-commands
refer to the Oracle Business Intelligence Enterprise Edition Deployment Guide.
4. Supply values for the prompted parameters, as shown in the following table.

CryptoTools Prompt Value or Input Description

Credential Alias Admin Specify the value admin. Presentation Services uses
this alias to identify the username-password
credential for the Scheduler administrator.
Username (Username of Username of the Scheduler administrator.
Scheduler
For example, Administrator.
administrator)
Password (Password for the Password of the Scheduler administrator.
Scheduler
administrator)
Do you want to y or n Choosing "y" encrypts the password.
encrypt the password?
Passphrase for (passphrase) Provide a passphrase that is used to encrypt the
encryption password. For example, another_secret.
Do you want to write y or n Choosing "y" writes the passphrase that is needed to
the passphrase to the decode the password in the xml file.
xml?
For enhanced security, choose "n". The passphrase is
not written to the xml file. Instead, you must specify
the passphrase in the instanceconfig.xml file.

The following is an example of the procedure to add the Scheduler administrator

credentials to the Presentation Services credential store.
$ . $ORACLE_BI_HOME/setup/sa-init.sh
$cryptotools credstore –add –infile
$ORACLE_BI_DATA_HOME/web/config/credentialstore.xml
>Credential Alias: admin
>Username: Administrator
>Password:
>Do you want to encrypt the password? y/n (y): y
>Passphrase for encryption:
>Do you want to write the passphrase to the xml? y/n (n): n
$
The CryptoTools utility updates the credentialstore.xml file, located in the directory
$ORACLE_BI_DATA_HOME/web/config.

Configuring Oracle BI Presentation Services to Identify the Credential Store

Oracle BI Presentation Services must be directed to the credential store that contains the
Scheduler administrator credentials. This is done by setting parameters in the Oracle BI

6 Oracle Retail Workspace

 Presentation Services configuration file, instanceconfig.xml. In addition, if you have not
stored the passphrase in the credential store, then the passphrase to decrypt the password
credential must also be specified. In the above example, the passphrase was not stored in the
credential store and needs to be specified in the instanceconfig.xml file.
To identify the credential store to be used by Oracle BI Presentation Services:
1. Open the instanceconfig.xml file for editing. This file is located in the directory
$ORACLE_BI_DATA_HOME/web/config.

2. Locate the <CredentialStore> node within this file.

3. Specify attribute values as shown in the following example. If the <CredentialStore>
node does not exist, create this element with sub-elements and attributes.
<WebConfig>
<ServerInstance>
<!-- other settings ... -->
<CredentialStore>
<CredentialStorage type="file" path="<path to credentialstore.xml>"
passphrase="<passphrase>"/>
<!-- other settings ... -->
</CredentialStore>
<!-- other settings ... -->
</ServerInstance>
</WebConfig>
4. Restart Presentation Services to reflect the configuration changes.

CAUTION: Both the credentialstore.xml and instanceconfig.xml

file must be protected via file access permissions (chmod file
permissions to be 400). Their combination can reveal a
privileged user password. (Neither file by itself has enough
information to expose the password.)

5. Restart the BI Scheduler by executing the following command:

$ $ORACLE_BI_HOME/setup/run-sch.sh start
Once this is done, you should be able to schedule and create new iBots. The best way to
validate the configuration is to save a sample iBot. If you are able to successfully save a new
iBot, then your configuration has been properly set.
For information on how to create an iBot see the “Creating and Delivering an iBot” topic in
the following online tutorial:
http://www.oracle.com/technology/obe/obe_bi/bi_ee_1013/delivers/delivers.htm

Troubleshooting
Problem:
When you try to save an iBot, the following error appears:
“Oracle BI Scheduler Error: [nQSError: 68019] Authentication Failed.”
Solution:
Verify that the administrator of the metadata repository has been set in the scheduler
configuration. Follow the steps in the Configuring the Scheduler section to set the
administrator name and password for the scheduler.

Integrating with Oracle BI EE Delivers Alerts 7

Reference
Oracle® Business Intelligence Infrastructure Installation and Configuration Guide

8 Oracle Retail Workspace

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.

Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
oracle.com

Copyright © 2009, Oracle. All rights reserved.

This document is provided for information purposes only and the
contents hereof are subject to change without notice.
This document is not warranted to be error-free, nor subject to any
other warranties or conditions, whether expressed orally or implied
in law, including implied warranties and conditions of merchantability
or fitness for a particular purpose. We specifically disclaim any
liability with respect to this document and no contractual obligations
are formed either directly or indirectly by this document. This document
may not be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without our prior written permission.
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle
Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.