Skip Headers
Oracle® Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
11g Release 1 (11.1.1)

Part Number E10541-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

19 Configuring and Managing Agents

If your organization licensed Oracle BI Delivers and if you have the appropriate privileges, then you can use the agents functionality as part of a default installation with no additional configuration. This chapter describes how agents are used, what affects agents, about advanced configuration settings that affect agents, managing device types for agents, and monitoring agent sessions. For information about using agents, see "Delivering Content" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

This chapter includes the following topics:

Note:

If you are migrating an Oracle Business Intelligence environment to a new system, then ensure that you also migrate the Oracle Business Intelligence repository file, the Oracle BI Presentation Catalog, and the Oracle BI Scheduler tables. The Oracle BI Scheduler tables are required for agents.

See Section 8.5.6, "Diagnosing Issues with Agents" for information about diagnostics and log files for agents.

19.1 How Are Agents Used?

Agents deliver targeted analytics to users based on a combination of schedule and trigger event. Delivery can be by a variety of routes, for example to Dashboard Alerts or to e-mail.

To create an agent, Oracle Business Intelligence users (with the Create Agent privilege) define the operations that the agent is to perform. Oracle BI Presentation Services packages information such as priority, delivery devices, and user, into a job, and tells Oracle BI Scheduler when to execute the job. For information, see "What is Oracle BI Scheduler?" in Oracle Fusion Middleware Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition

19.2 How Do Antivirus Software and Privileges Affect Agents?

This section provides the following information about agents:

19.2.1 How Does Antivirus Software Affect Agents?

Some antivirus software programs, such as Norton AntiVirus, enable a script-blocking feature, which tries to block all calls made by scripts to system objects (such as the Windows file system object) that the antivirus software deems unsafe.

If you start a script as part of post-agent processing, then this antivirus feature might cause unexpected results. If you run antivirus software with a script-blocking feature on the computer where Oracle BI Scheduler is installed, then you should disable the script-blocking feature to prevent the software from unexpectedly blocking agent script calls.

19.2.2 What Privileges Affect Agents?

You access the privilege settings for agents in the Delivers section of the Manage Privileges page in Oracle BI Presentation Services Administration.

To create an agent, users must be granted the Create Agent privilege. To enable users with the Publish Agents for Subscription privilege, which provides the ability to change or to delete an agent, you must grant them the Modify permission to the shared agent objects and child objects in the Oracle BI Presentation Catalog. For information, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

Note:

If the Oracle BI Server is configured to authenticate users through database logons, then impersonation is permitted until the number of associated variables exceeds one (for example, when session variables other than USER are associated with the initialization block). If the number of associated variables exceeds one, then the impersonated user does not have the password to log in to the database and to fill the other session variables. Agents work with database authentication, if only the initialization block that is set up for authentication in the Oracle BI Administration Tool uses a connection pool with pass-through login. That connection pool cannot be used for any other initialization block or request.

For information about user authentication options, see Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition. For information about pass-through login, see Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

19.3 Configuring Settings That Affect Agents

You configure settings for agents by changing values for Oracle BI Presentation Services or Oracle BI Scheduler. You configure delivery options for agents using the SA System subject area. This section contains the following topics:

19.3.1 Manually Configuring Presentation Services Settings That Affect Agents

Use various elements in the instanceconfig.xml file for Presentation Services to change these settings. You must apply changes to both the primary and secondary scheduler's instanceconfig.xml in a cluster.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit Presentation Services settings that affect agents:

  1. Open the Presentation Services instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the section in which you must add the elements that are described in Table 19-1.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    
    
    <ServerInstance>
      <ps:Alerts xmlns:ps="oracle.bi.presentation.services/config/v1.1">
         <ps:Enabled>false</ps:Enabled>
         <ps:DefaultDeliveryFormat>pdf</ps:DefaultDeliveryFormat>
      </ps:Alerts>
    </ServerInstance>
    
  4. Save your changes and close the file.

  5. Restart Presentation Services.

Table 19-1 Presentation Services Settings That Affect Agents

Element Description Default Value

Enabled

Specifies whether Oracle BI Delivers is enabled. Allowed values are true or false.

Delivers is an optional component of Presentation Services that is enabled by default for organizations that have purchased the appropriate license. You use the Delivers component to create agents.

true

DefaultDeliveryFormat

Specifies the default format for sending e-mailed reports through an agent.

For example, a content designer can create an agent to send a report every day to a development team to share how many bugs have been fixed in the past day. When the content designer creates the agent, he can specify the format of the e-mail. As the administrator, you can specify the default format that is used for such e-mails, using one of the following values:


html
pdf
excel
text

html


19.3.2 Manually Changing Additional Scheduler Settings That Affect Agents

