19 Configuring and Managing Agents

This chapter describes how configure and manage agents in Oracle Business Intelligence.

If your organization licenses 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. For information about using agents, see Delivering Content in User's Guide for Oracle Business Intelligence Enterprise Edition.

This chapter includes the following sections:

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 Diagnosing Issues with Agents for information about diagnostics and log files for agents.

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

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

How Do Antivirus Software and Privileges Affect Agents?

This section provides the following information about how antivirus software and privileges affect agents.

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 disable the script-blocking feature to prevent the software from unexpectedly blocking agent script calls.

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. See Managing Presentation Services Privileges in Security Guide for Oracle Business Intelligence Enterprise Edition.

Note:

If the Oracle BI Presentation Services 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 Security Guide for Oracle Business Intelligence Enterprise Edition. For information about pass-through login, see Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

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:

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.

  1. Open the instanceconfig.xml file for editing, located in:

    BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

  2. Locate the section in which you must add the elements that are described in the table below.
  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:
    
    
    <ServerInstance>
      <Alerts>
         <Enabled>false</Enabled>
         <DefaultDeliveryFormat>pdf</DefaultDeliveryFormat>
      </Alerts>
    </ServerInstance>
    
  4. Save your changes and close the file.
  5. Restart Presentation Services.
Element Description Default Value

Enabled

Specifies whether Oracle BI Delivers is enabled. Possible 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 emailed 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 email. As the administrator, you can specify the default format that is used for such emails, using one of the following values:

  • html
  • pdf
  • excel
  • text

html

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 schedulerconfig.xml file to change these settings. You must apply changes to both the primary and secondary scheduler's schedulerconfig.xml in a cluster.

  1. Open the Oracle BI Scheduler schedulerconfig.xml file for editing, located in:

    BI_DOMAIN/config/fmwconfig/biconfig/OBISCH

  2. Locate the sections in which you must add or update the elements described in What Additional Scheduler Configuration Settings Affect Agents?
  3. Include the elements and their ancestor elements as appropriate. The entry for <Log> is shown in the following example:
    <Log>
            <Level>
                    <Error>1</Error>
                    <IncidentError>1</IncidentError>
                    <Trace>0</Trace>
                    <Warning>1</Warning>
                    <Notification>1</Notification>
            </Level>
            <MaximumFileSizeKb>512</MaximumFileSizeKb>
            <MaximumLogAgeDay>3</MaximumLogAgeDay>
    </Log>

    Note:

    You cannot specify values for user name and password in the schedulerconfig.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.

What Additional Scheduler Configuration Settings Affect Agents?

Agents can be changed by scheduler configuration settings.

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

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.

The table below describes the settings.

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.

For information about modifying the database table names, see Changing Oracle BI Scheduler Table Names in 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, do not add or remove scripts from this directory. By default, this field is set to:

BI_DOMAIN/servers/obisch1

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:

BI_DOMAIN/servers/obisch1

scripts\common

TempPath

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

No default value

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

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.

7

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

MinExecThreads

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

1

MaxExecThreads

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

100

PauseOnStartup

Specifies that no jobs are executed 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.

No default value

CertPrivateKeyFileName

Specifies the SSL Certificate Private Key File.

This setting supports SSL.

No default value

PassphraseFileName

Specifies the SSL File Containing Passphrase.

This setting supports SSL.

No default value

PassphraseProgramName

Specifies the SSL Program Producing Passphrase.

This setting supports SSL.

No default value

CertificateVerifyDepth

Specifies the SSL Certificate Verification Depth.

No default value

CACertificateDir

Specifies the CA Certificate Directory.

This setting supports SSL.

No default value

CACertificateFile

Specifies the CA Certificate File.

This setting supports SSL.

No default value

TrustedPeerDNs

Specifies the SSL Trusted Peer DNs.

No default value

VerifyPeer

Specifies whether to verify the peer.

This setting supports SSL.

false

CipherList

Specifies the Cipher List.

This setting supports SSL.

No default value

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

Email Scheduler Configuration Settings that Affect Agents

Configure agents by specifying the following configuration settings.

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. See Enabling SSL in a Configuration Template Configured System in Security Guide for Oracle Business Intelligence Enterprise Edition.

No default value

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

Agent Scheduler Configuration Settings

Agents are functionally a combination of data that is stored in Oracle BI Server 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. The table below describes each agent configuration element.

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 information about log files, see 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

BI_DOMAIN/servers/obisch1/logs

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.

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

BI_DOMAIN/bi/servers/obisch1/logs

true

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 email addresses), or in the SA System subject area. See Setting Up the SA System Subject Area in Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition for information.

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. See Managing Presentation Services Privileges Using Application Roles in Security Guide for Oracle Business Intelligence Enterprise Edition.

  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.

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.

  1. In the global header, click Administration.
  2. Click the Manage Agent Sessions link to display the Manage Agent Sessions page.
  3. The Agent Sessions section displays a table with information about each agent session. You can see details such as the job identifier, the instance identifier, the primary agent, and the day and time at which the agent session was last accessed. 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.

    • Click the link in the Primary Agent column to display the agent in the Agent editor.

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

  4. The Agents section displays a table with information about each agent. You can see details such as the path for the agent and its state. The state can be either Created, Populated, or Conditional Request Resolved.Do one of the following:
    • Click the link in the Path column to display the agent in the Agent editor.

    • Click the Expand button to see the list of recipients for that agent.

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