Broadcast Agent Administrator s Guide

(1)

Broadcast Agent version 6.5 Windows and UNIX

(2)

If you find any problems with this documentation, please report them to Business Objects in writing at [email protected].

Trademarks Business Objects, the Business Objects logo, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners.

This product includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j.

Use restrictions This software and documentation is commercial computer software under Federal Acquisition regulations, and is provided only under the Restricted Rights of the Federal Acquisition Regulations applicable to commercial computer software provided at private expense. The use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in subdivision (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013.

Patents Business Objects owns the following U.S. patents, which may cover products that are offered and sold by Business Objects: 5,555,403, 6,247,008 B1, 6,578,027 B2, 6,490,593 and 6,289,352.

(3)

Contents

preface

(8)

Overview

Information, services, and solutions

The Business Objects business intelligence solution is supported by thousands of pages of documentation, available from the products, on the Internet, on CD, and by extensive online help systems and multimedia.

Packed with in-depth technical information, business examples, and advice on troubleshooting and best practices, this comprehensive documentation set provides concrete solutions to your business problems.

Business Objects also offers a complete range of support and services to help maximize the return on your business intelligence investment. See in the following sections how Business Objects can help you plan for and successfully meet your specific technical support, education, and consulting requirements.

(9)

Information resources

Whatever your Business Objects profile, we can help you quickly access the documentation and other information you need.

Where do I start?

Below are a few suggested starting points; there is a summary of useful web addresses on page 12.

Documentation Roadmap

The Documentation Roadmap references all Business Objects guides and multimedia, and lets you see at a glance what information is available, from where, and in what format.

View or download the Business Objects Documentation Roadmap at www.businessobjects.com/services/documentation.htm

Documentation from the products

You can access electronic documentation at any time from the product you are using. Online help, multimedia, and guides in Adobe PDF format are available from the product Help menus.

Documentation on the web

The full electronic documentation set is available to customers with a valid maintenance agreement on the Online Customer Support (OCS) website at www.businessobjects.com/services/support.htm

Buy printed documentation

You can order printed documentation through your local sales office, or from the online Business Objects Documentation Supply Store at

www.businessobjects.com/services/documentation.htm Search the Documentation CD

Search across the entire documentation set on the Business Objects

Documentation CD shipped with our products. This CD brings together the full set of documentation, plus tips, tricks, multimedia tutorials, and demo materials. Order the Documentation CD online, from the Business Objects Documentation Supply Store, or from your local sales office.

(10)

Multimedia

Are you new to Business Objects? Are you upgrading from a previous release or expanding, for example, from our desktop to our web solution? Try one of our multimedia quick tours or Getting Started tutorials. All are available via the Online Customer Support (OCS) website or on the Documentation CD.

How can I get the most recent documentation?

You can get our most up-to-date documentation via the web. Regularly check the sites listed below for the latest documentation, samples, and tips.

Tips & Tricks

Open to everyone, this is a regularly updated source of creative solutions to any number of business questions. You can even contribute by sending us your own tips.

www.businessobjects.com/forms/tipsandtricks_login.asp Product documentation

We regularly update and expand our documentation and multimedia offerings. With a valid maintenance agreement, you can get the latest documentation – in seven languages – on the Online Customer Support (OCS) website.

Developer Suite Online

Developer Suite Online provides documentation, samples, and tips to those customers with a valid maintenance agreement and a Developer Suite license via the Online Customer Support (OCS) website.

Send us your feedback

Do you have a suggestion on how we can improve our documentation? Is there something you particularly like or have found useful? Drop us a line, and we will do our best to ensure that your suggestion is included in the next release of our documentation: [email protected]

NOTE

If your issue concerns a Business Objects product and not the documentation, please contact our Customer Support experts. For information about Customer Support visit: www.businessobjects.com/services/support.htm

(11)

Services

A global network of Business Objects technology experts provides customer support, education, and consulting to ensure maximum business intelligence benefit to your business.

How we can support you?

Business Objects offers customer support plans to best suit the size and requirements of your deployment. We operate three global customer support centers:

• Americas: San Jose, California and Atlanta, Georgia • Europe: Maidenhead, United Kingdom

• Asia: Tokyo, Japan and Sydney, Australia Online Customer Support

Our Customer Support website is open to all direct customers with a current maintenance agreement, and provides the most up-to-date Business Objects product and technical information. You can log, update, and track cases from this site using the Business Objects Knowledge Base.

Having an issue with the product?

Have you exhausted the troubleshooting resources at your disposal and still not found a solution to a specific issue?

For support in deploying Business Objects products, contact Worldwide Customer Support at: www.businessobjects.com/services/support.htm

Looking for the best deployment solution for your company?

Business Objects consultants can accompany you from the initial analysis stage to the delivery of your deployment project. Expertise is available in relational and multidimensional databases, in connectivities, database design tools,

customized embedding technology, and more.

For more information, contact your local sales office, or contact us at: www. businessobjects.com/services/consulting.htm

Looking for training options?

From traditional classroom learning to targeted e-learning seminars, we can offer a training package to suit your learning needs and preferred learning style. Find more information on the Business Objects Education website:

(12)

Useful addresses at a glance

Address Content

Business Objects Documentation www.businessobjects.com/services/ documentation.htm

Overview of Business Objects

documentation. Links to Online Customer Support, Documentation Supply Store, Documentation Roadmap, Tips & Tricks, Documentation mailbox.

Business Objects Documentation mailbox

documentation@businessobjects. com

Feedback or questions about documentation.

Product documentation www.businessobjects.com/ services/support.htm

The latest Business Objects product documentation, to download or view online.

Business Objects product information

www.businessobjects.com

Information about the full range of Business Objects products.

Developer Suite Online

www.techsupport.businessobjects. com

Available to customers with a valid maintenance agreement and a Developer Suite license via the Online Customer Support (OCS) website. Provides all the documentation, latest samples, kits and tips.

Knowledge Base (KB)

www.techsupport.businessobjects. com

Technical articles, documents, case resolutions.

Also, use the Knowledge Exchange to learn what challenges other users – both customers and employees – face and what strategies they find to address complex issues. From the Knowledge Base, click the Knowledge Exchange link.

(13)

Useful addresses at a glance Tips & Tricks

www.businessobjects.com/forms/ tipsandtricks_login.asp

Practical business-focused examples.

Online Customer Support www.techsupport.businessobjects. com

www.businessobjects.com/ services

Starting point for answering questions, resolving issues.

Information about registering with Worldwide Customer Support. Business Objects Education

Services

www.businessobjects.com/ services/education.htm

The range of Business Objects training options and modules.

Business Objects Consulting Services

www.businessobjects.com/ services/consulting.htm

Information on how Business Objects can help maximize your business intelligence investment.

(14)

About this guide

This guide describes the architecture of Broadcast Agent Scheduler and explains the main administrative tasks required to set up and maintain a Broadcast Agent Scheduler system.

Audience

This guide is intended for systems administrators who already have a working knowledge of the following:

• The operating system(s) on which the system is running (Microsoft Windows or UNIX).

• The Business Objects product suite.

Conventions used in this guide

The conventions used in this guide are described in the table below.

Convention Indicates

Small capitals The names of all products such as

BusinessObjects, WebIntelligence, Supervisor, and Designer.

This font Code, SQL syntax, computer programs. For

example: @Select(Country\Country Id).

This font is also used for all paths, directories, scripts, commands and files for UNIX.

Some code more code

Placed at the end of a line of code, the symbol ( ) indicates that the next line should be entered continuously with no carriage return.

$DIRECTORYPATHNAME The path to a directory in the Business Objects installation/configuration directory structure. For example:

• $INSTALLDIR refers to the Business Objects installation directory.

• $LOCDATADIR refers to a subdirectory of the BusinessObjects installation directory called locData.

(15)

(16)

Overview

Broadcast Agent enables WebIntelligence and BusinessObjects users to process and distribute documents, automatically and securely, at scheduled dates and times.

For example, you can schedule a document to be refreshed from a corporate database on the first Monday of every month, and have the new information distributed automatically to user groups. Documents can be distributed via a secured Business Objects repository, a local file system, an intranet, or an extranet.

Broadcast Agent effectively shields users from the complexity of the underlying system. Users schedule tasks by means of a simple graphical user interface. For systems administrators, the Business Objects Administration Console provides easy configuration and optimization of modules on all servers.

Broadcast Agent is a server product, installed as a distributed solution across one or more servers on a CORBA network. This architecture enables Broadcast Agent to offer robust performance, scalability, load balancing, and failover. To use Broadcast Agent you must be familiar with Supervisor.

(17)

Structure of this guide

This guide is divided into the following chapters: • Introduction to Broadcast Agent (this chapter)

Provides an overview of the product and what you can do with it. • How Broadcast Agent Works

Introduces the components and tools that make up the complete Broadcast Agent system, and explains how these work together in a clustered

deployment.

• Deploying Broadcast Agent

Discusses issues related to deployment and sizing. Includes a number of tasks you need to perform before beginning the installation of Broadcast Agent.

• Installing and Configuring Broadcast Agent

Reviews the tasks necessary to install and configure the product. • Using the Broadcast Agent Console

After Broadcast Agent is installed on your servers, and documents are scheduled, you can monitor and control Broadcast Agent activity with the Broadcast Agent Console.

The Console displays information about all scheduled tasks, and can also be used to change task information.

• Troubleshooting

Provides solutions to a number of possible issues, such as how to fix a failed connection to the repository.

• Problem-solving with Broadcast Agent

Examines some advanced ways to use Broadcast Agent, focusing on how the product can dramatically improve the performance of an enterprise business intelligence solution.

(18)

What you can do with Broadcast Agent

You can use Broadcast Agent to schedule documents for processing and distribution at off-peak times. This cuts down on network traffic at peak times, and enables documents to be automatically printed or refreshed via the Internet at night or over the weekend.

You can also set conditions, so that Broadcast Agent processes and distributes documents only when specified conditions occur. For example:

• increased revenue in a given region

• daily sales figures for a given product pass a certain value

Automated document scheduling and distribution

Broadcast Agent provides scheduled or batch processing of BusinessObjects and WebIntelligence documents. You send a document to Broadcast Agent using BusinessObjects or InfoView, specifying scheduling and distribution information. No understanding of the server configuration is required.

You can publish documents on the repository, on a web server, or on the server file system.

Users with access to the repository can view corporate documents that Broadcast Agent has processed.

Adding VBA routines

Broadcast Agent can automate BusinessObjects documents containing routines written in Microsoft VBA (Visual Basic for Applications) development language. By adding VBA routines to your BusinessObjects documents, you can customize the system to automate almost any task.

For example, a scheduled report could:

• trigger a speech synthesizer call to a mobile telephone if a certain condition is met

• generate email messages or pager signals to alert individuals to a given situation

Report bursting

Power users with access rights to all documents and database connections might not want all the people who receive a document to see the same information. Report bursting answers this need by letting you automatically generate different versions of a document. Each version is sent to individuals with a given user profile. (See Report bursting on page 81.)

(19)

What you can do with Broadcast Agent BusinessObjects Supervisors set up these user profiles. Profiles define access rights, such as the data each user can view, which database connections are available, which universes, and so on.

(20)

Access and security

You can deploy Broadcast Agent for any group of BusinessObjects or

WebIntelligence users. Users can schedule operations on both WebIntelligence and BusinessObjects documents if they have the required access rights. The administrator—that is, a supervisor-level user—grants these access rights in Supervisor.

The supervisor also defines Broadcast Agent properties, such as: • the Broadcast Agent name

• the document domain in which documents are stored • a password for the Broadcast Agent Console

Broadcast Agent benefits from the access and security provided by the Business Objects repository:

• Pass-through database security

Broadcast Agent can be configured to connect to the database using the user name and password of the user who scheduled the document. This allows the use of only one password, which simplifies administrative work.

• Multiple repositories

Broadcast Agent asks for the security domain when a document is scheduled, then passes this information to the appropriate server at run time.

(21)

(22)

Overview

This chapter presents the components and tools that make up the complete Broadcast Agent system, and explains how these work together in a clustered deployment to provide a distributed solution. You can deploy Broadcast Agent on a UNIX cluster, a Windows cluster or a mixed (heterogeneous) cluster. A number of limitations and performance considerations are reviewed.

In the next chapter, the issues involved in deploying Broadcast Agent are discussed, along with some server sizing guidelines and recommendations for configuring database connections.

(23)

Broadcast Agent server components

The Broadcast Agent system contains a number of interdependent server components. You configure and monitor these components in the Administration Console.

The server components are summarized in the table below.

Schedulers

There must be at least one Scheduler for each named Broadcast Agent. Each Scheduler periodically queries the repository to determine which documents are due for processing. In the Administration Console, you determine how frequently the Scheduler queries the repository by setting the Scanning Repository Delay parameter. By default, the scan occurs every ten minutes.

When a scheduled task is due, the Scheduler sends the task to a BOManager process, for BusinessObjects documents, or a wiqt_batch process, for

WebIntelligence documents. There may be several of these processes running on machines in your cluster, in which case a load-balancing algorithm is used to send the task to the least busy machine.

If a task fails, the Scheduler automatically retries it after a certain delay. This delay is set using the Delay between retry parameter.

Component Function

Scheduler Initiates the processes required to perform scheduled tasks. Broadcast

Agent Manager

Starts and controls multiple Schedulers.

BusObj Refreshes BusinessObjects (full-client) documents. BOManager Starts and controls multiple BusObj processes. Batch

processing can be enabled or deactivated on each node, to allow or prevent Broadcast Agent tasks being scheduled on that node.

WIQT WebIntelligence Query Technique. Refreshes WebIntelligence 2.x documents in interactive mode

(documents on which a user is currently working) as well as in batch mode (scheduled tasks).

WICDZServer The WebIntelligence 6.x server. This multi-threaded component processes requests for WebIntelligence 6.x documents.

(24)

What happens if a Scheduler shuts down or fails?

You can provide Scheduler failover functionality by deploying two or more Schedulers on separate servers. If one machine fails, the other Scheduler automatically takes over the failed Scheduler’s jobs. The multiple schedules can be in the same cluster or on separate ones. As long as they reference the same repository they can pick up the same jobs.

To provide further failover, you can run two separate clusters on the same repository, both with Schedulers for your mission-critical Broadcast Agent tasks. With this configuration, even if an entire cluster fails, the tasks are processed correctly.

BOManager

BOManager receives instructions from the Scheduler to process full-client documents that are due. BOManager launches one BusinessObjects session, or re-uses an existing loaded process, per document. BusinessObjects then extracts the documents from the repository’s document domain, and processes them according to actions set by the user at submission time. Normally, the document is refreshed, and then published as a corporate document, via either the file system, through a web server, or sent to one or more users via the repository.

EXAMPLE

Scheduling a document for automatic refresh

A user requests that Broadcast Agent refresh a document named Sales.rep at 8:00 pm on Friday:

• The first time the Scheduler queries the repository after 8:00 pm, it retrieves the information that Sales.rep is due for processing, and passes this on to the BOManager.

• BOManager launches a BusinessObjects process. • BusinessObjects extracts Sales.rep from the repository.

BusinessObjects on the server runs the Refresh command, saves the updated document, and then returns it to the repository.

(25)

Broadcast Agent server components BusinessObjects on UNIX and Windows

On UNIX nodes, the executables started by the BOManager to process BusinessObjects documents are called bolight whereas on Windows nodes the executables are called busobj.exe. The functionality of these two components is the same except for certain Windows-specific features, such as VBA macros or certain database connectivities.

WIQT

The Scheduler scans the repository for scheduling jobs that are due. When a WebIntelligence 2.x document is due, the Scheduler requests a wiqt process to refresh the document.

In turn, wiqt calls a wiqt_batch process, which fetches the document, and then processes the task according to the actions set by the user. For example, the document could be refreshed and then published as a corporate document, or sent to a list of users via the repository.

WICDZServer

WICDZServer receives instructions from the Scheduler to process WebIntelligence 6.x documents that are due. It then launches one WebIntelligence session per document. WebIntelligence then extracts the documents from the repository’s document domain, and processes them according to actions set by the user at submission time. Normally, the document is refreshed, and then published as a corporate document, or sent to one or more users via the repository.

(26)

Workflow summary

Using BusinessObjects or InfoView, users send documents to Broadcast Agent. They set the actions they want Broadcast Agent to perform, along with options for scheduling, categories, and distribution.

The documents that users send to Broadcast Agent are stored in the repository’s document domain that has been allocated to that Broadcast Agent.

The Scheduler periodically scans the domain and extracts documents that are due for processing.

The Scheduler passes due BusinessObjects documents to the BOManager, which launches one instance of BusinessObjects on the server per document. Similarly, WebIntelligence documents are passed to a wiqt process (via the WICDZServer in the case of a WebIntelligence 6.x document).

On the server, BusinessObjects or WIQT performs the actions the user requested on the document.

(27)

Workflow summary The diagram below summarizes this workflow.

WebIntelligence or BusinessObjects user

Corporate database

Repository

Documents refreshed

WebIntelligence or BusinessObjects users

Broadcast Agent

Scheduler

Task 1 Task 2

BOManager

busobj instance

wiqt instance

Task 3 wiqt instance

(28)

Monitoring and controlling Tasks

Broadcast Agent Console

When Broadcast Agent is functioning, users can begin scheduling documents. You monitor the processing activity by viewing the list of sent documents and their characteristics. This is done in the Broadcast Agent Console. (The Console is fully described in The Broadcast Agent Console on page 93.)

The Console enables you to:

• monitor the status of all processed and pending tasks • modify tasks

• reschedule tasks that have either failed or expired

• execute actions such as deleting a task or running a task immediately The Console has direct access to both the Scheduler and the repository, and can be located on any machine that has access to the repository and is on the same subnet as the CORBA network. For more information, refer to Broadcast Agent as a distributed solution on page 30.

The Console is also available in BusinessObjects and InfoView, so that BusinessObjects users can monitor the documents they send to Broadcast Agent.

(29)

Monitoring and controlling Tasks

Administration Console

The Administration Console is a utility that allows you enable, deactivate, and control the Broadcast Agent Managers and Schedulers on your cluster, as well as all the other modules on your BusinessObjects and Broadcast Agent systems. You must install the Administration Console before you deploy Broadcast Agent. For a full description of the modules, see the Administrator’s Guide.

(30)

Broadcast Agent as a distributed solution

Broadcast Agent is a collection of server components that can be deployed over a distributed CORBA network. You can also install all Broadcast Agent

components on a single server, in a Windows environment. In this case, the only connection you require is to the repository. (Deployment is fully explained in Deploying Broadcast Agent on page 33.)

Setting up Broadcast Agent as a distributed solution, however, provides the following advantages:

• Scalability

CORBA enables server solutions to be deployed on multiple server machines. As the document scheduling and distribution needs of your organization grow, you can manage the extra workload by adding Broadcast Agent machines to your network.

• Load balancing

Broadcast Agent allows you to distribute your document processing over several different machines, in order to balance the workload. When one server is busy, jobs are processed by the next server.

• Failover

Failover ensures that Broadcast Agent automatically restarts tasks that fail, in the event of a server crash. Broadcast Agent provides two types of failover: - When a task fails, the Scheduler automatically starts the task again on another server, if necessary.

- If the Scheduler itself fails, Broadcast Agent automatically restarts it. • Server optimization via caches

The Business Objects product line includes several cache mechanisms to improve server performance, especially in large deployments.

Because of these advantages, Business Objects recommends that you deploy Broadcast Agent as a distributed solution, that is, in a cluster.

The Broadcast Agent cluster

A Broadcast Agent cluster contains one or more server machines, each hosting one or more nodes that run Broadcast Agent server processes.

Clusters contain the following types of nodes: • Primary node

The primary node serves as the central coordinator between all the nodes in the cluster. There is only one primary node per cluster; if the cluster contains

(31)

Broadcast Agent as a distributed solution only one node, it is the primary node.

• Secondary node • Client node

A client node can be used to access the Broadcast Agent through the Broadcast Agent Console, and to use the Administration Console without being on the server itself. A CORBA connection is required.

Under Windows, only one node can be configured per server machine. Under UNIX, multiple nodes can be hosted on a single machine, if each of them belongs to a different cluster.

In a heterogeneous cluster, that is, mixed UNIX and Windows servers, you can make the file systems visible to each type of server. You can do this with third-party tools such as Microsoft UNIX Services for NT, or the Open Source product, Samba. For details, see the documentation for these products.

(32)

(33)

(34)

Overview

This chapter discusses issues related to deployment and sizing. These issues include:

• Sizing guidelines

Looks at the factors that impact the size and number of machines you need for Broadcast Agent.

• Matching components to machines

Which Broadcast Agent component should you run on which machine? • UNIX vs. Windows

You can deploy Broadcast Agent in a UNIX cluster, a Windows cluster or in a mixed, or heterogeneous, cluster. A number of limitations and performance considerations are reviewed.

• Optimizing performance

For example, optimizing your servers by using caches. • Server filenames, pathnames, and permissions

The proper formats are discussed. • Configuring database connections

• Using Broadcast Agent with Lightweight Directory Access Protocol (LDAP) The chapter also includes a number of tasks you need to perform before starting to install Broadcast Agent.

(35)

Sizing guidelines

The size and number of machines you need for Broadcast Agent varies depending on a number of factors, including the:

• quantity of documents to be scheduled • complexity of the documents

• refresh frequency

• speed of the connection between the repository and the Broadcast Agent server

• speed of the underlying database

• number of users simultaneously accessing the data

In general, a document being processed by Broadcast Agent requires the same amount of RAM and CPU time as if it were processed in the same way by an interactive user.

If 100 documents are scheduled for refresh at the same time, it is the equivalent of 100 concurrent users—all logged in and running simultaneous queries. If your system is unable to cope with the level of activity requested, then some tasks may fail or be delayed until the system is less busy. Take this into account when making decisions about server sizing, as well as when scheduling your

documents.

If you use multiple-refresh report bursting (see Report bursting on page 81) with options set to refresh each user’s copy of a report according to that user’s profile, a separate refresh is carried out for each recipient. In other words, if you burst a document according to the profile of 100 recipients, it carries the same load as refreshing the document 100 times.

Memory requirements by document type

The amount of RAM required for each document to be processed depends on its length and complexity. Typical requirements are as follows:

• WebIntelligence version 2.x documents: 6-40 MB; average size 12 MB • WebIntelligence version 6.x documents: 2-40 MB; average size 10 MB • BusinessObjects documents: 12-40 MB; average size 16 MB

The document size is the same whether the server is UNIX- or Windows-based. The best way to ensure the memory requirements for your deployment is to build the reports on a test system and find out how large they actually are. You can then size your servers accordingly.

(36)

Number of Broadcast Agents and Schedulers

You can configure multiple Broadcast Agents in your deployment, and multiple Schedulers for each Broadcast Agent. The advantage of having several Broadcast Agents is that you can have one for each user group for example, Sales and Finance, defined in each repository.

One advantage of having two or more Schedulers for each Broadcast Agent is for failover. Without a working Scheduler, no jobs are processed. Because an additional Scheduler does not use significant resources, many configurations include two Schedulers on different machines for each Broadcast Agent. In this way, even if one node fails, the tasks are still processed.

A typical cluster configuration has one or more Schedulers, plus either a BOManager or WIQT, on every secondary node.

(37)

Matching components with machines

This section explains which Broadcast Agent components to run on which machines. (For information on components, see Broadcast Agent server components on page 23.)

You are not obliged to set up your Broadcast Agent cluster over multiple servers. If you decided to install all components on one machine, you must declare the machine as the primary node when you install Broadcast Agent.

Running Broadcast Agent server software and BusinessObjects client software on the same machine is not recommended. When Broadcast Agent or

WebIntelligence services are running, they automatically launch and stop BusinessObjects instances. On the same machine, these system sessions can interfere with the interactive BusinessObjects user session.

The machine running the Scheduler does not need exceptional processing power or disk space. However, machines running BOManager and WIQT require much more processing power.

NOTE

You can limit the number of processes that are run concurrently on each machine by using the parameter settings in the WIQT and Scheduler modules. (See Report bursting on page 81.)

Any machine that runs the BOManager or WIQT processes must be equipped with at least 256MB of RAM, but Business Objects recommends more if possible. You must have an additional 16 MB for each job that it is configured to run concurrently.

We recommend that you also configure sufficient swapping space to allow for peak conditions. Keep in mind that:

• if a job cannot be handled with the available RAM, swapping occurs and processing slows down.

• if swapping occurs and the swapping space is exceeded, performance is greatly affected, and eventually the system may become unstable.

NOTE

Do not install Broadcast Agent on the same machine as the repository database server.

(38)

A WebIntelligence session use the BOManager located on the same node as the other processes involved in the session (WISessionManager, WIApiBroker, WIQT, WIReportServer, WIDispatcher).

A Scheduler on any machine can process documents (using WIQT or

BOManager) on any machine in the same cluster, if the component is enabled and its Enable Batch Processing parameter is set to On. The Scheduler itself uses very little CPU time or RAM, and can easily reside on the same machine as a BOManager or wiqt process without significantly impacting performance. The Broadcast Agent Console and the Administration Console are relatively lightweight user interfaces, and do not consume significant resources. They can be installed on any machine on the subnet, not necessarily a server node, but they must be installed on a client node at least.

If your system is processing both WebIntelligence 2.x and 6.x documents, you can set the Max No WebI 2.x jobs running and Max No WebI 6.x jobs running parameters to proportionally balance the load between the two types. For example, if you have 80% of your scheduled documents in WebIntelligence 2.x format, and only 20% in 6.x, then set the Max No WebI 2.x jobs running to four times the Max No WebI 6.x jobs running.

(39)

UNIX or Windows?

You can deploy Broadcast Agent on either a UNIX cluster, a Windows cluster, or a mixed, or heterogeneous, cluster. Using a heterogeneous cluster, you can utilize the additional functionality of Windows for some tasks, while still using your UNIX machines for other tasks. In this environment, the BOManagers in a given cluster that are used for interactive processing (Enable Interactive Processing set to On) must be all on UNIX or all on Windows.

When used for batch processing (Enable Batch Process set to On), BOManager can run on both UNIX and Windows systems. Broadcast Agent redirects tasks as needed.

In general, UNIX nodes can be used to process the majority of tasks, while Windows nodes provide some additional connectivities and functionalities, such as access to OLAP data sources

The following Broadcast Agent functionalities are available on Windows only: • Direct access to some OLAP data sources

Contact Business Objects customer support for the current list of supported OLAP servers.

• Visual Basic procedures used as data providers • Personal data files

• Custom macros in VBA

These macros depend on Microsoft proprietary technologies that are not currently supported under UNIX.

• Some RDBMS data sources

Contact Business Objects customer support for current information.

If your users need to access any of the above functionalities via Broadcast Agent, you must use Windows nodes for executing Broadcast Agent tasks that is, with a BOManager process enabled.

You can set up multiple Broadcast Agent Schedulers and BOManager processes, on either UNIX or Windows nodes, in the same cluster.

NOTE

For a full, up-to-date list of supported tools on both Windows and UNIX, contact Business Objects customer support.

(40)

Optimizing performance

Using the Administration Console, you can optimize Broadcast Agent performance by specifying:

• the number of documents per day that Broadcast Agent can process simultaneously

• how often the Scheduler checks the repository for waiting tasks • how long Broadcast Agent waits before reloading a failed task

For more information about the Administration Console, see Enabling and disabling components on page 73.

Server optimization using caches

The Business Objects product line includes several cache mechanisms to improve server performance, especially in large deployments.

Login cache

After users execute a task via Broadcast Agent, they do not have to log in again when submitting subsequent tasks. BOManager caches their login information for each Broadcast Agent task. If users have the appropriate access rights, the session context for the task is restored directly from the cache.

The life span of cache entries is controlled by the Scheduler login cache duration parameter in BOManager. (See Report bursting on page 81.) The login cache is for BusinessObjects Full Client reports only.

Presentation cache

To help prevent overloads at peak transaction periods, you can preload the cache when you process a task. When you schedule a corporate document with Broadcast Agent from BusinessObjects, you can cache the document’s presentation by using one of the following options:

• Enhanced Document Viewing

Generates the document in metafile format, which is recognized by the ActiveX viewer in InfoView. The metafile is then stored in the server cache. • Standard HTML

Generates the HTML for scheduled corporate documents, suitable for the standard HTML document viewer in InfoView.

• PDF

Available for other users without any need to regenerate the PDF, unless a change has occurred in the document.

(41)

Optimizing performance To access these options in BusinessObjects:

1. From the File menu, select Publish To and Corporate Documents. The Send dialog box opens.

2. Click Schedule...

The Schedule Corporate Documents dialog box opens. 3. Click the Actions tab.

4. Click Faster Document VIewing Over The Web, then click Options... The Select the document format dialog box opens with the available categories that correspond to the cache options.

The first time an InfoView user asks to view the document in a certain format, BOManager retrieves the presentation and stores it in a cache on the Storage Manager machine. The generated files are then removed after the document is viewed for the first time, and the document itself is passed to the InfoView cache. When other users then access the document in InfoView, they access a pre generated file.

This means that:

• InfoView requests for BusinessObjects documents do not require logging into BOManager

• there are fewer demands on available processes in your cluster

• the document’s presentation doesn’t have to be generated—the document is displayed faster and more efficiently

• response time remains constant and doesn’t depend on the document’s size or complexity

• CPU power and busobj processes are made available for refreshing documents (ad hoc queries)

(42)

In large organizations, where important documents are viewed regularly by thousands of users, caching can prevent critical system congestion and overload.

Encourage users to preprocess all corporate documents that they expect will be viewed by multiple users—particularly PDF documents, which may require substantial processor time to generate.

Schedule documents to be refreshed often. If the cached presentation is always up-to-date, recipients won’t need to refresh them.

Cached documents take up only about 5 KB of disk space per document, plus 20 KB per metafile page. PDF and HTML documents, by contrast, often reach several megabytes.

Do you need to install an HTTP server to use Broadcast Agent?

An HTTP server is needed to run WebIntelligence, and also to use the Publish to Channel and Distribute via Web operations in Broadcast Agent. You don't need to install an HTTP server if you wish to use Broadcast Agent only in conjunction with full-client BusinessObjects. Broadcast Agent automatically detects the web server when InfoView is not installed.

(43)

Server filenames, pathnames, and permissions

Broadcast Agent users specify a pathname and filename when using:

• the File Watcher option to schedule tasks to run only when a specific file is present

(See File Watcher on page 118.)

• the Distribute via File System option to copy a scheduled document to a specific location

• the Distribute via Web Server option • Save as RTF

• Save as TXT • Save as PDF • Save as XLS

These functions are accessed via the Actions and Distribution tabs of the Send Document to Broadcast Agent dialogue box in BusinessObjects.

The pathname relates to the server on which the process (BOManager) is running, not to the user’s machine.

For example, if the user selects Save as RTF with the filename C:\MyFile, Broadcast Agent attempts to save the file to that location on the server, not on the client.

NOTE

To specify a pathname or filename on a machine other than the server on which the Broadcast Agent is running, you must specify a full UNC (Universal Naming Convention) name; for example (under Windows):

\\MyMachine\SharedFolder\MyFile.

The BOManager executing the scheduled task must have the required permissions:

• to write to the file itself and its parent folder • to access every folder in the path

For example, if a Windows user specifies Save as TXT with the filename: \\MyMachine\MyFolder1\MyFolder2\MyFile

then the BOManager must have permission to access MyMachine, MyFolder1, MyFolder2, and MyFile, and permission to write to MyFolder2 and MyFile.

(44)

Instead of specifying a filename, you can send a job through Broadcast Agent on a UNIX machine using the default location. The default location for all scheduled jobs in the $BO_FILE_PATH environment variable is defined in the following directory: $INSTALLDIR/nodes/servername/mycluster/MyWebIEnv.sh.

UNIX and Windows pathname conversion

Broadcast Agent automatically converts Windows pathnames (with backslash delimiters, “\”) to UNIX pathnames (with forward slash delimiters, “/”) when needed. This conversion is transparent to the user. For example, if you specify the path:

\usr\current

it is interpreted by a Scheduler on a Windows server as c:\usr\current

(where c: is the default drive), or on a UNIX scheduler as /usr/current.

NOTE

Encourage users to follow the Windows convention (with a backslash) as this is interpreted correctly on either system. UNIX format pathnames (with a “/”) will be interpreted correctly only on UNIX servers.

You can mount file systems on UNIX servers to map to file systems on another networked UNIX machine, so that users have the functionality they require without needing to know the physical location of the files. See your UNIX documentation for further information.

Ensure that directories are mounted appropriately on UNIX machines so that any Windows files that users need to access from UNIX systems are in accessible folders.

Inform users that Windows filenames are not case sensitive. UNIX filenames, however, are case sensitive.

NOTE

When you use a printer other than the default printer, you must enter its path in the Select the Printer box under Print Properties. The printer name entered here must be in exactly the same case (the combination of upper and lower case letters) as the printer name specified on the server.

(45)

Server filenames, pathnames, and permissions

Setting the $BO_FILE_PATH variable

On a UNIX server, you can define the variable $BO_FILE_PATH to enable Windows filenames to map to UNIX file names correctly.

For example, you can add the following line to the WebIEnv.sh file:

BO_FILE_PATH=/opt/webidoc/ ; export BO_FILE_PATH

and the following line to the WebIEnv.csh file:

setenv BO_FILE_PATH /opt/webidoc/

This causes the pathnames specified to be mapped, as shown in the following table.

NOTE

The conversion results in lower-case UNIX pathnames, regardless of the case used in Windows.

What users do

The path that the BusinessObjects user enters in the Save As, Distribute via Web Server or Distribute via the Server File System boxes in the Send Document to Broadcast Agent dialog box depends on whether you, the administrator, define

the BO_FILE_PATH variable.

Path naming convention

You can name paths in any of the following formats:

• UNC, which expresses the location on the network by giving a machine name as well as a path:

\\<machinename>\<pathname>\<filename>

Windows path UNIX path on server

MyFile /opt/webidoc/myfile

\\Server\MyFile /opt/webidoc/server/myfile

(46)

NOTE

Business Objects recommends using UNC. This avoids any confusion, and enables the process to succeed even if the Scheduler is running on a different machine.

• Mapped network drive, on the server running the Scheduler: <mapped drive letter>:\<pathname>\<filename>

• Local, relative Windows filename: \<pathname>\<filename>

• Local, absolute Windows filename (local to the server, not the client): C:\<pathname>\<filename>

• Local UNIX filename:

/<pathname>/<filename>

The table below summarizes the various formats.

Shield users from these issues by mapping and mounting structures appropriately, and informing users what the best practice is.

EXAMPLE Pathnames

A user wants to use File Watcher to schedule a report called MyReport, to be refreshed whenever the file Update_Completed is present.

The Update_Completed file is automatically created by a weekly update process, whenever the data warehouse is updated with new data. The file is stored on a UNIX server called Orion, located in

/usr/datawarehouse/Update_Completed

Path format UNIX Windows

UNC Finds locally or

remotely

Finds locally or remotely

Mapped network drive Fails Finds if mapped drive is set up on server Local relative Windows filename Finds locally Finds locally Local absolute Windows filename Fails Finds locally Local UNIX filename Finds locally Fails

(47)

Server filenames, pathnames, and permissions If the Broadcast Agent Scheduler and BOManager are running on a UNIX server called Pluto, and the user specifies:

then the task will never be executed because the file cannot be found. However, if the Scheduler is running on the same server machine (Orion), the user can specify the path in File Watcher as:

\usr\datawarehouse\Update_Completed

or

To be safe, wherever the Broadcast Agent Scheduler is running (Windows or UNIX), specify:

\\Orion\usr\datawarehouse\Update_Completed

HTML and web server filenames

When Broadcast Agent sends an HTML format file to a web server using the Distribute via Web serveraction, it automatically converts the following characters in the file name so that they conform to standard web usage: • ampersand (&)

• empty space

These characters are converted to an underscore. For example, a file named Alpha & Beta.rep becomes Alpha_Beta.rep when it is saved in HTML.

(48)

Configuring database connections

Broadcast Agent may establish hundreds of database connections per day. The configuration of these connections is therefore critical to the efficiency of your deployment.

Broadcast Agent connects to both the security and document domains:

• the Update repository delay transaction connects only to the security domain • the Scanning repository delay transaction connects to both the security and

the document domains

Configuration guidelines

When configuring your connections, you can choose from the following options in the Advanced tab of the Connections dialog box:

• Keep the connection active during the whole session • Keep the connection active for X minutes

• Disconnect after each transaction

Business Objects recommends using either Keep the connection active for X minutes or Disconnect after each transaction.

The reason is that an internal module called SQLBO handles a pool of

connections to the different domains involved. The connection can be physically closed (Disconnect after each transaction) or only logically closed (Keep the connection active during the whole session).

Using shared and personal connections

Most BusinessObjects documents access data through a secured connection that is stored in the repository. However, BusinessObjects users can also create documents that access data through personal connections or shared

connections, which are not defined in the repository. These types of connection are defined in two locations:

• in the document itself

• in LSI (Local Security Information) files stored in the LocData folder on the user’s machine: pdac.lsi for personal connections, and sdac.lsi for

shared connections.

When users send documents based on shared connections to Broadcast Agent, the connection information is obtained from within the document itself. However, if the document contains a VBA macro which directly accesses the shared connection, the sdac.lsi file on the server must contain the shared connection

(49)

Configuring database connections

LocData folder

All Broadcast Agent servers and BusinessObjects client machines use a LocData folder, whose location is determined during the installation process using the Configuration Tool.

In many deployments, a single LocData folder on the primary node is referenced by all the other machines over the network, in order to simplify administration. This folder contains files which define the database connections:

• bomain.key

Defines the default connection to the repository. • additional .key files

These define connections to alternative repositories that the user can reference at login.

• sdac.lsi file

Defines shared connections • pdac.lsi

Defines personal connections Recommended configuration

If you want shared connections to be available to all users (rather than just to the user who created the connection), set all the cluster machines and client machines to use the LocData folder on the primary node.

When the installer on each machine asks for the path of the LocData folder, give the network path of the LocData folder on the primary node. This folder must be under a mapped network drive on each Windows machine, or a mounted network path on each UNIX machine in the deployment. All machines then access the same .lsi and bomain.key files.

Synchronizing sdac.lsi files

If you do not set all the cluster machines and client machines to use the LocData folder on the primary node, you need to verify that all BusinessObjects client machines and Broadcast Agent servers have a copy of the same sdac.lsi file in their local LocData folder. When you install the secondary nodes, their

sdac.lsi files are automatically replaced with a copy of the sdac.lsi file from

(50)

When a user adds a new shared connection, the new sdac.lsi file must be

copied to all other clients and to the servers. To update all the secondary nodes, copy the new sdac.lsi file to the primary node and click the Cluster files

synchronization button in the Administration Console. This copies the .key files and the sdac.lsi file from the primary node to the secondary nodes.

Enabling VBA custom macros to access shared connections

If a user sends a document based on a shared connection to Broadcast Agent, and the document includes a VBA custom macro that directly accesses the shared connection, the sdac.lsi file in the LocData folder on the machine

where the VBA code is running must contain the connection information for the shared connection.

If the sdac.lsi file on the server does not include the shared connection, then

the task will fail with the following error:

(303) Error with no ErrorHandler with BreakOnVBAError =FALSE.

If all machines in the deployment share the same LocData folder on the primary node, the task will be processed correctly because there is only one sdac.lsi

file in the cluster and it includes all shared connections.

Documents containing OLAP data providers

In BusinessObjects, you can retrieve data from OLAP servers, if you have installed the BusinessObjects Access Pack for these products. This section covers what users can and cannot do when they schedule documents containing OLAP data providers.

NOTE

Broadcast Agent now refreshes WebIntelligence OLAP documents in Windows.

Users can schedule documents containing data providers built on a Microsoft OLAP Services database, but must verify that the BOManager user account has permission to access the OLAP Services database.

Microsoft OLAP Services authenticates users with Windows security information. The users’ Windows login, not their BusinessObjects login, allows access to the data in the OLAP Services database. When users manually refresh a

BusinessObjects document containing an OLAP data provider, the database retrieves their Windows user name and password from the operating system.

(51)

Configuring database connections If these are the same as the user name and password defined by your Windows administrator on the OLAP side, users gain access to their OLAP data, and successfully refresh the document.

Broadcast Agent processes a document containing OLAP Services data providers as follows:

• A Windows user name and password, defined with the Configuration Tool, is used to start BusinessObjects on the Windows server.

• A user schedules a document containing a Microsoft OLAP Services data provider.

• At the scheduled time, Broadcast Agent launches BOManager on the server, using the user name and password that was defined with the Configuration Tool.

• To allow BusinessObjects to retrieve data from the database, OLAP Services checks the Windows user name and password defined on the server machine where BusinessObjects is active.

• If the Windows user name and password on the server machine running BusinessObjects are the same as those defined on the OLAP side,

BusinessObjects gains access to the data, and refreshes the document. If the user account does not have OLAP permission, BusinessObjects cannot refresh the document, and Broadcast Agent returns a failed task.

Repository sizing and Broadcast Agent transactions

Broadcast Agent passes SQL transactions to the security and document domains of the repository.

Transactions between Broadcast Agent and the security domain do not require significant repository resources. However, if you are using Broadcast Agent to publish documents on the repository, verify that the document domain is large enough to store the documents.

You can also control the number of documents in the repository by advising users to switch on the Overwrite mode option when they send documents to Broadcast Agent. As the administrator, you can switch on this option in the Broadcast Agent Console (see Overwrite mode on page 110).

(52)

LDAP

The Business Objects Enterprise suite can use Lightweight Directory Access Protocol (LDAP) to manage the identity of your Business Objects users in a corporate directory. LDAP enables you to store user information for all your enterprise applications on a single corporate directory.

Business Objects users can be stored in LDAP, in the corporate repository, or in both. If your deployment makes use of LDAP, Broadcast Agent publishes to users and distributes to groups stored in LDAP in the same way as it does to users and groups in the Business Objects repository.

The passwords of Broadcast Agent user in the repository must match those of the users in the LDAP directory.

Configuring LDAP

For Broadcast Agent Scheduler to work correctly with LDAP the Store Password in Reporting option must be activated in the Security Configuration Tool. You install this tool with the Administration Products.

NOTE

Broadcast Agent requires a Broadcast Agent user to execute tasks. This user must still be declared and authenticated through the repository. You cannot use an LDAP user to execute tasks.

Users in the LDAP directory, who are not in the repository, must log into the system (for example, into InfoView before any document can be sent to them with the following option enabled: "Refresh with profile of each recipient.

For more information about using LDAP with the Business Objects Enterprise suite, refer to the Installation and Configuration Guide for Windows and the Installation and Configuration Guide for UNIX.

(53)

chapter

(54)

Overview

This chapter explains how to install and configure Broadcast Agent.

Before you begin, make sure you review the deployment requirements outlined in the previous chapter (Deploying Broadcast Agent on page 33).

Installation and configuration of Broadcast Agent involves the following tasks: • Installing Broadcast Agent

• Assigning users to Broadcast Agents • Enabling modules on the servers

• Enabling and deactivating Broadcast Agent components • Setting BOManager parameters

• Starting Broadcast Agent processes on the server • Starting Schedulers to monitor the Broadcast Agents

(55)

Installing Broadcast Agent

Broadcast Agent is a server product. You install Broadcast Agent on your server machine(s) together with other Business Objects server products as shown below:

You must also install:

• the Broadcast Agent Console • Supervisor

• Configuration Tool • Administration Console

(56)

These components are located under the Administration Products

For more information and detailed installation instructions, see the Installation and Configuration guide.

(57)

Creating a Broadcast Agent

Once you have installed Broadcast Agent, you are ready to begin the

configuration process. The first step is to create a named Broadcast Agent for one or more user groups, using Supervisor. You must log in to Supervisor with a General Supervisor or Supervisor profile.

You assign a Broadcast Agent as a property of a group, to which only users who are members of that group or sub-groups have access. A given user can belong to more than one group, and can therefore use more than one Broadcast Agent. To assign a Broadcast Agent to a group of users:

1. In Supervisor, right-click the user group to which you want to assign the Broadcast Agent, then select Properties from the shortcut menu.

The Group Properties dialog box appears. 2. Click the Broadcast Agent tab.

(58)

3. Under User click Broadcast Agent.

4. In the Name box, type the name of the Broadcast Agent. 5. In the Password field, enter a password.

6. Clear the Disable Login check box.

This enables the Broadcast Agent to log in and the Console to monitor tasks. 7. If you want to use only UNIX servers to process tasks sent to this Broadcast

Agent, select the UNIX-Only Broadcast Agent checkbox. 8. Select a document repository domain from the drop-down list. 9. Click OK.

Your Broadcast Agent is now defined, and users can now send documents to it for processing. Before the tasks can be processed, you must also start a Scheduler for the Broadcast Agent (see Starting a Scheduler on page 61). Each named Broadcast Agent services one document domain. In Supervisor, you can define multiple groups that have the same members, and use multiple named Broadcast Agents to service the different document domains.

(59)

Creating a Broadcast Agent

NOTE

You can define multiple named Broadcast Agents without requiring an extra license. You need only one Broadcast Agent license per server in each cluster that runs Broadcast Agent tasks.

Security commands

Security commands in Supervisor must be correctly set to enable a BusinessObjects or WebIntelligence user to access Broadcast Agent functionality. By default, ordinary users do not have permission to access advanced functions such as report bursting or VBA macros, so you need to configure these settings for your users. However, remember that the more users that are given report bursting rights, the more resources may be consumed. See the Supervisor’s Guide (appendix B) for a full description of the available security commands. You access the security commands in the Command Restriction dialog box in Supervisor. The information below gives a summary of the commands that are most relevant for Broadcast Agent users:

Command Setting

Do not refresh with the reference profile of each recipient

Disable, for users to access the Report Bursting feature

Run scripts/VBA code Enable, to allow users to access custom scripts

Use Broadcast Agent Console Enable, to allow users to view and modify scheduled task status via the Console Work with web server Enable, to allow users to use Broadcast

Agent’s Distribute via Web Server function Retrieve documents from

scheduled processing

Enable, to allow users to retrieve documents from Broadcast Agent

(60)

NOTE

For InfoView users, the Schedule Documents command must be set to Enabled in order for users to send documents to Broadcast Agent.

Schedule corporate documents Enable, to allow users to send corporate documents to Broadcast Agent

Send documents for scheduled processing

Enable, to allow users to send documents to Broadcast Agent

Attach scripts to scheduled processing

Enable, to allow users to send documents containing custom VBA macros to Broadcast Agent

(61)

Broadcast Agent Schedulers

You can create, start, or stop the Broadcast Agent Schedulers assigned to the various nodes on the system. You can also view and modify the parameters of each Scheduler.

Starting a Scheduler

You start a Scheduler using the Administration Console.

REMINDER

You must start the server first.

The Administration Console is a Java applet that can be installed on any machine in the same subnet as the Broadcast Agent cluster. You can run it in any Java-enabled web browser, or from the Windows desktop.

NOTE

The Administration Console is not the same as the Broadcast Agent Console, a Windows-based tool that allows you to examine and modify the list of tasks scheduled by a Broadcast Agent.

Accessing the Administration Console

To access the Administration Console, you must have one of the following profiles:

• General Supervisor • Supervisor

• Supervisor-designer

• Versatile user (with Supervisor rights)

The actions that these profiles are permitted within the Administration Console can be restricted by applying certain security commands.

By default, the General Supervisor profile can perform all operations in the Administration Console.

With a General Supervisor profile, you can modify in Supervisor the access rights of a Supervisor, Supervisor-designer, and Versatile User.

(62)

The table below shows the security commands that are relevant for the Administration Console.

For more information on how to set these security commands in Supervisor, refer to the Supervisor’s Guide.

NOTE

If the Log into Administration Console security command is disabled, all other security commands are automatically disabled, and the user will be denied access to the Administration Console.

Security Command What it allows

Log into Administration Console Starting the Administration Console Administrate clusters and

modules

• Stopping and starting clusters and modules (except Broadcast Agent) • Changing cluster language • Changing log file names • Changing module parameters • Enabling/disabling Broadcast Agent

Manager

Administrate user sessions Stopping user sessions Administrate clusters, modules

and Broadcast Agents

• Creating and removing Schedulers • Stopping and starting Schedulers • Modifying Scheduler parameters

(63)

Broadcast Agent Schedulers Starting and monitoring a scheduler

Decide which machine in your cluster will run a Scheduler for the user group. You can also start Schedulers on several different machines, so that if one machine fails, the others will continue processing the tasks as normal (failover). To start a Scheduler:

1. Open the Administration Console.

2. From the list of modules on the left side, select Broadcast Agent Manager.

The panel on the right side shows the Schedulers that are currently running on the machine selected in the left panel. If there are none, the panel is empty. The Schedulers are listed per named Broadcast Agent. If a Broadcast Agent has more than one Scheduler, all of the Schedulers appear in the