In addition to the scheduler settings that you can change in Fusion Middleware Control, you can change other settings manually. Use various elements in the instanceconfig.xml file to change these settings. You must apply changes to both the primary and secondary scheduler's instanceconfig.xml in a cluster.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually change additional Oracle BI Scheduler settings that affect agents:

  1. Open the Oracle BI Scheduler version of the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the sections in which you must add or update the elements that are described in Section 19.3.3, "What Additional Scheduler Configuration Settings Affect Agents?"

  3. Include the elements and their ancestor elements as appropriate. The entry for Log_Dir is shown in the following example:

    <xs:element name="Log_Dir" type="xs:string" default="ibots" minOccurs="0">
       <xs:annotation>
          <xs:documentation xml:lang="en">
             The directory where Agent logs are stored.
          </xs:documentation>
       </xs:annotation>
    </xs:element>
    

    Note:

    You cannot specify values for user name and password in the instanceconfig.xml file. Instead you specify values in Fusion Middleware Control that are stored securely within the central credentials wallet, along with all other user names and passwords.
  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.3.3 What Additional Scheduler Configuration Settings Affect Agents?

You can change the following additional Oracle BI Scheduler configuration settings that affect agents:

19.3.3.1 General Scheduler Configuration Settings That Affect Agents

General configuration settings include access to, and configuration of, the Scheduler back-end database, some behavior settings, and settings for secure sockets and clustering configuration. Table 19-2 describes the settings.

Table 19-2 General Scheduler Configuration Settings That Affect Agents

Element Description Default Value

PoolTimeout

Specifies the amount of time in minutes that a connection to the data source remains open after an operation completes.

During this time, new operations use this connection rather than open a new one, up to the number specified for Maximum Connections. The time is reset after each completed connection request.

Specify a value of 1 or greater.

60

NumDbConnections

Specifies the maximum number of database connections that Oracle BI Scheduler can open concurrently. Specify a value of 1 or greater. When this limit is reached, the connection request waits until a connection becomes available.

5

TABLE_JOBS

Specifies the name of a database table used to store information about scheduled jobs.

Note: For information about modifying the database table names, see "Changing Oracle BI Scheduler Table Names" in Oracle Fusion Middleware Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition and see Oracle Business Intelligence Applications Installation and Configuration Guide.

S_NQ_JOB

TABLE_INSTANCES

Specifies the name of a database table used to store information about job instances.

S_NQ_INSTANCE

TABLE_PARAMS

Specifies the name of a database table used to store information about job parameters.

S_NQ_JOB_PARAM

TABLE_ERRMSGS

Specifies the name of a database table used to store information about job instances that do not complete successfully.

S_NQ_ERR_MSG

SchedulerScriptPath

Refers to the path where Oracle BI Scheduler-created job scripts are stored. In general, you should not add or remove scripts from this directory. By default, this field is set to ORACLE_INSTANCE\bifoundation\OracleBISchedulerComponent\coreapplication_obischn\scripts\scheduler, for example D:\OBI11g\instances\instance1\bifoundation\OracleBISchedulerComponent\coreapplication_obisch1\scripts\scheduler.

scripts\scheduler

DefaultScriptPath

Specifies the path where user-created job scripts (not agents) are stored.

If a file name is entered in the Script field when adding or modifying a job, then Oracle BI Scheduler examines the contents of this directory for the specified file. However, if a full path is given in the Script field, then this directory is not examined. By default, this field is set to ORACLE_INSTANCE\bifoundation\OracleBISchedulerComponent\coreapplication_obischn\scripts\scheduler\common, for example D:\OBI11g\instances\instance1\bifoundation\OracleBISchedulerComponent\coreapplication_obisch1\scripts\scheduler\common.

scripts\scheduler\common

TempPath

Specifies the path where temporary files are stored during Oracle BI Scheduler execution.

NA

BulkFetchBufferSize

Used in the database gateways. Specifies the maximum size in bytes of a bulk fetch page for retrieving data from a data source.

33,792 bytes.

LogAllSqlStmts

Occasionally you might set up the Scheduler to point to a database using a generic protocol like ODBC. This is usually done when the Target Type is not specified. When this happens, and a SQL statement fails, you must be able to determine which statement failed. Turning this setting on places the SQL statements in the Scheduler log file. Do not set this to TRUE in production mode as the overhead for this is quite high.

false

ServerPortNumber

Specifies the port number for the server. Defaults to the Oracle BI Scheduler port number.

The port number set for the Scheduler.

PurgeInstDays

Specifies the number of days after which old job instances are deleted from the back-end database automatically. To prevent old job instances from being deleted automatically, set the value to 0 (zero).

7 days

PurgeIntervalMinutes

Specifies the number of minutes in which Oracle BI Scheduler updates the tables and flags the affected rows as deleted.

Note: Oracle BI Scheduler does not actually issue SQL DELETE statements when jobs or instances are removed, instead rows are flagged for deletion.

After every X minutes (where X is defined as the value of this field), the actual SQL DELETE statements are issued.

60 minutes

MinExecThreads

Specifies the minimum number of multiple threads in the Oracle BI Scheduler thread pool that executes jobs at run time.

1

MaxExecThreads

Specifies the maximum number of multiple threads in the Oracle BI Scheduler thread pool that executes jobs at run time.

100

PauseOnStartup

Specifies that no jobs should execute when Oracle BI Scheduler starts. While Oracle BI Scheduler pauses, users can add, modify, and remove jobs. However, no jobs execute. From the Service Management menu, select Continue Scheduling to continue with regular execution.

false

CertificateFileName

Specifies the SSL Certificate File Path.

This setting supports SSL.

NA

CertPrivateKeyFileName

Specifies the SSL Certificate Private Key File.

This setting supports SSL.

NA

PassphraseFileName

Specifies the SSL File Containing Passphrase.

This setting supports SSL.

NA

PassphraseProgramName

Specifies the SSL Program Producing Passphrase.

This setting supports SSL.

NA

CertificateVerifyDepth

Specifies the SSL Certificate Verification Depth.

NA

CACertificateDir

Specifies the CA Certificate Directory.

This setting supports SSL.

NA

CACertificateFile

Specifies the CA Certificate File.

This setting supports SSL.

NA

TrustedPeerDNs

Specifies the SSL Trusted Peer DNs.

NA

VerifyPeer

Specifies whether to verify the peer.

This setting supports SSL.

false

CipherList

Specifies the Cipher List.

This setting supports SSL.

NA

ScriptRPCPort

Specifies the port used for interprocess communication between the script processes and the Oracle BI Scheduler process. This port accepts connections only from the same computer on which Oracle BI Scheduler is running.

9707


19.3.3.2 E-Mail Scheduler Configuration Settings That Affect Agents

Table 19-3 E-Mail Scheduler Configuration Settings That Affect Agents

Element Description Default Value

SmtpCipherList

Specifies the list of ciphers that match the cipher suite name that the SMTP server supports. For example, RSA+RC4+SHA. For information, see "Advanced SSL Configuration Options" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

NA

UseStartTLS

Ignored unless UseSSL is true. If UseStartTls is true, then use the STARTTLS option (RFC 2487) for the SMTP session. Initial connection is through an unsecured link, usually port 25. The connection is then promoted to a secure link using the STARTTLS SMTP command. If UseStartTls is false, then a secured connection is created immediately, before the SMTP protocol is started. This is also known as SMTPS. SMTPS typically uses port 465.

true


19.3.3.3 Agent Scheduler Configuration Settings

Agents are functionally a combination of data that is stored in Oracle BI Presentation Services and Oracle BI Scheduler. The elements in the Scheduler instanceconfig.xml file describe the behavior of all agents that run on a specific Oracle BI Scheduler. Table 19-4 describes each agent configuration element.

Table 19-4 Agent Scheduler Configuration Settings

Element Description Default Value

Log_Dir

Agents can create log files if exceptional error conditions occur. Log_Dir specifies the directory where these files are saved. The directory must be accessible to the Oracle BI Scheduler server. In Windows, the default installation runs the service as a system account, which prevents Oracle BI Scheduler from writing to or reading from network directories. If you put script files on network shares, or your scripts access network shares, then Oracle BI Scheduler must be run as a network user. For example:

For information about log files, see Section 8.5.6, "Diagnosing Issues with Agents."

ibots

LogPurgeDays

Specifies the number of days after which old agent logs are deleted automatically. To prevent old logs from being deleted automatically, set the value to 0 (zero).

7

NumGlobalRetries

A Web or mail server that has too many people logged on might reject new connections, including connections from Oracle BI Scheduler. To cope with such overload, an agent retries the connection. This element sets the maximum number of retries to obtain global information about what to deliver and to whom before the agent gives up. If you set this value to 0 (zero), then no retries are attempted.

2

MinGlobalSleepSecs

Specifies the minimum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to obtain global information about what to deliver and to whom.

3

MaxGlobalSleepSecs

Specifies the maximum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to obtain global information about what to deliver and to whom.

10

NumRequestRetries

After an agent has received the global information, it issues a series of unique requests to the server for each user. This element specifies the number of times Oracle BI Scheduler retries its attempts to connect to the server to issue these requests. If you set this value to 0 (zero), then no retries are attempted.

3

MinRequestSleepSecs

Specifies the minimum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to issue requests.

2

MaxRequestSleepSecs

Specifies the maximum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to issue requests.

10

NumDeliveryRetries

After a unique request has executed, the agent tries to deliver the results to specified devices. This specifies the number of times that Oracle BI Scheduler attempts to retry to connect to the server to deliver the results. If you set this value to 0 (zero), then no retries are attempted.

4

MinDeliverySleepSecs

Specifies the minimum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to deliver results.

5

MaxDeliverySleepSecs

Specifies the maximum number of seconds that the agent randomly sleeps after its connection is refused before it attempts to reconnect to the server to deliver results.

10

MaxRowsTimesColumns

When agents are chained, this value governs the size of filters passed between agents. When you pass a filter to another agent in a chain, Oracle BI Scheduler creates a union of the result sets for the Conditional Report for each personalized recipient. This report can grow very large in some cases (1000 users with 100 unique rows each with ten columns per report = 1,000,000 column values in the filter). The Oracle Business Intelligence servers might not be able to handle such a large filter, so this element specifies the maximum number of rows*columns in the filter.

10,000

Debug

Debug Enabled.

Set this element to have Oracle BI Scheduler generate a log file for each agent. This log file has useful logging messages when trying to diagnose a problem. This log file is stored in ORACLE_INSTANCE\diagnostics\logs\OracleBISchedulerComponent\coreapplication_obischn.

A new log file named Agent-<Job number>-<Instance number>.log is created for each job instance. The Job Manager can also be used to override the Debug setting for an individual job.

For more information, see Section 8.5.6, "Diagnosing Issues with Agents."

false

KeepErrorLogFiles

Set this element to true to generate an error log file for each agent. This log file is created only when an agent execution encounters errors and contains only error messages. The file is stored in ORACLE_INSTANCE\diagnostics\logs\OracleBISchedulerComponent\coreapplication_obischn.

true


19.3.4 Controlling Delivery Options for Agents

Delivery options (that is, delivery devices and delivery profiles) determine how the contents of agents are delivered to users. Delivery options can be configured by users, in the LDAP server (for e-mail addresses), or in the SA System subject area. See "Setting Up the SA System Subject Area" in Oracle Fusion Middleware Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition for information.

19.4 Managing Device Types for Agents

You can use different device types from such categories as mobile phones and pagers to deliver the content of agents to users. You can create, view, edit, and delete device types for a device category. Many device types are provided automatically. You can add types that are required for your users.

Note:

You can only view system-seeded device types (such as AT&T Wireless); you cannot edit or delete them.

The capability to manage device types is available to users who have the Manage Device Types privilege. For information about privileges, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

To create a device type:

  1. Log in to Oracle Business Intelligence.

  2. In the global header, click Administration.

  3. Click the Manage Device Types link to display the Manage Device Types page.

  4. Click the Create New Device Type link.

  5. Complete the Create New Device Type dialog, and click OK.

  6. Click Create Device Type to return to the Manage Device Types screen.

To view or edit a device type:

  1. In the global header, click Administration.

  2. Click the Manage Device Types link.

  3. Click the Edit button for the appropriate device type.

  4. Complete the Edit Device Type dialog, and click OK.

To delete a device type:

  1. In the global header, click Administration.

  2. Click the Manage Device Types link.

  3. Click the Delete button for the device type to delete.

    A confirmation box is displayed.

  4. Click OK to confirm the deletion.

For more information about the Administration page in Oracle Business Intelligence, see "Administration page" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

19.5 Monitoring Active Agent Sessions

Using the Manage Agent Sessions page in Oracle BI Presentation Services Administration, you monitor currently active agent sessions that are triggered by Oracle BI Scheduler. For example, you can see a list of active agents per session.

When one or more agent sessions are active, information about each agent session is displayed, such as the job identifier and the instance identifier that are assigned to the agent session by the Oracle BI Scheduler. Expanding the agent session shows the individual agents (one agent, or multiple agents if they are chained). The state of the agent is either Created, Populated, or Conditional Request Resolved.

Expanding a specific agent in a particular session shows the recipients for the agent and their type, such as the Engineering recipients defined in a group, or individual users. When the recipient is a group, the individual members of the group are not listed.

Note:

When agents are chained, the recipient list is depends on the parent agent. The recipients are shown for the parent agent definition only, and not for the actual execution of chained agents.

To view information about active agent sessions:

  1. In the global header, click Administration.

  2. Click the Manage Agent Sessions link to display the Manage Agent Sessions page and do one of the following:

    • To sort agent sessions by their values in a particular column, click the Sort button for that column.

      Re-sorting the list causes the page to refresh so the number of active agent sessions might increase or decrease as a result.

    • To view more information about an agent session or about agents within a particular session, click the Expand button.

    • To view the definition of an individual agent, click its link.

For more information about the Administration page in Oracle Business Intelligence, see "Administration page" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.