crystal enterprise installation guide - sap q&a · crystal training whether you’re a...

Crystal Enterprise™ 10Installation Guide

Crystal Decisions, Inc.895 Emerson St.

Palo AltoCalifornia, USA 94301

Copyright © 2002 Crystal Decisions, Inc., 895 Emerson St., Palo Alto, California, USA 94301. All rights reserved.

Issue 1.

No part of this documentation may be stored in a retrieval system, transmitted or reproduced in any way, except in accordance with the terms of the applicable software license agreement. This documentation contains proprietary information of Crystal Decisions, Inc., and/or its suppliers.

Trademark Acknowledgements© 2003 Crystal Decisions, Inc. All rights reserved. Crystal Decisions, Crystal Reports, Crystal Enterprise, Crystal Analysis, Crystal Services, Crystal Care, Crystal Assist, Crystal Applications, Info and Holos are trademarks or registered trademarks of Crystal Decisions, Inc. in the U.S. and/or other countries. All other trademarks or registered trademarks referenced are the property of their respective owners.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/)

Contents

Chapter 1: Welcome to Crystal EnterpriseWhat is Crystal Enterprise? ............................................................... 2Who should use this guide? ............................................................... 2

About this guide ................................................................................ 2Chapter contents ................................................................................................... 2

Product registration .......................................................................... 3

Customer Handbook ......................................................................... 4

Crystal Care technical support .......................................................... 4

Crystal Training ................................................................................. 4

Crystal Consulting ............................................................................. 5

Document conventions ..................................................................... 5

Chapter 2: Planning Your InstallationInstallation overview ......................................................................... 8System requirements ......................................................................... 8Choosing a database server for the CMS database ................................................. 9Choosing a web server ........................................................................................ 10Choosing an application server ........................................................................... 11Choosing a web development environment ......................................................... 12

Default installation on Windows ..................................................... 14

Default installation on UNIX .......................................................... 14

Deployment scenarios for Crystal Enterprise .................................. 15Full stand-alone installation on Windows ............................................................ 16Full server-side installation on Windows connected to a web server ................... 16Full Java installation on Windows or UNIX ......................................................... 17Pure Java installation on UNIX or Windows ........................................................ 18

Crystal Enterprise Installation Guide iii

Pure ASP solution on Windows ........................................................................... 18Pure ASP.NET solution on Windows ................................................................... 19Expanded installation on Windows or UNIX ....................................................... 19Upgrading an existing installation on Windows or UNIX ..................................... 19Silent installation on Windows or UNIX .............................................................. 20

Optimizing your system for report viewing .................................... 20

Configuring your Crystal Enterprise installation .............................. 23Familiarizing yourself with administration ........................................................... 23Setting up users and groups ................................................................................. 23Creating folders and publishing objects ............................................................... 25Controlling users’ access to objects ..................................................................... 27Advanced administration ..................................................................................... 27

Chapter 3: Installing Crystal Enterprise on WindowsInstallation overview ....................................................................... 30System requirements ....................................................................... 31Setting up the CMS database ............................................................................... 31Providing administrative privileges ...................................................................... 32Meeting network requirements ............................................................................ 33

Installing Crystal products on a non-system drive ........................... 33

Full stand-alone installation ............................................................ 33

Server-side installation connected to a web server ......................... 37

Expanded installation ...................................................................... 43

Client tools installation ................................................................... 46

Custom installation ......................................................................... 47

Silent installation ............................................................................ 51

Java component installation ............................................................ 53Installing the Java SDK ........................................................................................ 54Installing a Java application server ....................................................................... 55

iv Crystal Enterprise Installation Guide

Installing Crystal Enterprise .................................................................................. 55Deploying the Java version of the Crystal Enterprise web desktop ........................ 55Deploying the Web Component Adapter ............................................................. 58

Chapter 4: Installing Crystal Enterprise on UNIXInstallation overview ....................................................................... 66System requirements ....................................................................... 66

Setting up your UNIX system .......................................................... 67Meeting the host name and network requirements .............................................. 67Checking for required commands and utilities ..................................................... 67Setting the locale ................................................................................................. 68Setting up an empty database for the CMS ........................................................... 68Creating an account, a home directory, and a login environment ........................ 69Providing and verifying connectivity to the CMS database ................................... 70Installing the Java SDK ........................................................................................ 74

Running the installation script ........................................................ 75Installing the Crystal Enterprise files ..................................................................... 75Setting up the Crystal Enterprise servers ............................................................... 76Finishing a system installation ............................................................................. 77Running an expand installation ........................................................................... 77Running a silent installation ................................................................................ 78Starting the Crystal Enterprise daemons with ccm.sh ........................................... 78

Installing a Java application server .................................................. 79

Installing the Java application tier components .............................. 80

Deploying the Crystal Enterprise web desktop ................................ 81

Deploying the Web Component Adapter ........................................ 83Changing the default deployment values for the WCA ......................................... 86Deploying custom CSP applications .................................................................... 88Installing multiple Web Component Adapters ..................................................... 88

Installing a Web Connector on a UNIX web server ........................ 89

Crystal Enterprise Installation Guide v

Chapter 5: Configuring Web ConnectorsWhat are Web Connectors? ............................................................ 92Path mapping overview ................................................................... 92Web server virtual directory mappings ................................................................ 93Web server application mappings ....................................................................... 94Web Connector virtual path mappings ................................................................ 94

Installing Web Connectors .............................................................. 95On Windows ....................................................................................................... 95On UNIX ............................................................................................................. 96

Configuring Windows Web Connectors .......................................... 96Connecting Crystal Enterprise to IIS ..................................................................... 96Connecting Crystal Enterprise to Lotus Domino ................................................... 97Connecting Crystal Enterprise to iPlanet .............................................................. 98Connecting Crystal Enterprise to the IBM HTTP Server ........................................ 99Configuring other supported CGI web servers ..................................................... 99Configuring the Web Connector for a remote WCS .......................................... 101

Configuring UNIX Web Connectors .............................................. 104Connecting Crystal Enterprise to Apache ........................................................... 104Connecting Crystal Enterprise to iPlanet ............................................................ 107Configuring other supported CGI web servers ................................................... 111

Troubleshooting path mappings .................................................... 113Web server virtual path mappings ..................................................................... 113Web server application mappings ..................................................................... 114Web Connector virtual path mappings .............................................................. 118

Chapter 6: Upgrading, Migrating, and ImportingUpgrading overview ...................................................................... 126Before upgrading or migrating ...................................................... 127

Upgrading earlier versions of Crystal Enterprise ........................... 127

vi Crystal Enterprise Installation Guide

Migrating system data from earlier versions ................................. 129

Importing content from Crystal Enterprise or Info ........................ 129

Upgrading other Crystal components ........................................... 130Upgrading the Report Application Server .......................................................... 130Upgrading Crystal Reports ................................................................................. 130Upgrading Crystal Analysis ................................................................................ 130

Chapter 7: Custom SDK DeploymentsSoftware Development Kit overview ............................................. 132Crystal Server Pages environment ................................................. 132

Active Server Pages environment .................................................. 133

Java Server Pages environment ..................................................... 133

.NET environment ......................................................................... 133

Chapter 8: UninstallingUninstalling Crystal Enterprise from Windows ............................. 136Uninstalling MSDE ............................................................................................ 136

Uninstalling Crystal Enterprise from UNIX ................................... 137

Index .............................................................................. 139

Crystal Enterprise Installation Guide vii

viii Crystal Enterprise Installation Guide

Welcome to Crystal Enterprise 1

This chapter briefly describes Crystal Enterprise andoutlines the contents and the intended audience of thisguide. Product registration and technical supportinformation is also included, along with a brief descriptionof the document conventions used within this guide.

Crystal Enterprise Installation Guide 1

What is Crystal Enterprise?

What is Crystal Enterprise?Crystal Enterprise is a flexible, scalable, and reliable solution for delivering powerful, interactive reports to end users via any web application—intranet, extranet, Internet or corporate portal. Whether it is used for distributing weekly sales reports, providing customers with personalized service offerings, or integrating critical information into corporate portals, Crystal Enterprise delivers tangible benefits that extend across and beyond the organization. As an integrated suite for reporting, analysis, and information delivery, Crystal Enterprise provides a solution for increasing end-user productivity and reducing administrative efforts.

Who should use this guide?This guide is intended for the system administrator or IT professional who needs to install Crystal Enterprise. Familiarity with your overall network environment, port usage, your database environment, and your web server software is especially beneficial. If you are installing Crystal Enterprise on UNIX, you will require root privileges to perform some of the setup procedures.

For more information about the product, consult the Crystal Enterprise Administrator’s Guide, the Crystal Enterprise Getting Started Guide, and the Crystal Enterprise User’s Guide. Online versions of these guides are included in the doc directory of your product distribution. Once you install Crystal Enterprise, they are also accessible from the Crystal Enterprise Launchpad.

About this guideThis guide provides you with information and procedures for installing Crystal Enterprise. This guide also includes detailed instructions for the different installation modes available.

Chapter contentsThe following list provides a short description of each of the remaining chapters in this guide.

Chapter 2: Planning Your InstallationThis chapter discusses the various Windows and UNIX installation scenarios supported by Crystal Enterprise, to help you plan your Crystal Enterprise deployment.

Chapter 3: Installing Crystal Enterprise on WindowsThis chapter shows how to install Crystal Enterprise on Windows. General system requirements are provided, as well as procedures covering various installation scenarios.

2 Crystal Enterprise Installation Guide

1: Welcome to Crystal Enterprise

Chapter 4: Installing Crystal Enterprise on UNIXThis chapter shows how to install Crystal Enterprise on UNIX. General system requirements are provided, as well as procedures covering various installation scenarios.

Chapter 5: Configuring Web ConnectorsWeb Connectors convert requests from your web server into a format that the Web Component Server can understand. This chapter focuses on configuring Web Connectors to work in conjunction with your web server software.

Chapter 6: Upgrading, Migrating, and ImportingThis chapter shows how to upgrade Crystal Enterprise, migrate system data, and import content from earlier releases of Crystal Enterprise and Info.

Chapter 7: Custom SDK DeploymentsThis chapter details the various SDKs that are included with Crystal Enterprise. It also provides deployment guidelines for different SDK environments.

Chapter 8: UninstallingThis chapter tells you how to uninstall Crystal Enterprise.

Product registrationThere are several ways you can register your product:• Fill out the Product Registration form on the Crystal Decisions, Inc. web site at:

http://www.crystaldecisions.com/register/

• Print the Product Registration form and fax it to the registration fax number closest to you. Crystal Decisions will then fax you a registration number that can be entered into the product the next time you use it.Registration fax numbersUSA/Canada +1 (604) 681-5147United Kingdom +44 (0) 20 8231 0601Australia +6 2 9955 7682Germany +49 (0) 69 9509 6182Hong Kong +852 2893 2727Singapore +65 777 8786

Registering the product ensures that you are kept up-to-date with product advancements.


Customer Handbook

Customer HandbookFor the latest details about product registration, maintenance, support, and services, visit our web site and download the Customer Handbook that corresponds to your region:• North America:

http://www.crystaldecisions.com/about/loyalty/handbook.asp (English)• Europe:

http://www.crystaldecisions.com/about/loyalty/handbook.asp (English)http://germany.crystaldecisions.com/about/loyalty/handbook.asp (German)http://france.crystaldecisions.com/about/loyalty/handbook.asp (French)

If a Crystal Decisions Customer Handbook is not available for your region, please refer to the rest of this Welcome chapter, or contact your sales or support representative for complete details

Crystal Care technical supportFor information on accessing your Crystal Care support specialists, contact the technical support administrative team, your sales representative, or the regional office nearest you. Contact details are available at:

http://www.crystaldecisions.com/contact/offices.asp

To find out about the technical support programs available for Crystal Enterprise:• Go to our support web site at:

http://support.crystaldecisions.com/crystalcare/

• Contact your regional office. For details, go to:http://www.crystaldecisions.com/contact/offices.asp

Crystal TrainingWhether you’re a developer, information technology professional, or business user, we offer a wide range of Crystal Enterprise training courses designed to build or enhance your existing skills. Courses are available online, at certified training centers, or at your own site:• For a complete list of training courses and special offers, visit:

http://www.crystaldecisions.com/training/

• Or contact your regional office. For details, go to:http://www.crystaldecisions.com/offices/


1: Welcome to Crystal Enterprise

Crystal ConsultingOur global team of certified consultants and consulting partners can guide you through a corporate-wide solution—including strategy, design, integration and deployment—for the fastest results, maximum performance, and increased productivity.• To learn more, visit:

http://www.crystaldecisions.com/consulting/

• Or contact your regional office. For details, go to:http://www.crystaldecisions.com/offices/

Document conventionsThis guide uses the following conventions:• Commands and buttons

For easy recognition within procedures, User Interface (UI) features appear in bold type. For example: On the File menu, click New.

• Keyboard shortcutsDelete means the Delete key, or the Del key on your numeric keypad. Enter means the Enter, Return, or CR key, depending on which of these keys appears on your keyboard.

• Key combinationsCTRL+KEY, SHIFT+KEY, and ALT+KEY are examples of key combinations. Hold down the first key in the combination and, at the same time, press the second key in the combination (designated above as KEY). For example: CTRL+C means hold the Control key down and press the letter C on your keyboard (CTRL+C is the Windows Copy command).

• Key terms are italicized when first defined.• Monospaced font indicates data that you enter using your keyboard. For

example: In the Formula Editor, type If Sales > 1000 Then crRed• Monospaced, italicized font indicates variable data that you must replace with

data appropriate to your current settings, environment, or task. For example, in the following URL, you would replace webserver:http://webserver/crystal/enterprise/


Document conventions


Planning Your Installation 2

This chapter discusses the various Windows and UNIXinstallation scenarios supported by Crystal Enterprise, tohelp you plan your Crystal Enterprise deployment.


Installation overview

Installation overviewCrystal Enterprise provides an open and flexible architecture that supports a multitude of deployment and configuration scenarios. Before you install Crystal Enterprise, consider how you want to integrate its components with your current database and web environments.

System requirementsGenerally, the following components must be installed and configured correctly before you install Crystal Enterprise:• Database software that is compatible with the Crystal Management Server (CMS)

On Windows, if you do not have a database engine installed on your machine, by default the Crystal Enterprise setup program installs the Microsoft Data Engine (MSDE). You can use the MSDE for your CMS database if you don’t want to use an existing database server.

• Web server software• J2EE web application server software (for Java environments)• Web browsers (on web desktop clients’ machines)

For a detailed list of tested environments, consult the platforms.txt file included with your product distribution. This file includes specific version, Service Pack, and patch requirements for web servers, web application servers, web browsers, databases, and operating systems.

In addition, the following requirements ensure that all Crystal Enterprise machines can communicate properly with one another:• Each Crystal Enterprise machine must be able to communicate over TCP/IP

with the machine that runs your CMS.• UNIX servers that run Crystal Enterprise must have a fixed host name. You must

have root privileges to set or modify this information on your system. If you are unfamiliar with these procedures, consult your UNIX system documentation.

• Ensure that your database client and server are set up to use Unicode character encoding (such as UTF-8). Consult your database documentation to determine the settings required for a Unicode configuration. For database clients, you must set certain parameters. The DB2 client, for example, must use the DB2CODEPAGE value of 1208. The Sybase database client typically requires the parameter LC_ALL and an appropriate entry in the locale.dat file.For database servers such as Oracle and Sybase, during installation you need to configure the server to use Unicode encoding for the character data types. For other databases, such as DB2 and Informix, you can create the CMS database with Unicode settings on your existing database server.


2: Planning Your Installation

• If you connect Crystal Enterprise to a web server:• The web server must be able to communicate with the machine that runs

your Web Component Server (WCS).This communication is enabled by the Web Connector, which you must install on your web server machine.

• All web desktop clients must be able to access the web server where you install the Web Connector.

• If you connect Crystal Enterprise to a Java web application server:• the Java web application server must be able to communicate with all

Crystal Enterprise machines.• This communication is enabled by the Crystal Enterprise Java SDK, which

you must install and configure on your web application server.Note: If you are installing Crystal Enterprise in a firewall environment, you will need additional configuration details. See the “Working with Firewalls” section of the Crystal Enterprise Administrator’s Guide.

When planning your Crystal Enterprise installation, you should also consider where you will place servers:• Your Report Job Server, Page Server, and Report Application Server communicate

frequently with the database servers containing the data in your published reports. To speed data retrieval and minimize network traffic, place your processing servers close to your database servers (ideally, on the same subnet). If your Crystal Enterprise installation is distributed over a wide geographic region, use server groups to create groups of nearby servers to process reports.

• The Crystal Management Server (CMS) stores data about users and groups, security levels, published objects, and servers in its system database. The CMS also maintains the Crystal Repository and a separate audit database of information about user actions. To optimize CMS performance, place your CMS on the same LAN as the database servers that host your CMS system database and the Crystal Enterprise audit database.

Choosing a database server for the CMS databaseCrystal Enterprise requires a database (or Oracle tablespace) to store information about the system and its users. This system data is maintained by the Crystal Management Server (CMS); thus, the database is known as the CMS database. [In earlier releases of Crystal Enterprise, the Crystal Management Server was called the Automated Process Scheduler (APS), and the system database was called the APS database.]

The CMS supports a number of third-party database servers, so you can connect Crystal Enterprise to your existing database infrastructure. For a detailed list of tested database servers, see the platforms.txt file included with your product distribution.


System requirements

Before you install and connect the CMS to your own database server, you or your database administrator must create a new, empty database on your database server. We recommend that you name the new database CEcms, create a new user account named crystal, and assign it a secure password. Ensure that the new account has permission to create, modify, and delete tables so that Crystal Enterprise can modify the CEcms database as required. You need the name of the database, the user account, and the password when you install Crystal Enterprise.

Note: • Consult your database server documentation and/or your database

administrator if you are unsure of the procedure for creating a new database.• You can migrate your initial CMS database to another supported database

server later. For details, see the Crystal Enterprise Administrator’s Guide.

Using the Microsoft Data Engine (MSDE)On Windows, if you do not have a database engine installed on your machine, by default the Crystal Enterprise setup program installs the Microsoft Data Engine (MSDE). You can use the MSDE for your CMS database if you don’t want to use an existing database server.

The MSDE is a client/server data engine that provides local data storage and is compatible with Microsoft SQL Server. If you already have the MSDE or SQL Server installed, the installation program creates the CMS database using your existing database engine.

Tip: For large scale deployments of Crystal Enterprise, use one of the supported database servers listed in the platforms.txt file included with your product distribution. The MSDE is not a scalable database solution.

Perform a custom installation of Crystal Enterprise if you do not want to install the MSDE. See “To install a full standalone Crystal Enterprise without the MSDE” on page 48 for details.

Choosing a web serverBefore selecting a web server to use with Crystal Enterprise, assess your current environment and determine the platform on which to deploy Crystal Enterprise. Determine whether you plan to develop custom applications and, if so, which web development environment to use.

Depending upon your needs, you can use one of these options:• Microsoft Internet Information Server (IIS)

If you plan to develop custom applications using ASP or ASP.NET, you should use IIS. In COM systems, a Web Connector must be installed on your web server to facilitate communications between browser-based clients and the Windows-based Web Component Server. In .NET systems, IIS communicates with the



Primary Interop Assemblies that allow you to use the Crystal Enterprise COM SDK with .NET applications.

• Other supported web servers (on Windows or UNIX)If you install Crystal Enterprise on Windows and plan to develop custom applications using Crystal Server Pages (CSP), you can use any of the supported UNIX or Windows web servers listed in the Platforms.txt file that is included with your product distribution. A Web Connector must be installed on your web server to enable communications between browser-based clients and the Windows-based Web Component Server.If you install Crystal Enterprise on Windows or UNIX and use the Crystal Enterprise Java SDK to develop custom applications, you can use any of the supported UNIX or Windows web servers listed in the Platforms.txt file that is included with your product distribution.

• No web server (on Windows or UNIX)If you install Crystal Enterprise on Windows or UNIX and use the Crystal Enterprise Java SDK to develop custom applications, you can also choose to not use a web server; web server connectivity is handled by your Java application server.

Note: We recommend that you use ASP, ASP.NET, or JSP for new custom applications, although development of new custom applications in CSP is still supported in Crystal Enterprise 10. For details, see “Crystal technology directions” on page 15.

Related topics• “Deployment scenarios for Crystal Enterprise” on page 17• “Choosing a web development environment” on page 14

Choosing an application serverCrystal Enterprise requires an application server to process the server-side scripts that make up web applications. Before choosing an application server, assess your current web environment and determine whether you want to deploy the default Crystal Enterprise web applications (the Crystal Enterprise web desktop and the Crystal Management Console), develop custom web applications, or both.

Depending on your needs, you can install Crystal Enterprise in one of two ways:• On Windows, install Crystal Enterprise with its own application server: the

Web Component Server (WCS). • On Windows or UNIX, install and configure the Java Web Component Adapter

and the Crystal Enterprise Java SDKs on a supported, third-party J2EE web application server.

Web Component ServerThe Web Component Server (WCS) is an application server that provides two main services: an engine for processing CSP script, and an application engine for


System requirements

WCS extensions. The WCS supports web applications composed of Crystal Server Pages (CSP) such as the CSP version of the Crystal Enterprise web desktop. The WCS also supports WCS extensions, which include Crystal only services such as the CMC, Crystal report viewers (via viewrpt.cwr based url requests), and Crystal Analysis Professional (CA Pro) via infoobject.cwr based url requests.

In Crystal Enterprise 10 on UNIX the WCS has been deprecated. The WCS will also be deprecated in a future release of Crystal Enterprise on Windows. However, before the WCS becomes obsolete, all applications using the WCS will be migrated to use standard application servers. To allow time for customers and Crystal applications to be migrated, WCS services will be provided by the Web Component Adapter. Crystal Enterprise 10 includes a Java Web Component Adapter. A Web Component Adapter for ASP.NET will be provided in a future release of Crystal Enterprise.

Java Web Component AdapterOn Windows and UNIX, Crystal Enterprise provides a Java web application—the Java Web Component Adapter —that allows your J2EE web application server to run CSP applications, to process .cwr requests, and to host the Crystal Management Console. The Web Connector that resided on the web server in earlier versions of Crystal Enterprise is no longer required. Requests are handled by the application server, and are passed on to the Web Component Adapter. This Java solution essentially replaces the Web Component Server (WCS) in J2EE environments.

The Java Web Component Adapter must be installed on a J2EE web application server. Crystal Enterprise supports a number of third-party application servers, so you can connect Crystal Enterprise to your existing infrastructure. For a detailed list of tested application servers, see the platforms.txt file included with your product distribution.

Choosing a web development environmentCrystal Enterprise supports Crystal Server Pages (CSP), Active Server Pages (ASP), and Java Server Pages (JSP). Crystal Enterprise includes web applications developed in CSP and JSP, such as the Crystal Enterprise web desktop, the Crystal Management Console, and the sample applications that are available through the Crystal Enterprise Launchpad. It also supports the development of custom web applications that use CSP, ASP, JSP, and ASP.NET.

Crystal Server Pages provide functionality similar to Microsoft’s Active Server Pages (ASP). However, unlike ASP, CSP pages will work on both Windows and UNIX platforms. Java Server Pages allow you to develop cross-platform J2EE applications that use Crystal objects in conjunction with your own custom objects, or a wide variety of objects from third parties.

Crystal Enterprise also includes Primary Interop Assemblies (PIAs) that enable you to use the Crystal Enterprise SDK and Report Application Server SDK with ASP.NET. It also includes a set of .NET Server Components which simplify development of custom Crystal Enterprise applications in ASP.NET.



See the developer documentation included with your product distribution for more information

Your choice of which web development environment to use to develop your own custom applications will depend largely on your own technology preferences. However, in making this decision, consider the technology directions foreseen by Crystal Decisions, Inc.

Crystal technology directionsIn the period since CSP was developed, the J2EE platform has come to dominate the cross-platform application server market. Also, Microsoft has released ASP.NET, which supersedes the ASP language and provides modern application server features.

As a result, Crystal Decisions, Inc. is moving away from our proprietary CSP language and is instead developing tools and applications in ASP.NET and J2EE. In support of that goal, CSP is deprecated on UNIX platforms in Crystal Enterprise 10. CSP will be deprecated on the Windows platform in a future release of Crystal Enterprise.

What does deprecating CSP on a platform mean?• Existing CSP applications will continue to run on that platform (after making

minor configuration changes).• New Crystal Enterprise features will not be made available in CSP.• You should not develop new custom applications in CSP on a platform where

CSP has been deprecated.• You should plan to port existing CSP applications to J2EE or ASP.NET.

Choosing an environment for new custom applicationsWhile it will be possible to run CSP applications after CSP has been deprecated on a platform, you should not develop new custom CSP applications on that platform. Here are some directions to consider:• Windows platform, IIS web server

Consider developing new applications using ASP.NET. (You could also develop new applications in ASP; however, Microsoft is gradually deprecating ASP.)

• Windows platform, any supported web serverYou may want to consider developing new applications using J2EE.

• UNIX platform, any supported web serverYou should build new applications using J2EE. You should port existing applications to J2EE since CSP on UNIX has been deprecated in Crystal Enterprise.

If you have an existing custom application that is a slightly modified version of the Crystal Enterprise web desktop (or another application supplied by Crystal), you may wish to apply your changes to an updated version of the application. A J2EE version of the Crystal Enterprise web desktop is available in Crystal Enterprise 10. An ASP.NET version will be available before CSP is deprecated on Windows.


Default installation on Windows

Default installation on WindowsWhen you install Crystal Enterprise on Windows, by default you install the version of Crystal Enterprise that uses the Crystal Enterprise COM SDK. As in previous versions of Crystal Enterprise, the default installation uses the Web Component Server as an application server to support CSP files, and requires the use of a Web Connector to allow Crystal Enterprise servers to communicate with your web server.

You may also choose to install the Java version of Crystal Enterprise, which uses the Java Crystal Enterprise SDK, a Java version of the Crystal Enterprise web desktop, and the Web Component Adapter (to support legacy CSP applications). See “Full Java installation on Windows or UNIX” on page 19 for more information.

For complete installation procedures, consult “Installing Crystal Enterprise on Windows” on page 29.

Default installation on UNIXCrystal Enterprise allows you to run all server components on a UNIX server. Users connect to Crystal Enterprise over the Web with Internet Explorer or Netscape Navigator. Once you’ve finished the installation and setup procedures, the various server components run as daemons. Then you must deploy the Crystal Enterprise web desktop, the Crystal Enterprise Launchpads, and the Web Component Adapter as web applications on your application server.

If you perform a system install, a user with root privileges can enable automated startup by running a script that copies run control scripts in the relevant directories. The script is run after the installation and setup scripts complete.

Consult the appropriate sections of the Crystal Enterprise Installation Guide (install.pdf), before you run the interactive installation shell script (install.sh). The installation guide provides full information on preparing for an installation, as well as procedures describing how to set up, install, and configure Crystal Enterprise.

Note: If you install the Crystal Enterprise server components on a UNIX machine, you can connect remotely to Crystal Enterprise with the Crystal Publishing Wizard and the Crystal Import Wizard. However, these client applications must be installed on Windows.

Crystal Enterprise on UNIX uses the Java Crystal Enterprise SDK, a Java version of the Crystal Enterprise web desktop, and the Web Component Adapter (to support legacy CSP applications, and the Crystal Management Console). The use of a web server is optional; you can choose to serve all of your web content on your application server.

For complete installation procedures, consult “Installing Crystal Enterprise on UNIX” on page 65.



Deployment scenarios for Crystal EnterpriseThis chapter includes a number of installation scenarios that describe how you can deploy Crystal Enterprise in different configurations on various platforms. These scenarios were selected to help you understand how to install Crystal Enterprise in a way that best meets the needs of your organization.

Consult your Crystal Enterprise Administrator’s Guide for information on other factors that you may want to consider in planning your Crystal Enterprise installation: • See “Working with firewalls” for information on how to configure Crystal

Enterprise to work with your secured network.• See “Creating accessible reports” for information on how to create and

distribute reports that meet the needs of people with disabilities.• See “Global deployments” for information on how to deploy Crystal

Enterprise for a multilingual, worldwide audience.

Of the scenarios described here, the full stand-alone installation on Windows is generally the quickest to perform, and it provides you with all the functionality you will require to proceed through the Crystal Enterprise Administrator’s Guide if you wish to familiarize yourself with the features and functionality of Crystal EnterpriseThe UNIX installation is also highly automated, but it is recommended that you attempt this installation only if you have some experience deploying software on an enterprise-wide level on your UNIX system.

Note: On Windows, you can choose to install all Crystal Enterprise components on a drive other than the drive that contains your operating system files. For details, see “Installing Crystal products on a non-system drive” on page 33.

Scenarios:• “Full stand-alone installation on Windows” on page 18.)• “Full server-side installation on Windows connected to a web server” on

page 18.• “Full Java installation on Windows or UNIX” on page 19.• “Pure Java installation on UNIX or Windows” on page 20.• “Pure ASP solution on Windows” on page 20.• “Pure ASP.NET solution on Windows” on page 21.• “Expanded installation on Windows or UNIX” on page 21.• “Upgrading an existing installation on Windows or UNIX” on page 21.• “Silent installation on Windows or UNIX” on page 22.

For complete installation procedures, consult“Installing Crystal Enterprise on UNIX” on page 65 and “Installing Crystal Enterprise on Windows” on page 29.


Deployment scenarios for Crystal Enterprise

Full stand-alone installation on WindowsIn this scenario, you install Crystal Enterprise on a single machine that is already running as a web server. This is the quickest way to install Crystal Enterprise.

This installation scenario offers the quickest way to install Crystal Enterprise. After you have set up your web server software, run the New installation from the Crystal Enterprise Setup program.

On Windows, this is the default installation. For more details, see “Default installation on Windows” on page 16.

When you select this option, all Crystal Enterprise components are deployed on the local machine (including the Crystal Enterprise web desktop and the Crystal Management Console), and your system provides support for CSP scripting. The Crystal Management Server (CMS) automatically creates its own database. The Web Connector is automatically configured to allow communication between Crystal Enterprise and the web server software that you have already installed. The installation program creates default accounts for users and groups, and publishes sample reports to the system. When the installation is complete, the server components are started as services on the local machine.

Note: For explicit procedural details covering this installation scenario, consult “Full stand-alone installation” on page 33.

Full server-side installation on Windows connected to a web serverIn this scenario, you run Crystal Enterprise and your web server on separate machines. After you’ve installed Crystal Enterprise on one machine, you install and configure the Web Connector on the web server machine.

Installing Crystal Enterprise on a server that is connected to a web server is a quick way to integrate Crystal Enterprise with your existing web server—without installing the core Crystal Enterprise components on the web server itself. This scenario is ideal if you have a single UNIX server that runs as your dedicated web server. You retain the use of your UNIX web server, and you can still install Crystal Enterprise on Windows.

In this scenario, all Crystal Enterprise components are deployed (including the Crystal Enterprise web desktop and the Crystal Management Console), and your system provides support for CSP scripting.

To install, run the New installation from the Crystal Enterprise Setup program on the machine where you want to install Crystal Enterprise components. Then install and configure the appropriate Web Connector on your web server machine.• If your web server runs on Windows, select the Web Connector by running the

Custom installation from the Crystal Enterprise Setup program.



• If your web server runs on UNIX, you must run the Web Connector installation (by running the appropriate install.sh script) on that machine and perform additional configuration. For details, see the Crystal Enterprise Installation Guide (install.pdf).

The installation program installs client and server components on the Crystal Enterprise machine, creates default Crystal Enterprise user and group accounts, and publishes sample reports to the system. When the installation is complete, the server components are started as services on the Crystal Enterprise machine.

Note: For explicit procedural details covering this installation scenario, consult “Server-side installation connected to a web server” on page 37.

Full Java installation on Windows or UNIXIn this scenario, you install Crystal Enterprise on a machine that is running a Java application server. This allows you to deploy pure JSP solutions and the Java version of the Crystal Enterprise web desktop, while still supporting legacy CSP applications and the Crystal Management Console through the Web Component Adapter. The use of a web server is optional; you can choose to use your application server to serve all of your web content.

All Crystal Enterprise components are deployed (including the Java version of the Crystal Enterprise web desktop), and your system provides support for JSP scripting. Support for the Crystal Management Console and legacy CSP applications is provided by the Web Component Adapter.

On UNIX, this is the default installation. See “Default installation on UNIX” on page 16 for more details.

To install, set up your Java application server, and then install Crystal Enterprise. On UNIX run the installation script. On Windows, run the Custom installation from the Crystal Enterprise Setup program and install all components except the Web Component Server and the Web Connectors (which are not needed).

When you perform the Crystal Enterprise installation, all of the client and server components are installed on the local machine. The installation program creates default accounts for users and groups, and publishes sample reports to the system. When the installation is complete, the server components are started as services on the local machine. Then you must deploy the Crystal Enterprise web desktop, the Crystal Enterprise Launchpads, and the Web Component Adapter as web applications on your application server.

Note: For explicit procedural details covering this installation scenario, consult “Java component installation” on page 53, or “Installing Crystal Enterprise on UNIX” on page 65.


Deployment scenarios for Crystal Enterprise

Pure Java installation on UNIX or WindowsIn this scenario, you install and configure Crystal Enterprise servers and the Crystal Enterprise Java SDK on the machine that is running your Java application server, but do not deploy the Web Component Adapter. You can also install the Java version of the Crystal Enterprise web desktop for use as a client application.

This allows you to deploy pure JSP solutions and the Java version of the Crystal Enterprise web desktop. CSP scripting and the Crystal Management Console are not supported. You must use the DHTML viewer, or the Advanced DHTML viewer. The use of a web server is optional; you can choose to use your application server to serve all of your web content.

To install, set up your Java application server, and then install Crystal Enterprise. On UNIX run the installation script. On Windows, run the Custom installation from the Crystal Enterprise Setup program and install all components except the Web Component Server, the Web Connectors, and the Crystal Enterprise COM SDK (on Windows only).Then you must deploy the Crystal Enterprise web desktop and the Crystal Enterprise User Launchpad as a web application on your application server. Do not deploy the Crystal Enterprise Admin Launchpad, or the Web Component Adapter.

When you perform a Crystal Enterprise installation, all of the client and server components are installed on the local machine. The installation program creates default accounts for users and groups, and publishes sample reports to the system. When the installation is complete, the server components are started as services on the local machine.

Note: For explicit procedural details covering this installation scenario, consult “Custom installation” on page 47 and “Java component installation” on page 53 for Windows. For UNIX, see “Installing Crystal Enterprise on UNIX” on page 65.

Pure ASP solution on WindowsIf you want a pure ASP solution in a Windows environment, install the Crystal Enterprise COM SDK on your Microsoft IIS web server. Deploy the other Crystal Enterprise components on another machine. This scenario is ideal if you plan to develop and deploy custom ASP applications.

To install, run the New installation from the Crystal Enterprise Setup program on the machine where you want to install Crystal Enterprise components. Then run a Custom installation on the machine running your IIS server and install the Crystal Enterprise COM SDK (listed under Developer Components in the Select Features dialog box).

Note: For explicit procedural details covering this installation scenario, consult “Custom installation” on page 47.



Pure ASP.NET solution on WindowsIf you want a pure.NET solution in a Windows environment, install the Crystal Enterprise COM SDK and the .NET assemblies on a Microsoft IIS web server that is already configured for use as a .NET server. This installation will also install the .NET Server Components, which you can use to simplify the development of custom applications. Deploy the other Crystal Enterprise components on another machine.

This scenario is ideal if you plan to develop and deploy your own custom ASP.NET applications.

To perform this installation, you must first install Visual Studio .NET or the .NET Framework on a machine that is running IIS (version 5 or higher). Then run the Custom installation from the Crystal Enterprise Setup program and install the Crystal Enterprise .NET SDK (listed under Developer Components in the Select Features dialog box).

Note: For more information about this scenario, see “.NET environment” on page 133. For explicit procedural details, consult “Custom installation” on page 47.

Expanded installation on Windows or UNIXIn large or mission-critical deployments of Crystal Enterprise you can scale your system to handle increased usage or to add fault-tolerance. Adding additional servers is called scaling horizontally, while adding additional processors to a machine is called scaling vertically. In a horizontally-scaled system, Crystal Enterprise components are installed on multiple machines. In a vertically-scaled system, multiple Crystal Enterprise server components can run on the same machine. Note that a single server, vertically-scaled system improves Crystal Enterprise’s ability to handle increased usage, but does not increase the fault tolerance of the system.

Consult the Scaling Your System section of the Crystal Enterprise Administrator’s Guide for information on planning how to best expand your installation to meet the needs of your organization. See “Installing Crystal Enterprise on Windows” on page 29 or “Installing Crystal Enterprise on UNIX” on page 65 for instructions on performing an expanded installation.

Upgrading an existing installation on Windows or UNIXIf you have an existing installation of Crystal Enterprise on Windows or UNIX, you can upgrade your system to Crystal Enterprise 10, migrate your system data to the new version, and import content from an earlier version of Crystal Enterprise or Info: • Upgrading consists of replacing existing Crystal Enterprise programs and files

with the latest versions.• Migrating consists of copying data from your old Automated Process Scheduler

(APS) database to a new Crystal Management Server (CMS) database, while at the same time updating the database schema to the latest version.


Optimizing your system for report viewing

• Importing consists of copying selected objects (reports, users, groups, and so on) and instances from one system to another.

Before beginning an upgrade, read “Upgrading, Migrating, and Importing” on page 125.

If you require further assistance in upgrading, particularly large-scale and/or mission-critical deployments, or in migrating customized reporting applications, it is recommended that you contact a Crystal Services consultant, who can then assess your reporting environment and assist in the planning or execution of the upgrade or migration.

Silent installation on Windows or UNIXIf you need to perform multiple installations and do not want to interrupt people who are currently working on machines in your system or if you want to install Crystal Enterprise with your own script, you can use the silent installation command for Crystal Enterprise. A silent installation is one that you run from the command line to automatically install Crystal Enterprise on any machine in your system, without prompting for information during the installation.

The silent installation is not recommended for custom installations. The installation options are simplified and do not allow for the same level of customization that is provided in the Crystal Enterprise Setup program (on Windows), or the install script (on UNIX). Silent installations are also not recommended for upgrades.

For more information on performing a silent installation on Windows, see “Silent installation” on page 51. For more information on performing a silent installation on UNIX, see “Running a silent installation” on page 78.

Optimizing your system for report viewingOnce Crystal Enterprise is configured and operational at your site, you should consider how to optimize Crystal Enterprise to meet your organization’s requirements for report viewing. The options that you choose allow you to balance users’ need for up-to-date information with the need to optimize data retrieval times and overall system performance.

Here are some issues that you should consider:• Using live or saved data

On-demand reporting gives users real-time access to live data, straight from the database server. Before providing live data for all your reports, however, consider whether or not you want all of your users hitting the database server on a continual basis. If the data isn’t rapidly or constantly changing, then all those requests to the database do little more than increase network traffic and consume server resources. In such cases, you may prefer to schedule reports on



a recurrent basis so that users can always view recent data (report instances) without hitting the database server. For more information on live and saved data and other issues around optimizing reports for viewing on the web, see the “Designing Optimized Web Reports” section in the Crystal Reports User’s Guide (version 8.5 and later).

• Setting report viewing optionsCrystal Enterprise allows you to enable data sharing, which permits different users accessing the same report object to use the same data when viewing a report on demand or when refreshing a report. Enabling data sharing reduces the number of database calls, thereby reducing the time needed to provide report pages to subsequent users of the same report while greatly improving overall system performance under load. However, to get full value from data sharing, you must permit data to be reused for some period of time. This means that some users may see “old” data when they view a report on demand, or refresh a report instance that they are viewing. You will usually want to enable data sharing, with an interval selected to meet your requirements for data freshness. For more information, see the section on setting report viewing options in the Crystal Enterprise Administrator’s Guide.

• Setting options per-server or per-report You can control data sharing settings on either a per-report or a per-server basis. If you specify which servers a report uses for viewing, you can use per-server settings to standardize data sharing settings for groups of reports, and centrally administer these settings. Per-report settings permit you to specify that particular reports will not share data (for example, because the report uses a User Function Library (UFL) that is personalized for each user). They also allow you to tailor the data sharing interval for each report to meet the needs of that report’s users. In addition, per-report settings enable you to decide on a report-by-report basis whether it is appropriate to allow users to access the database whenever they refresh reports. You will usually want to set report viewing options on a per-report basis, as your requirements for data freshness are usually different for every report.

• Designing reports to maximize data sharingData can be shared between users of a report object only if certain conditions are met. Try to maximize data sharing by designing reports such that the conditions for data sharing are met as often as possible, without compromising different user’s need for report information.When reports are processed by the Page Server, data is shared between users of a report when:• Users view a report using the same database logon information.• Users view a report using the same parameters.• Users view a report using the same page layout options.• Users view a report using the same locale settings.


Optimizing your system for report viewing

Reports viewed using the DHTML viewer, the Active X viewer, or the Java viewer are processed using the Page Server. These viewers do not allow users to change the page layout or locale of a report. However, it is possible to develop custom viewer applications that provide this functionality.When reports are processed by the Report Application Server, data is shared between users of a report when:• Users view a report using the same database logon information.• Users view a report using the same parameters.• Users view a report using the same locale settings.• Users do not modify the report.Reports viewed using the Advanced DHTML viewer (or your own custom application that permits report viewing and modification) are processed using the Report Application Server.

• Designing reports with parametersIf two users view the same report using different parameters, report data cannot be shared between the clients. To maximize data sharing, and therefore system performance, carefully consider how you use parameters:• Add parameters to a report only when the parameters are really needed.

The more parameters a report has, the less likely it is that report data can be shared between users.

• Where possible, use pick lists to ensure that different users make the same request when they want the same data. For example, users may want to use a report to find all customers who have made orders over a certain dollar amount. If you add a parameter field that allows users to type any amount, most database calls made by the report will be unique and data sharing between users will rarely be possible. However, if you add a parameter pick list containing commonly used dollar ranges (say, $0 to $50,000; $50,000 to $100, 000; and more than $100,000), many database calls made by the report will be the same, and Crystal Enterprise can use data sharing to conserve system resources.

• Choosing a report viewerReports viewed using the Advanced DHTML viewer are processed by the Report Application Server (RAS). Because the primary purpose of RAS is to enable users to modify reports online, report refreshes from the Advanced DHTML viewer always access the database. You may want to disallow the use of the Advanced DHTML viewer if your site does not implement report modification. (In the Crystal Management Console, go to the Crystal Applications area and select Crystal Enterprise Web Desktop.)When viewing reports that display aggregate data (such as charts) on the first page, the client-side Java and ActiveX viewers perform better than the DHTML viewers. The client-side viewers display information as it becomes available, rather than waiting until all data has been processed before beginning to draw the page.



Configuring your Crystal Enterprise installationOnce you have installed Crystal Enterprise, you must configure your system for use in your organization. The first step is to understand both your users and your content. Before you start, you must determine what content you will make available in Crystal Enterprise, which users will access your system, and what level of access each category of user needs to have for that content. Your next steps are to set up system security, create users and groups, publish your content to the system, set up folders to organize your objects, and set access rights.

Completing these steps will complete the basic configuration of Crystal Enterprise. However Crystal Enterprise is a flexible and powerful tool that allows you to do much more than publish and distribute simple reports. Consult your Crystal Enterprise Administrator’s Guide for information on the types of objects that you can publish, how to manage and schedule reports and other objects, how to create and manage events, how to audit user and system actions, and much more.

Familiarizing yourself with administrationMost Crystal Enterprise system administration is done using the Crystal Management Console (accessible from the Crystal Enterprise Admin Launchpad), or the Crystal Configuration Manager. Log on to the Crystal Management Console with the user name Administrator. By default, this account is created with no password.

For a general introduction to administering Crystal Enterprise, including information on making initial security settings, see Administering Crystal Enterprise in the Crystal Enterprise Administrator’s Guide.

Setting up users and groups

Understanding users and groupsBy default, when you install Crystal Enterprise, it creates an Administrator account (with a blank password), and a Guest account.

There are two default users included with Crystal Enterprise: Administrator and Guest. The Administrator user is able to perform all of the tasks in all of the Crystal Enterprise applications (for example, the Crystal Management Console, Crystal Configuration Manager, Crystal Publishing Wizard, and the Crystal Enterprise web desktop). The Guest user can view reports that are found within the Report Samples folder. Generally, the Guest user accesses reports through the Crystal Enterprise web desktop.

Users are members of a group or groups—their rights are determined by which group or groups they are associated with (and also by their user rights). There are three default groups created in Crystal Enterprise: Administrators, Everyone, and New Sign-Up Accounts. In addition to organizing users and simplifying administration, groups enable you to determine the functionality a user has access to.


Configuring your Crystal Enterprise installation

After the user accounts and groups have been created, you can add report objects and specify rights to them. When the users log on, they can view the reports using the Crystal Enterprise web desktop or their custom web application. For more information on objects and rights, see the object rights overview section of the Crystal Enterprise Administrator’s Guide.

For more information on default users and groups, see Managing User Accounts and Groups in the Crystal Enterprise Administrator’s Guide.

Deciding the authentication typeBefore setting up user accounts and groups within Crystal Enterprise, decide which of the available authentication types you want to use:• Enterprise authentication

Use the system default Enterprise Authentication if you prefer to create distinct accounts and groups for use with Crystal Enterprise, or if you have not already set up a hierarchy of users and groups in a Windows NT user database, an LDAP directory server, or a Windows AD server. See the section on managing Enterprise and general accounts in the Crystal Enterprise Administrator’s Guide.

• Windows NT authenticationIf you are working in a Windows NT environment (Windows NT/2000), you can use existing NT user accounts and groups in Crystal Enterprise. When you map NT accounts to Crystal Enterprise, users are able to log on to the Crystal Enterprise web desktop with their NT user name and password. This eliminates the need to recreate individual user and group accounts within Crystal Enterprise. For more information, see the section on managing NT accounts in the Crystal Enterprise Administrator’s Guide

• LDAP authenticationIf you set up an LDAP directory server, you can use existing LDAP user accounts and groups in Crystal Enterprise. When you map LDAP accounts to Crystal Enterprise, users are able to access the Crystal Enterprise web desktop with their LDAP user name and password. This eliminates the need to recreate individual user and group accounts within Crystal Enterprise. For more information, see the section on managing LDAP accounts in the Crystal Enterprise Administrator’s Guide.

• Windows AD authenticationIf you are working in a Windows 2000 environment, you can use existing AD user accounts and groups in Crystal Enterprise. When you map AD accounts to Crystal Enterprise, users are able to log on to the Crystal Enterprise web desktop with their AD user name and password. This eliminates the need to recreate individual user and group accounts within Crystal Enterprise. For more information, see the section on managing Windows AD accounts in the Crystal Enterprise Administrator’s Guide.

Note: You can use Enterprise Authentication in conjunction with either NT, LDAP, or AD authentication, or with all of the three authentication plug-ins.



For more information on Security in Crystal Enterprise, see Crystal Enterprise Security Concepts in the Crystal Enterprise Administrator’s Guide.

Creating and managing users and groupsThe procedures for creating and managing users and groups vary depending upon which authentication method you choose. Please see the appropriate section of the Managing User Accounts and Groups in the Crystal Enterprise Administrator’s Guide.

Creating folders and publishing objects

Creating foldersFolders provide you with the ability to organize and facilitate content administration. They are useful when there are a number of reports that a department or area requires frequent access to, because you can set object rights and limits once, at the folder level, rather than setting them for each report or object within the folder.

By default, new objects that you add to a folder inherit the object rights that are specified for the folder.

For instructions on creating and managing folders, see the Crystal Enterprise Administrator’s Guide.

Publishing objectsPublishing is the process of adding objects such as Crystal reports to the Crystal Enterprise environment and making them available to authorized users. There are several types of objects that you can publish to Crystal Enterprise: reports, programs, Microsoft Excel files, Microsoft Word files, Microsoft PowerPoint files, Adobe Acrobat PDFs, rich text format files, text files, and hyperlinks, as well as object packages, which consist of report and/or program objects.

You can publish objects to Crystal Enterprise in three ways:• Use the Crystal Publishing Wizard when you:

• Have access to the locally installed application.• Are adding multiple objects or an entire directory.For details, see the section on the Crystal Publishing Wizard in the Crystal Enterprise Administrator’s Guide.

• Use the Crystal Management Console (CMC) when you are:• Publishing a single object.• Taking care of other administrative tasks.• Performing tasks remotely.For details, see the section on publishing with the Crystal Management Console in the Crystal Enterprise Administrator’s Guide.



• Save directly to your Enterprise folders when you are:• Designing reports with Crystal Reports.• Creating other objects with Crystal Enterprise plug-in components such as

Crystal Analysis.For details, see the section on saving objects directly to the CMS in the Crystal Enterprise Administrator’s Guide.

Choosing between live and saved dataWhen reporting over the Web, the choice to use live or saved data is one of the most important decisions you’ll make. Whichever choice you make, however, Crystal Enterprise displays the first page as quickly as possible, so you can see your report while the rest of the data is being processed.

Live data

On-demand reporting gives users real-time access to live data, straight from the database server. Use live data to keep users up-to-date on constantly changing data, so they can access information that’s accurate to the second. For instance, if the managers of a large distribution center need to keep track of inventory shipped on a continual basis, then live reporting is the way to give them the information they need.

Before providing live data for all your reports, however, consider whether or not you want all of your users hitting the database server on a continual basis. If the data isn’t rapidly or constantly changing, then all those requests to the database do little more than increase network traffic and consume server resources. In such cases, you may prefer to schedule reports on a recurrent basis so that users can always view recent data (report instances) without hitting the database server.

For more information about optimizing the performance of reports that are viewed on demand, see the “Designing Optimized Web Reports” section in the Crystal Reports User’s Guide (version 8.5 and later).

Tip: Users require View On Demand access to refresh reports against the database.

Saved data

Report instances are useful for dealing with data that isn’t continually updated. When users navigate through report instances, and drill down for details on columns or charts, they don’t access the database server directly; instead, they access the saved data. Consequently, reports with saved data not only minimize data transfer over the network, but also lighten the database server’s workload.

You can schedule these reports within Crystal Enterprise so that they automatically refresh from the database on a predetermined basis. For example, if your sales database is only updated once a day, or once a week, then you can run the report on a similar schedule. Sales representatives then always have access to current sales data, but they aren’t hitting the database every time they open a report.

Tip: Users require only View access to display report instances.



Controlling users’ access to objectsTo secure the content that you publish to Crystal Enterprise, you can set rights for each object. By setting object rights, you can control users’ access to specific content. For each object, you can grant or deny access to users and groups in your system. For example, you can use rights to make sure that you are the only one who can access your reports. You can ensure that confidential employee records can be accessed only by the human resources department.

You can set rights for folders, report objects, program objects, and other Crystal Enterprise objects.

To facilitate administration and maintenance, Crystal Enterprise includes a set of predefined access levels that allow you to set common security levels quickly. Each access level grants a set of rights that combine to allow users to accomplish common tasks (such as view reports, schedule reports, and so on). It is recommended that you use the predefined access levels whenever possible, because they can greatly reduce the complexity of your object security model. For more information, see the section on setting common access levels in the Crystal Enterprise Administrator’s Guide.

Whether or not you use access levels, you can also take advantage of the inheritance patterns recognized by Crystal Enterprise: users can inherit rights as the result of group membership; subgroups can inherit rights from parent groups; and both users and groups can inherit rights from parent folders. When you need to disable inheritance or to customize security levels for particular objects, users, or groups, the Advanced Rights pages allow you to choose from the complete set of available object rights. Most importantly, the advanced object rights allow you to explicitly deny any user or group the right to perform a particular task.

Depending upon your security needs, creating a set of access rights for your objects that is both effective, and easy to understand and administer can be difficult. Before configuring your system it is recommended that you read the following sections of the in the Crystal Enterprise Administrator’s Guide:• Controlling Users’ Access to Objects (Includes a tutorial on setting inherited

rights)• Object Rights and Access Levels (Includes a description of the predefined

access levels).

Advanced administrationOnce you have created users and groups for your system, created folders, published objects, and set access rights for objects in your system, you will want to consider how to further set up and optimize your Crystal Enterprise installation.

Consult your Crystal Enterprise Administrator’s Guide for information how to manage and schedule reports and other objects, how to create and manage events, how to audit user and system actions, and much more.


Installing Crystal Enterprise on Windows 3

This chapter shows how to install Crystal Enterprise onWindows. General system requirements are provided, aswell as procedures covering various installation scenarios.



Installation overviewBefore you install Crystal Enterprise on Windows, consider which of the following scenarios is best for you:• “Full stand-alone installation” on page 33

In this scenario, you install Crystal Enterprise on a single machine that is already running as a web server. This provides the quickest way to install Crystal Enterprise.

• “Server-side installation connected to a web server” on page 37In this scenario, you maintain separation between Crystal Enterprise and your web server by running them on separate machines. Once you’ve installed Crystal Enterprise on one machine, you install and configure the Web Connector on the web server machine.This scenario is also ideal if you have a single UNIX server that is running as your dedicated web server. You retain the use of your UNIX web server, and you can still install Crystal Enterprise on Windows.

• “Expanded installation” on page 43By expanding your installation, you take advantage of the scalability of Crystal Enterprise. The ways in which you choose to expand your system depend largely upon your current configuration and your reporting requirements. This section provides the steps to running the Expand installation. It is strongly recommended that, before you expand your installation, you consult the Crystal Enterprise Administrator’s Guide for sample configurations, general scalability considerations, information about CMS clustering, and so on.

• “Client tools installation” on page 46Although most end users interact with Crystal Enterprise over the Web, client tools are also provided as stand-alone Windows applications: the Crystal Publishing Wizard, the Crystal Repository Migration Wizard, and the Crystal Import Wizard. Install these applications individually for particular users who are responsible for managing Crystal Enterprise content, developing applications, or migrating system data.

• “Custom installation” on page 47The Custom installation allows you to choose exactly which components are installed. It is recommended that you run this installation only when you are familiar with specific Crystal Enterprise components and their roles.

• “Silent installation” on page 51For experienced administrators, the silent installation allows you to install from the command line. It is recommended that you run this installation when you need to install quickly on multiple machines. You can also incorporate the silent installation command into your own build scripts.


3: Installing Crystal Enterprise on Windows

• “Java component installation” on page 53In this scenario, you install Crystal Enterprise on a machine that is running a Java application server. This allows you to deploy pure JSP solutions and the Java version of the Crystal Enterprise web desktop, while still supporting legacy CSP applications and the Crystal Management Console through the Web Component Adapter.

System requirementsFor a detailed list of tested environments, please consult the Platforms.txt file included with your product distribution. This file includes specific version and Service Pack requirements for web servers, web browsers, web application servers, databases, and operating systems. For additional important information that may pertain to your deployment, it is also strongly recommended that you consult the Release Notes included with your product distribution (release.pdf, release.htm, or release.rtf).

Generally, however, the following components must be installed and configured correctly before you install Crystal Enterprise:• Windows• Internet Explorer or Netscape Navigator• Web server software

Crystal Enterprise requires a database to store information about the system and its users. However, the Setup program can install its own Microsoft Data Engine (MSDE) database by default. Alternatively, you can connect your CMS directly to your preferred database server without installing the MSDE.

Setting up the CMS databaseThe Crystal Management Server (CMS) requires a database to store information about the system and its users. By default, the Setup program installs and configures its own Microsoft Data Engine (MSDE) database if necessary. CMS clustering is automatically supported by the default MSDE database.

The MSDE is a client/server data engine that provides local data storage and is compatible with Microsoft SQL Server. If you already have the MSDE or SQL Server installed, the New installation option of the installation program creates the CMS database using your existing database engine.

You can migrate this initial CMS database to another supported database server later. For details, see “Configuring the intelligence tier” in the Crystal Enterprise Administrator’s Guide.

Alternatively, you can connect your CMS directly to your preferred database server without installing the MSDE. Ensure that the MSDE or SQL Server are not installed on your local machine. Then set up the appropriate database client software or


System requirements

ODBC Data Source Name (DSN). Consult your local database administrator or database system documentation for details.

Note: • See the Platforms.txt file included with your product distribution for a

complete list of tested database software and version requirements.• Ensure that your database server is set up to use Unicode character encoding

(such as UTF-8). Consult your database documentation to determine the settings required for a Unicode configuration. For database servers such as Oracle and Sybase, during installation you need to configure the server to use Unicode encoding for the character data types. For other databases, such as DB2 and Informix, you can create the CMS database with Unicode settings on your existing database server.

• Before installing Crystal Enterprise atop an existing installation of the MSDE or Microsoft SQL Server, you need to complete several preparatory steps before running the Crystal Enterprise setup program.

To set up a database account for Crystal Enterprise on MSDE1 Determine whether the CMS should use Windows NT or SQL Server

authentication when connecting to your local database installation.

2 Using your usual administrative tools, create or select a user account that provides Crystal Enterprise with the appropriate privileges to your database server:• If you want the CMS to connect to its database using Windows NT

authentication, ensure that the Windows NT user account that you assign to the CMS belongs to the System Administrators role in your SQL Server installation.In this scenario, the Windows NT user account that you assign to the CMS is not actually used to create the system database during the installation process. Instead, your own Windows NT administrative account is used to create the database, so verify that your Windows NT account also belongs to the System Administrators role in your SQL Server installation.

• If you want the CMS to connect to its database using SQL Server authentication, the login that you assign to the CMS must belong to the Database Creators role in your SQL Server installation.In this scenario, the SQL Server credentials that you assign to the CMS are also used to create the database and its tables.

3 Verify that you can log on to SQL Server and carry out administrative tasks using the account you set up for use by the CMS.

Providing administrative privilegesYou must log on to the local machine as an Administrator when you install Crystal Enterprise.



Meeting network requirementsWhen installing Crystal Enterprise on multiple machines, ensure that each target machine is able to communicate over TCP/IP with the machine that is running as your CMS. In particular, your web server must be able to communicate with the machine that is running as your Web Component Server (WCS). This communication is enabled by the Web Connector, which you must install on your web server machine. All web desktop clients must be able to access the web server.

Note: If you are installing Crystal Enterprise in a firewall environment, you will need additional configuration details. See the “Working with Firewalls” section of the Crystal Enterprise Administrator’s Guide.

Installing Crystal products on a non-system driveYou can install Crystal Enterprise on any drive on your machine. The Setup program installs Crystal Enterprise files only on the drive that you specify.

There is one exception to this rule. If you previously installed another Crystal product, the Crystal Enterprise Setup program automatically uses the existing common directory for any shared Crystal product files that it adds. If this common directory is on the system drive (that is, the drive containing your operating system files), Crystal Enterprise automatically installs its shared files there.

To install several Crystal products on a non-system drive, install Crystal Enterprise first. All Crystal products that you install subsequently will use this same non-system drive for their shared files.

Full stand-alone installationThis installation scenario offers the quickest way to install Crystal Enterprise. Once you have set up your web server software, run the New installation from the Crystal Enterprise Setup program.

When you perform this default installation, all the client and server components are installed on the local machine. The CMS automatically creates its own database. The Web Connector is automatically configured to allow communication between Crystal Enterprise and the web server software that you have already installed. Default user and group accounts are created, and sample reports are published to the system. When the installation is complete, the server components are started as services on the local machine.

Note: • If the Microsoft Data Engine (MSDE) or Microsoft SQL Server is already

installed on the local machine, you must first set up an account for the CMS. For details, see “Setting up the CMS database” on page 31


Full stand-alone installation

• To install Crystal Enterprise without installing the MSDE on your local machine, you must perform a custom installation. For details, see “Custom installation” on page 47.

To install all components1 Unless Autoplay is enabled for your CD-ROM drive, run setup.exe from the

win32 directory of your product distribution.When you start the installation, the Microsoft Windows Installer may need to be installed or upgraded on the local machine. If so, the Wise Installation Wizard performs the necessary modifications and prompts you when finished. Click Yes to restart the machine and resume the installation automatically.

2 Proceed through the Setup program’s dialog boxes and follow the instructions on the screen until you reach the Directory selection dialog box:

You can install Crystal Enterprise on any drive on your machine. Click Next.

If you chose to install on a drive other than the default location (C:\Program Files\Crystal Decisions\Enterprise 10), the Setup program next asks you to select a drive for the installation of common files. These common files are also used by Crystal products such as Crystal Reports or Crystal Analysis.

Note: To install several Crystal products on the same machine without installing files on the default system drive, first install Crystal Enterprise. When you subsequently install Crystal Reports or Crystal Analysis, those programs will use the common file directory created by Crystal Enterprise.



Otherwise, the Setup program proceeds directly to the Installation Type dialog box.

3 Click New; then click Next.The setup program checks to see whether or not the Microsoft Data Engine (MSDE) or Microsoft SQL Server is already installed on the local machine.

4 If the setup program detects the MSDE or SQL Server, use the “Microsoft SQL Server Authentication” dialog box to provide the credentials that correspond to the database account you set up for the CMS.


Full stand-alone installation

Note: If you have not yet created an account for the CMS, see “Setting up the CMS database” on page 31.Select Overwrite database to overwrite any existing CMS database on this machine and proceed with the install. (If there is an existing CMS database, you must select this option to proceed with the installation. See the Crystal Enterprise Administrator’s Guide for information on migrating data from a CMS database).

5 If the setup program does not detect an existing MSDE or SQL Server database, use the “MSDE Security Configuration” dialog box to create a password for the default SQL administrator account that will be installed along with the MSDE.

The setup program later configures the CMS to connect to its system database using this “sa” account and the password you create here.

6 When you reach the Start Installation dialog box, click Next.The installation of files begins immediately. During the installation process, you may be prompted to restart the local machine. When the installation program has finished copying files, you are given the opportunity to register your product.

7 When you reach the final setup dialog box, clear Launch Crystal Publishing Wizard unless you want to publish your own reports to Crystal Enterprise immediately.Tip: Sample reports are installed by default, so you can verify your installation and learn your way around Crystal Enterprise.

8 Click Finish.

If the web server installed on the local machine is a supported version of Microsoft IIS, iPlanet Enterprise Server, or Lotus Domino, then the Setup program installs and configures the appropriate Crystal Enterprise Web Connector. Thus, when the



installation is complete, you can access Crystal Enterprise by opening your web browser and going to:

http://webserver/crystal/enterprise10/

Here, the term webserver represents the name of the local machine.

Note: • For CGI web servers, you must perform additional configuration before you

can access Crystal Enterprise. For details, see “Configuring Web Connectors” on page 91.

• If you cannot access Crystal Enterprise, start the Crystal Configuration Manager (CCM) from the Crystal Enterprise program group. Ensure that all of the servers listed are both started and enabled.

Server-side installation connected to a web serverA server-side installation connected to a web server is a quick way to integrate Crystal Enterprise with your existing web server—without installing the core Crystal Enterprise components on the web server itself.

First, on the machine that you have set aside for use by Crystal Enterprise, run the New installation from the Crystal Enterprise Setup program. Then, install and configure the appropriate Web Connector on your web server machine:• If the web server is running on Windows, you can select the Web Connector by

running the Custom installation from the Crystal Enterprise Setup program.• If the web server is running on UNIX, see “Installing a Web Connector on a

UNIX web server” on page 89.

When you perform this installation, the client and server components are installed, the default user and group accounts are created, and the sample reports are published to the system. When the installation is complete, the servers are started as services on the local machine. You will need to configure the Web Connector manually.

Note: • If the Microsoft Data Engine (MSDE) or Microsoft SQL Server is already

installed on the local machine, you must first set up an account for the CMS. For details, see “Setting up the CMS database” on page 31.

• You can connect your CMS directly to your preferred database server without installing the MSDE. Ensure that the MSDE or SQL Server are not installed on your local machine. Then set up the appropriate database client software or ODBC Data Source Name (DSN). Consult your local database administrator or database system documentation for details.


Server-side installation connected to a web server

To install the Crystal Enterprise serversNote: Follow these steps on the machine that you have set aside for Crystal Enterprise.

1 Unless Autoplay is enabled for your CD-ROM drive, run setup.exe from the win32 directory of your product distribution.When you start the installation, the Microsoft Windows Installer may need to be installed or upgraded on the local machine. If so, the Wise Installation Wizard performs the necessary modifications and prompts you when finished. Click Yes to restart the machine and resume the installation automatically.


You can install the Crystal Enterprise servers on any drive on your machine. Click Next.

If you chose to install on a drive other than the default location (C:\Program Files\Crystal Decisions\Enterprise 10), the Setup program next asks you to select a drive for the installation of common files. These common files are also used by Crystal products such as Crystal Reports or Crystal Analysis.


3 When you reach the Installation Type dialog box, click Custom; then click Next.



4 In the Select Features dialog box, click the Web Server Connectors feature (under Servers) and select Entire feature will be unavailable.

Note: The setup program checks to see whether or not the Microsoft Data Engine (MSDE) or Microsoft SQL Server is already installed on the local machine.If not, and you don’t want to install the MSDE, under the Crystal Management Server, click MSDE and select Entire feature will be unavailable.

5 Click Next.The CMS Clustering dialog box appears.



6 Unless you want to cluster this new system with an existing system, select No and ensure that Enable servers upon install remains selected.Tip: For more information on CMS clusters, see the Crystal Enterprise Administrator’s Guide.

7 Click Next.

8 If the setup program detects the MSDE or SQL Server, use the “Microsoft SQL Server Authentication” dialog box to provide the credentials that correspond to the database account you set up for the CMS.

Note: If you have not yet created an account for the CMS, see “Setting up the CMS database” on page 31.Select Overwrite database to overwrite any existing CMS database on this machine and proceed with the install. (If you do not select this option and the setup program detects an existing CMS database, the installation terminates. See the Crystal Enterprise Administrator’s Guide for information on migrating data from a CMS database).

9 If the setup program does not detect an existing MSDE or SQL Server database, it checks to see if the MSDE feature is selected for installation. If it is, use the “MSDE Security Configuration” dialog box to create a password for the default SQL administrator account that will be installed along with the MSDE.



The setup program later configures the CMS to connect to its system database using this “sa” account and the password you create here.

10 If the setup program does not detect an existing MSDE or SQL Server database, and the MSDE feature is not selected for installation, the “CMS Database Information” dialog box appears.

Specify the database connection type that the CMS must use to connect to the CMS database:• If you select SQL Server or Informix, click Select DSN to choose (or create)

the appropriate system data source and provide the database Login ID and password. Then click Next.



• If you select Oracle, DB2, or Sybase, enter the name of the database server, along with the database Login ID and password. Then click Next.


12 When you reach the final setup dialog box, clear Launch Crystal Publishing Wizard.

13 Click Finish.

To install the Web Connector on a Windows web serverNote: Complete these steps on your web server machine.


2 Proceed through the Setup program’s dialog boxes and follow the instructions displayed on your screen until you reach the Installation Type dialog box.

3 Click Custom; then click Next.

4 In the Select Features dialog box, select the Web Server Connectors (under Servers) and Help Files options, and disable all of the remaining components.



5 Click Next.You are prompted to enter a Web Component Server Name.

6 Type the name of the machine upon which you installed the Crystal Enterprise Web Component Server (WCS) component.By default, the Web Connector that you are installing will forward Crystal Enterprise requests to port 6401 on the WCS machine. If you configured the WCS to listen on a different port, type your entry as machinename:portnumber

7 Click Next.

8 In the Start Installation dialog box, click Next. The installation of files begins immediately. When the installation program has finished copying files, the final setup screen appears.

9 Click Finish and, if prompted, restart the local machine.

If the web server installed on the local machine is a supported version of Microsoft IIS, iPlanet Enterprise Server, or Lotus Domino, then the Setup program installs and configures the appropriate Crystal Enterprise Web Connector. Thus, when the installation is complete, you can access Crystal Enterprise by opening your web browser and going to:


Here, the term webserver represents the name of your web server machine. The Web Connector installed on that machine sets up the appropriate virtual directory mappings for the web server. The Web Connector also intercepts all Crystal Enterprise scripting requests and forwards them to the Web Component Server that you installed on your Crystal Enterprise machine. The Web Component Server evaluates the script and forwards its response to the web server through the Web Connector.

Note: For CGI web servers, you must perform additional configuration before you can access Crystal Enterprise. For details, see Chapter 5: Configuring Web Connectors.

Expanded installationOnce Crystal Enterprise is up and running on one machine, run the Expand installation on other machines to add server components, create a CMS cluster, increase available resources, and distribute the processing workload.

The ways in which you choose to expand your system depend largely upon your current configuration and your reporting requirements. This section provides the steps to running the Expand installation. It is strongly recommended that, before you expand your installation, you consult the Crystal Enterprise Administrator’s Guide for sample configurations, general scalability considerations, information about CMS clustering, and so on.


Expanded installation

Note: • If you are adding another CMS, first set up the appropriate database client

software or ODBC Data Source Name (DSN) on the local machine. The new CMS must connect to the CMS database in the same manner as the existing CMS. Also ensure that you have the database user name (Login ID) and password that the existing CMS uses to connect to the CMS database. If you are unfamiliar with CMS clusters, see the Crystal Enterprise Administrator’s Guide.

• If you are adding another WCS, you will need to reconfigure your Web Connector so that it can communicate with both WCS machines. Once set up, the Web Connector automatically balances the Crystal Enterprise load across available WCS machines.

To expand an existing system1 Unless Autoplay is enabled for your CD-ROM drive, run setup.exe from the



You can install Crystal Enterprise servers on any drive on your machine. Click Next.





4 Click Expand; then click Next.The Expand Options dialog box appears.

5 In the Existing CMS Name field, type the name of the machine that is currently running as your CMS.

6 Select the check boxes that correspond to the servers that you want to add to the local machine and register with the existing CMS. Clear the remaining check boxes.The options available to you include some common server combinations. For instance, you can install a new CMS and cluster it with the existing CMS by selecting only the CMS check box. Or, you can increase the report-processing capabilities of your system by selecting the Processing Servers check box, which adds both a Job Server and a Page Server to the local machine.Tip: For greater control over the individual components that are installed, perform a Custom installation. For details, see “Custom installation” on page 47.

7 Select the Enable servers upon install check box.If you choose not to enable the servers immediately, use the Crystal Configuration Manager (CCM) to start the servers and then to enable them.

8 Click Next.If you chose to add an additional CMS, the CMS Database Information dialog box appears.


Client tools installation

9 Specify the database connection type that the CMS must use to connect to the existing CMS database:• If you select SQL Server or Informix, click Select DSN to choose (or create)

the appropriate system data source and provide the database Login ID and password. Ensure that the values you provide match the values used by your existing CMS to connect to the CMS database. Then click Next.

• If you select Oracle, DB2, or Sybase, enter the name of the database server, along with the database Login ID and password. Ensure that the values you provide match the values used by your existing CMS to connect to the CMS database. Then click Next.

10 In the Start Installation dialog box, click Next.The installation of files begins immediately. When the installation program has finished copying files, the final setup screen appears.

11 Click Finish and, if prompted, restart the local machine.

Client tools installationThis section shows you how to perform a Custom installation that installs only the client tools on the local machine. These tools are the Crystal Publishing Wizard and the Crystal Import Wizard.

Tip: These client tools are not needed by users who access the Crystal Enterprise web desktop or the Crystal Management Console (CMC) administrative web application. Rather, these additional tools are provided for users who are responsible for publishing multiple reports or for moving objects between systems.



If you install the Crystal Enterprise servers on a UNIX machine, you can connect remotely to Crystal Enterprise with the client tools. However, the client applications must be installed on Windows.

To install the client tools1 Unless Autoplay is enabled for your CD-ROM drive, run setup.exe from the



3 Click Custom; then click Next.

4 In the Select Features dialog box, select the client components that you want to install and disable the remaining components.

5 Click Next.

6 In the Start Installation dialog box, click Next. The installation of files begins immediately. When the installation program has finished copying files, follow any additional instructions that appear.

Custom installationSelecting the Custom installation option invokes the Select Features dialog box, which allows you to install specific features, to change the default location of various features, and to check the amount of disk space required by each feature. Use the Custom installation when you are familiar with Crystal Enterprise and know exactly which components you need to install on any particular machine.

In particular, see the Crystal Enterprise Administrator’s Guide for information about scaling your deployment across multiple machines.

The icons in the feature tree indicate whether the feature and its subfeatures will be installed or not:• A white icon means that the feature and all its subfeatures will be installed.• A shaded icon means that the feature and some of its subfeatures will be installed.• A red X means that the feature or subfeature is either unavailable or will not be

installed.

To select the configuration and location of a feature or subfeature, click its icon.

Note: Each feature or subfeature can have its own configuration and location.


Custom installation

Use the following table to determine your installation options for each feature or subfeature:

Note: Subfeatures are listed below each feature. A subfeature can have a different type of installation than its parent feature.

To install a full standalone Crystal Enterprise without the MSDEYou can use the Custom installation option to install Crystal Enterprise without the Microsoft Data Engine (MSDE). Ensure that the MSDE or SQL Server are not installed on your local machine. Then set up the appropriate database client software or ODBC Data Source Name (DSN). (Consult your local database administrator or your database system documentation for details.)


2 Proceed through the Setup program’s dialog boxes and follow the instructions on the screen until you reach the Directory selection dialog box:You can install Crystal Enterprise on any drive on your machine. Click Next.Note: To install several Crystal products on the same machine without installing files on the default system drive, first install Crystal Enterprise. When you subsequently install Crystal Reports or Crystal Analysis, those programs will use the common file directory created by Crystal Enterprise.

3 When you reach the Installation Type dialog box, click Custom; then click Next.

Type of feature installation Description of what is installed

Will be installed on local hard drive

• Installs the feature on the hard drive you specified in the Setup program.• Uses typical installation settings to install some of the feature’s subfeatures to the hard drive you specified earlier.

Entire feature will be installed on local hard drive

• Installs the feature and all of its subfeatures on the hard drive you specified earlier.

Entire feature will be unavailable • Neither the feature nor its subfeatures are installed.



4 In the Select Features dialog box, click the MSDE feature (under Servers > Crystal Management Server) and select Entire feature will be unavailable.

5 Click Next.The CMS Clustering dialog box appears.

6 Unless you want to cluster this new system with an existing system, select No and ensure that Enable servers upon install remains selected.Tip: For more information on CMS clusters, see the Crystal Enterprise Administrator’s Guide.


Custom installation

7 Click Next.The “CMS Database Information” dialog box appears.

8 Specify the database connection type that the CMS must use to connect to the CMS database:• If you select SQL Server or Informix, click Select DSN to choose (or create)

the appropriate system data source and provide the database Login ID and password. Then click Next.

• If you select Oracle, DB2, or Sybase, enter the name of the database server, along with the database Login ID and password. Then click Next.


10 When you reach the final setup dialog box, clear Launch Crystal Publishing Wizard unless you want to publish your own reports to Crystal Enterprise immediately.Tip: Sample reports are installed by default, so you can verify your installation and learn your way around Crystal Enterprise.

11 Click Finish.

If the web server installed on the local machine is a supported version of Microsoft IIS, iPlanet Enterprise Server, or Lotus Domino, then the Setup program installs and configures the appropriate Crystal Enterprise Web Connector. Thus, when the installation is complete, you can access Crystal Enterprise by opening your web browser and going to:




Here, the term webserver represents the name of the local machine.

Note: • For CGI web servers, you must perform additional configuration before you

can access Crystal Enterprise. For details, see Chapter 5: Configuring Web Connectors.

• If you cannot access Crystal Enterprise, start the Crystal Configuration Manager (CCM) from the Crystal Enterprise program group. Ensure that all of the servers listed are both started and enabled.

Silent installationA silent installation is one that you run from the command line to automatically install Crystal Enterprise on any machine in your system, without the installation program prompting for information during the installation. To install silently, you run an msiexec command from the command line. The command must include a series of parameters that provide information for installation settings and directory paths.

The silent Crystal Enterprise installation is particularly useful when you need to perform multiple installations and do not want to interrupt people who are working on machines in your system. You can also use the silent installation command in your own scripts. For example, if your organization uses scripts to install software on machines, you can add the silent Crystal Enterprise installation command to your scripts.

The silent installation command consists of the command msiexec, followed by the location of the installation executable file, and a number of parameters that provide information about the installation. The following example installs Crystal Enterprise with the CMS onto the myserver machine:

Msiexec /i “\\mynetworkfolder\Crystal Decisions\Enterprise10\cer.msi” REBOOT=ReallySuppress /qn+ INSTALLLEVEL=5 PIDKEY=A1234-ABCD123-12345A6 DATABASEUSER=sa DATABASEPWD=mypassword INSTALLDIR=”C:\Program Files\Crystal Decisions\Enterprise 10” CRYSTALDECISIONSCOMMONFOLDER=”C:\Program Files\Common Files\Crystal Decisions\Enterprise 10”

The example uses the most common parameters. You can choose any number of valid parameters, but it is good practice to keep the silent installation as simple as possible.

The following table lists the most common parameters used in a silent installation. To use a parameter, place it on the command line after the msiexec command and the path for the installation files.


Silent installation

Installation parameter Description

INSTALLDIR=“filepath” • Specifies the machine and directory where you want to install the new Crystal Enterprise components. Replace filepath with the full path for the installation directory. For example, “C:\Program Files\Crystal Decisions\Crystal Enterprise 10”.

CRYSTALDECISIONSCOMMONFOLDER="filepath"

• Specifies the machine and directory where you want to store the common files directory created during the installation. Replace filepath with the full path for the common files directory. For example, “C:\Program Files\Common Files\Crystal Decisions\Crystal Enterprise 10”.

PIDKEY=00000-0000000-0000000 • Specifies your product activation keycode.

DATABASEUSER=myusername • If you’re using SQL Server, use this parameter to specify the user name for the database you’ll be using for Crystal Enterprise.

DATABASEPWD=mypassword • If you’re using SQL Server, use this parameter to specify the administrator password for the database you’ll be using for Crystal Enterprise.

DATABASEDRIVER=“OracleDatabaseSubsystem”

• If you do not use SQL Server, include this parameter to identify the type of database. This example specifies Oracle as the database. Other valid values for this parameter include “DB2DatabaseSubSystem” and “SybaseDatabaseSubSystem”.

DATABASECONNECT=“DSN=OracleNetServiceName;UID=OracleUserName;PWD=OraclePassword”

• If you do not use SQL Server, include this parameter to provide your connection information. This example uses a native Oracle connection. The DSN value is the service name configured in the Oracle Client.For a DB2 native connection, the DSN value is the database alias configured in the DB2 Client Configuration Assistant.



Note: • The silent installation is not available from the Crystal Enterprise Setup program

and is intended only for experienced administrators of Crystal Enterprise. • The silent installation is not recommended for custom installations. The

installation options are simplified and do not allow for the same level of customization that the Crystal Enterprise Setup program provides.

• Silent installations are not recommended for upgrades.

Java component installationWhen you install Crystal Enterprise on Windows using the Crystal Enterprise Setup program, by default you install and deploy the CSP version of the Crystal Enterprise web desktop and the Crystal Enterprise COM SDK. Unless you specifically remove the Java SDK feature (found under Crystal Developer components in the Select Features dialog box, on a custom installation), the Setup program also installs the Crystal Enterprise Java SDK and the Java version of the Crystal Enterprise web desktop. However, those components will not be deployed unless you follow the steps outlined here.

For more information about the system architecture of a Java installation of Crystal Enterprise, see the architecture chapter of the Crystal Enterprise Administrator’s Guide.

INSTALLLEVEL=5 • Determines which Crystal Enterprise components are installed. If you set the install level parameter to 5, all components will be installed. If you set this parameter to 3, all components except the CMS will be installed. For SDK installations, use install level 4.

REBOOT=ReallySuppress • Prevents Crystal Enterprise from prompting the user to reboot the machine.

/qn+ • Performs the installation silently, but prompts the user when the installation is complete.

/qn • Performs the installation silently, without prompting the user.

NOMSDE=1 • Crystal Enterprise installs the MSDE by default. To remove the MSDE from the installation, add this parameter and set it to 1. To keep the MSDE in the installation, do not add this parameter to the command.

Installation parameter Description


Java component installation

Note: You cannot use the shortcuts in the Crystal Enterprise program group to access the Crystal Enterprise Launchpads deployed on your Java web application server. To access them, you must include the port number of the Java web application server in your URL. That is, to access the Crystal Enterprise User Launchpad running on your Java web application server, type:

http://server01:portnum/crystal/enterprise10/desktoplaunch/en/default.htm

To access the Crystal Enterprise Admin Launchpad running on your Java web application server, type:

http://server01:portnum/crystal/enterprise10/adminlaunch/en/default.htm

where server01 is the name of the server, and portnum is the port number of the Java web application server.

Click the appropriate link to jump to that section:• “Installing the Java SDK” on page 54• “Installing a Java application server” on page 55• “Installing Crystal Enterprise” on page 55• “Deploying the Java version of the Crystal Enterprise web desktop” on

page 55• “Deploying the Web Component Adapter” on page 58

Installing the Java SDKIf your Java web application server does not install the Java SDK as part of its installation process, you must install the J2SE SDK first, before installing your application server. You can download the J2SE SDK from java.sun.com.

Read the documentation on the Sun web site, and select a version of the J2SE SDK that is compatible both with your Java application server and with the Crystal Enterprise Java SDK. Consult the Platforms.txt file that is included with your product distribution for more information.

Configuring the Java environment variableAfter installing the Java SDK, you must set the JAVA_HOME environment variable. If your Java web application server installs the Java SDK as part of its installation process, install the application server first, and then set the environment variable. You need to know the directory path containing your Java SDK bin directory.

To set the JAVA_HOME environment variable on Windows1 Right-click My Computer, and select Properties.

2 Click the Advanced tab.

3 Click Environment Variables.

4 In the System variables area, click New.



5 In the Variable Name box, type JAVA_HOME.

6 Enter the complete path to the directory containing your Java SDK bin directory in the Variable Value box. For example, enter C:\bea\jdk141_02 if you have completed a default installation of BEA WebLogic 8.

7 Click OK > OK > OK.

Installing a Java application serverInstall one of the supported Java application servers on the same machine where you have installed the J2SE SDK, and where you plan to install the Crystal Enterprise Java SDK. Make sure that your Java application server can communicate with the machine(s) that run your Crystal Enterprise servers over TCP/IP. Alternatively, you can install your Java application server, Crystal Enterprise Java SDK, and all Crystal Enterprise servers on the same machine.

For a detailed list of tested Java application servers, consult the Platforms.txt file included with your product distribution.

Note: If you have a firewall between the machine running your Java application server and your other Crystal Enterprise servers, you must perform additional system configuration. See the section on how to configure firewalls, in your Crystal Enterprise Administrator’s Guide.

Follow the installation instructions that come with your Java web application server. Once your server is installed and running, verify that the application server is running correctly by launching its default page, or administrative console in a web browser.• For Tomcat, type http://servername:8080/• For BEA WebLogic 8, type http://servername:7001/console• For IBM WebSphere 5, type http://servername:9090/admin

Installing Crystal EnterprisePerform a custom installation of Crystal Enterprise, and install all components except the Web Component Server and the Web Connector. (See “Custom installation” on page 47 for instructions.) Make sure to install the WCA feature and the Crystal Enterprise Java SDK feature (found under Crystal Developer components in the Select Features dialog box) on the machine where you installed your Java application server.

Deploying the Java version of the Crystal Enterprise web desktopTo deploy the Java version of the Crystal Enterprise web desktop, you must create virtual path mappings on your Java web application server. They must map specific URLs to the web application archives (.war files) that implement the Crystal Enterprise User Launchpad and the Crystal Enterprise Admin Launchpad.


Once you have deployed the Launchpads and the Web Component Adapter, set the context path for the WCA in the Crystal Applications area of the Crystal Management Console. Setting the context path ensures that users can view reports using the Active X viewer and the Java viewer shipped with Crystal Enterprise.

Note: You cannot use the shortcuts in the Crystal Enterprise program group to access the Crystal Enterprise Launchpads deployed on your Java web application server. To access them, you must include the port number of the Java web application server in your URL. That is, to access the Crystal Enterprise User Launchpad running on your Java web application server, type:

http://server01:portnum/crystal/enterprise10/desktoplaunch/en/default.htm

To access the Crystal Enterprise Admin Launchpad running on your Java web application server, type:

http://server01:portnum/crystal/enterprise10/adminlaunch/en/default.htm

where server01 is the name of the server, and portnum is the port number of the Java web application server.

To deploy the Crystal Enterprise Launchpads on Tomcat1 Shut down Tomcat if it is running. Type %CATALINA_HOME%\bin\shutdown in the

Command Prompt window.

2 Open the file %CATALINA_HOME%\conf\server.xml, in a text editor such as Notepad.

3 Add the following lines directly above the line :

<Context path=”/crystal/enterprise10/adminlaunch”docBase=”C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\admin.war”debug=”0” reloadable=”false”/>

<Context path=”/crystal/enterprise10/desktoplaunch”docBase=”C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\desktop.war”debug=”0” reloadable=”false”/>

Note: If you install Crystal Enterprise in a location other than the default installation directory of C:\ProgramFiles\Crystal Decisions\Enterprise 10, adjust the path descriptions to match your actual install directories.

4 Save the file.

5 Restart Tomcat by typing %CATALINA_HOME%\bin\startup at the command prompt.

6 To test the Crystal Enterprise User Launchpad, open a web browser and type http://servername:8080/crystal/enterprise10/desktoplaunch in its address bar. For servername, substitute the name of the machine where you installed Tomcat.The Crystal Enterprise User Launchpad should open.


7 To log on to the Java version of the Crystal Enterprise web desktop, click the Crystal Enterprise link.

8 To test the Crystal Enterprise Admin Launchpad, open a web browser and type http://servername:8080/crystal/enterprise10/adminlaunch in its address bar. For servername, substitute the name of the machine where you installed Tomcat.The Crystal Enterprise Admin Launchpad should open. Do not click the link to the Crystal Management Console. You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 58 for instructions.

9 Once you have deployed the CMC, ensure that the context path for the WCA is set correctly in the Crystal Applications area of the CMC. See “Deploying the Web Component Adapter” on page 58 for instructions.

To deploy the Crystal Enterprise Launchpads on BEA WebLogic1 Open a web browser, and type http://servername:7001/console in its address

bar to open the BEA WebLogic Administrative Console. Note: For servername, substitute the name of the machine where you installed BEA WebLogic. By default, BEA WebLogic uses port 7001. If you configured your application server to use a different port number, substitute that port number in the URL.

2 Deploy the Crystal Enterprise User Launchpad as a new web application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\desktop.war, and set the context root to /crystal/enterprise10/desktoplaunch

3 To test the Crystal Enterprise User Launchpad, type http://servername:7001/crystal/enterprise10/desktoplaunch in the address bar of a web browser. The Crystal Enterprise User Launchpad should open.


5 Deploy the Crystal Enterprise Admin Launchpad as a new web application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\admin.war, and set the context root to /crystal/enterprise10/adminlaunch

6 To test the Crystal Enterprise Admin Launchpad, open a web browser and type http://servername:8080/crystal/enterprise10/adminlaunch in its address bar. For servername, substitute the name of the machine where you installed BEA WebLogic.The Crystal Enterprise Admin Launchpad should open. Do not click the link to the Crystal Management Console (CMC). You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 58 for instructions.




To deploy the Crystal Enterprise Launchpads on IBM WebSphere 1 Start the IBM WebSphere Administrative Console. (http://servername:9090/

admin/).

2 Install the Crystal Enterprise User Launchpad as a new application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\desktop.war, and set the context root to /crystal/enterprise10/desktoplaunch

3 Start the new application.

4 To test the Crystal Enterprise User Launchpad, type http://servername:9080/crystal/enterprise10/desktoplaunch/launchpad.html in the address bar of a web browser. The Crystal Enterprise User Launchpad should open.


6 Install the Crystal Enterprise Admin Launchpad as a new application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\admin.war, and set the context root to /crystal/enterprise10/adminlaunch


8 To test the Crystal Enterprise Admin Launchpad, type http://servername:9080/crystal/enterprise10/adminlaunch/launchpad.html in the address bar of a web browser. The Crystal Enterprise Admin Launchpad should open. Do not click the link to the Crystal Management Console. You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 58 for instructions.


Deploying the Web Component AdapterThe Web Component Adapter (WCA) is a Java web application that runs on your Web Application Server. The WCA hosts web components, including a CSP plug-in that allows you to run CSP applications on your Java Web Application Server. You must deploy the WCA to run the Crystal Management Console, and other CSP applications, in a Java Crystal Enterprise environment.



The Crystal Enterprise setup program configures the Web archive file that implements the WCA (webcompadapter.war) with specific information:• The name and location of your Crystal Management Server.• The default display name of the WCA.• The location of the directories where the WCA can find CSP applications.• The location it should use for log files.

In most situations you should not need to change these default values. If you do, see “Changing the default deployment values for the WCA” on page 62.

To deploy the WCA, you must first configure your Java web application server to use the cewcanative.jar archive file. Then you must deploy the Web Component Adapter archive webcompadapter.war as a web application.

To deploy the WCA using Tomcat on Windows1 Shut down Tomcat if it is running. Type %CATALINA_HOME%\bin\shutdown in the

Command Prompt window.

2 Add C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\ to the PATH environment variable. (This directory contains Crystal Enterprise DLLs that the WCA uses.) See “To set the JAVA_HOME environment variable on Windows” on page 54 for instructions on how to set a Windows environment variable.

3 Copy the Java archive file cewcanative.jar (found in C:\Program Files\Crystal Decisions\Enterprise 10\java\applications) to %CATALINA_HOME%\shared\lib.

4 Open the file %CATALINA_HOME%\conf\server.xml, in a text editor such as Notepad.


<Context path=”/crystal”docBase=”C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\webcompadapter.war”debug=”0” reloadable=”false”/>

Note: If you installed Crystal Enterprise in a location other than the default installation directory of C:\Program Files\Crystal Decisions\Enterprise 10\java\applications, adjust the path descriptions to match your install directories.

6 Save the file.

7 Restart Tomcat by typing %CATALINA_HOME%\bin\startup at the command prompt.

8 To test the deployment of the WCA, launch the Crystal Management Console by typing http://servername:8080/crystal/enterprise10/admin in the address bar of a web browser.



For servername, substitute the name of the machine where you installed Tomcat. If you chose to use a port number other than the default value, substitute that value for 8080.

9 Log on to the Crystal Management Console (CMC) as Administrator. By default, the Administrator account has no password.

10 Go to the Crystal Applications area of the CMC, and click Web Desktop.

11 On the Properties tab, ensure that the WCA context path is set to /crystal.

12 Click Update.You can now view reports in Crystal Enterprise using the Active X and Java viewers.

To deploy the WCA using BEA WebLogic on Windows1 Make sure that your BEA WebLogic server is not running.

2 Add C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\ to the PATH environment variable. (This directory contains Crystal Enterprise DLLs used by the WCA.) See “To set the JAVA_HOME environment variable on Windows” on page 54 for instructions on how to set a Windows environment variable.

3 Edit your CLASSPATH environment variable to include C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\cewcanative.jar

4 Start your BEA WebLogic server.

5 Open a web browser, and type http://servername:7001/console in its address bar to start the BEA WebLogic Administrative Console. For servername, substitute the name of the machine where you installed BEA WebLogic. If you chose to use a port number other than the default value, substitute that value for 7001.

6 Deploy the Web Component Adapter as a new web application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\webcompadapter.war, and set the context root to /crystal

7 To test the deployment of the WCA, launch the Crystal Management Console by typing http://servername:7001/crystal/enterprise10/admin in its address bar. For servername, substitute the name of the machine where you installed BEA WebLogic. If you chose to use a port number other than the default value, substitute that value for 7001.







To deploy the WCA using IBM WebSphere 5 on Windows1 Make sure that your IBM WebSphere server is not running.

2 Add C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\ to the PATH environment variable. (This directory contains Crystal Enterprise DLLs used by the WCA.) See “To set the JAVA_HOME environment variable on Windows” on page 54 for instructions on how to set a Windows environment variable.

3 Edit your CLASSPATH environment variable to include C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\cewcanative.jar

Note: IBM WebSphere is case-sensitive. Make sure that you add the filename and path exactly as it appears here.

4 Start your IBM WebSphere Server, and launch the Administrative Console (at http://servername:9090/admin/).For servername, substitute the name of the machine where you installed IBM WebSphere. If you chose to use a port number other than the default value for the administrative console, substitute that value for 9090.

5 Deploy the Web Component Adapter as a new application. Use the .war file found at C:\Program Files\Crystal Decisions\Enterprise 10\java\applications\webcompadapter.war, and set the context root to /crystal


7 To test that you have deployed the WCA correctly, launch the Crystal Management Console by opening a web browser and typing http://servername:9080/crystal/enterprise10/admin/admin.cwr in the address bar of a web browser. For servername, substitute the name of the machine where you installed IBM WebSphere. If you use a port number other than the default value, substitute that value for 9080.







Changing the default deployment values for the WCAThe Crystal Enterprise setup program configures the Web archive file that implements the WCA (webcompadapter.war) with specific information:• The name and location of your Crystal Management Server.• The default display name of the WCA.• The location of the directories where the WCA can find CSP applications.• The location it should use for log files.

You may need to change some of these values to change the location of the WCA log files, if you want to deploy your custom CSP applications in a location other than the default directory, or if you plan to deploy multiple WCAs. To do so, edit the web.xml file contained in the WEB-INF directory of the archive.

Note: See “Installing multiple Web Component Adapters” on page 63 for further instructions before you install multiple WCAs.

To change the deployment values for the WCA1 Stop your Java application server, if it is running.

2 Extract web.xml from webcompadapter.war using a tool such as WinZip.The webcompadapter.war archive file is stored in the C:\Program Files\Crystal Decisions\Enterprise 10\java\applications directory.

3 Open web.xml in a text editor such as Notepad. To alter the values of cspApplication.dir (the directory for your CSP applications), or log.file (the location of the log files created by the WCA), edit the following lines to change the values between the <param-value></param-value> tags:

<context-param><param-name>cspApplication.dir</param-name><param-value>C:\Program Files\Crystal Decisions\Enterprise 10\Web Content</param-value></context-param>

<context-param><param-name>log.file</param-name><param-value>C:\Program Files\Crystal Decisions\Enterprise 10\Logging\wca</param-value></context-param>

Note: The values shown here are the default locations that the Crystal Enterprise setup program creates when you use the default installation directory for Crystal Enterprise.

4 Edit the value between the <display-name> </display-name> tags to edit the display name of your WCA. Use the format wcaname.wca. Changing the display name of your WCA is equivalent to changing the server name of the WCS in a Windows deployment of Crystal Enterprise.



5 Edit the connection.cms context parameter to edit the name of your Crystal Management Server. (Add the name of your CMS between the <param-value> </param-value> tags for this context parameter.)

6 Save web.xml, then reinsert the file into the WEB-INF directory within webcompadapter.war. Tip: To reinsert web.xml into WEB-INF using WinZip, right-click the WEB-INF directory that contains your edited web.xml file, and select “Add to Zip File...”. Adding the file in this way ensures that it is placed in the correct directory inside the archive.

7 Restart your application server and redeploy webcompadapter.war (for BEA WebLogic), or restart the application (for IBM WebSphere). The WCA should now use the new values from web.xml.

Deploying custom CSP applications To deploy your own custom CSP applications, place them in the crystal_root/webcontent directory (or other directory specified by the cspApplication.dir parameter in web.xml. See “Changing the default deployment values for the WCA” on page 62 for details.) This is the same directory that contains the Crystal Management Console.

Alternatively, you can deploy a second WCA, with a separate CSP deployment directory for your custom applications. See “Installing multiple Web Component Adapters” on page 63 for details.

Installing multiple Web Component AdaptersYou can install multiple Web Component Adapters (WCA) by deploying multiple instances of webcompadapter.war.

If you deploy each WCA on a separate Java application server, installing multiple WCAs is roughly equivalent to installing multiple Web Component Servers (in a Windows installation of Crystal Enterprise that uses the Crystal Enterprise COM SDK). If you deploy each WCA on the same Java application server, installing multiple WCAs is equivalent to creating multiple virtual directories for your web server (in a Windows installation of Crystal Enterprise that uses the Crystal Enterprise COM SDK). See “Configuring Web Connectors” on page 91 for more information.

When you install more than one WCA, each webcomponentadapter.war file contains its own web.xml file that contains configuration parameters for that WCA. However, you can only set the following parameters individually for each WCA:• cspApplication.defaultPage

• cspApplication.dir

• connection.cms

• connection.listenPort

• log.file



• log.ext

• log.isRolling

• log.size

• log.level

• log.entryPattern

The remaining parameters must be the same for all WCAs.

See “Changing the default deployment values for the WCA” on page 62 for information on changing the values in web.xml.


Installing Crystal Enterprise on UNIX 4

This chapter shows how to install Crystal Enterprise onUNIX. General system requirements are provided, as wellas procedures covering various installation scenarios.



Installation overviewCrystal Enterprise allows you to run all server components on a UNIX server. Users then connect to Crystal Enterprise over the Web with a supported web browser, such as Internet Explorer. The installation can place the necessary run control scripts in the relevant directories for automated startup (requires root privileges). Or you can confine the installation to a particular directory. Once you’ve finished the installation and setup procedures, the various server components run as daemons.

Once you have installed the Crystal Enterprise server components, you can deploy the Crystal Enterprise Launchpads (including the Crystal Enterprise web desktop), and the Web Component Adapter as web applications on your application server.

Before you run the interactive installation shell script (install.sh), it is strongly recommended that you read through the details and procedures provided in the rest of this chapter.

Crystal Enterprise on UNIX uses the Crystal Enterprise Java SDK with a Java web application server to deliver reports over the web. A Java version of the Crystal Enterprise web desktop and the Web Component Adapter (which supports legacy CSP applications, and the Crystal Management Console) combine to provide a complete suite of web based interfaces for users and administrators. Note that the use of a web server is optional; you may choose to use your application server to serve all your web content.

If you install the Crystal Enterprise server components on a UNIX machine, you can connect remotely to Crystal Enterprise with the Crystal Publishing Wizard and the Crystal Import Wizard. However, these client applications must be installed on Windows. For details, see “Client tools installation” on page 46.

System requirementsFor a detailed list of tested environments, please consult the Platforms.txt file included with your product distribution. This file includes specific version and patch-level requirements for web servers, application servers, web browsers, and operating systems. For additional important information that may pertain to your deployment, it is also strongly recommended that you consult the Release Notes included with your product distribution (release.pdf, release.htm, or release.rtf).

Generally, however, the following components must be installed and configured correctly before you install Crystal Enterprise:• Java J2SE SDK• Java application server• Database software that is compatible with the CMS• 256 MB RAM• 3 GB free disk space


4: Installing Crystal Enterprise on UNIX

Note: Crystal Enterprise requires a database to store information about the system and its users. For details, see “Setting up an empty database for the CMS” on page 68.

Setting up your UNIX systemCrystal Enterprise integrates with your existing database and web server software components, so the installation script needs to collect certain information about your current system. Because UNIX systems can vary significantly from site to site, the following sections detail the key tasks that you must perform prior to installing Crystal Enterprise.

Meeting the host name and network requirementsYour UNIX server must have a fixed host name before you run the installation script. You must have root privileges to set or modify this information on your system. If you are unfamiliar with these procedures, consult your UNIX system documentation.

When installing Crystal Enterprise on multiple machines, ensure that each target machine is able to communicate over TCP/IP with the machine that is running as your Crystal Management Server (CMS).

Note: If you are installing Crystal Enterprise in a firewall environment, you will need additional configuration details. See the “Working with Firewalls” section of the Crystal Enterprise Administrator’s Guide.

Checking for required commands and utilitiesIn order for the install.sh script to run correctly, the following commands and utilities must be installed on your UNIX system:

These relatively standard commands and utilities should be available on most UNIX distributions. However, if for any reason one of them is not available on your system, download and install a version appropriate to your UNIX system. It is recommended that you obtain any required files from your UNIX vendor.

Additionally, these commands and utilities must be accessible in the PATH environment variable of the user account that you use when installing Crystal Enterprise. For details, see “Creating an account, a home directory, and a login environment” on page 69.

/bin/sh pwd read touch

uname expr hostname sed

awk chown grep tail

tar id dirname gzip

stty ulimit which


Setting up your UNIX system

Setting the localeBefore you install Crystal Enterprise, set your operating system to use one of the locales that Crystal Enterprise 10 supports for your type and version of UNIX. Consult the platforms.txt file included with your product distribution for a complete list.

If you are working at the console of a UNIX machine, you can select your locale directly from the logon screen when you log on with the crystal account. However, to ensure that your operating system uses the correct locale whenever Crystal Enterprise runs, set the LC_ALL and LANG environment variables to your preferred locale in your login environment. (For example, if you are using a C shell, set these environment variables in the .login file.)

Tip: Type locale to check that all of the related locale environment variables (such as LC_MONETARY, LC_NUMERIC, etc.) were properly set by LC_ALL.

Note: The Windows terminal program does not support the use of UTF8 locales. Do not use a Windows terminal to telnet into your UNIX server if you choose a UTF8 locale.

See the section on International Deployments in the Crystal Enterprise Administrator’s Guide for information on deploying Crystal Enterprise for a multilingual, world-wide audience.

Setting up an empty database for the CMSCrystal Enterprise requires a database (or Oracle tablespace) to store information about the system and its users. Consequently, before you install Crystal Enterprise, you or your database administrator must create a new database on your database server. We strongly recommend that this database be used only for Crystal Enterprise, and not contain other tables.

The following database servers are supported on UNIX:• Oracle• DB2• Sybase

Note: See the Platforms.txt file included with your product distribution for a complete list of tested database software and version requirements.

It is recommended that you name the new database CEcms, create a new user account named crystal, and assign that user account a secure password. Ensure that the new account has permission to create, modify, and delete tables so that Crystal Enterprise can modify the CEcms database as required. You will need the name of the database, the user account, and the password when you run the Crystal Enterprise installation script.

During the installation process, the install script asks you if you want to reinitialize the database. During a new install, choosing this option causes the install script to



create new tables in the database to store Crystal Enterprise data. (In Oracle, choosing this option causes the install script to create Crystal Enterprise tables in the default tablespace of the user whose name you provided during the install.) During a reinstall of Crystal Enterprise, choosing this option causes the install script to reinitialize the tables containing Crystal Enterprise data, destroying any existing data. You must choose to reinitialize the database to proceed with the install. In either case, reinitializing the database does not affect any other tables in that database or tablespace.

(See “Upgrading, Migrating, and Importing” on page 125 for information on performing a Crystal Enterprise upgrade without overwriting existing data.)

Note: • Consult your database server documentation and/or your database

administrator if you are unsure of the procedure for creating a new database.• Ensure that your database server is set up to use Unicode character encoding

(such as UTF-8). Consult your database documentation to determine the settings required for a Unicode configuration. For database servers such as Oracle and Sybase, during installation you need to configure the server to use Unicode encoding for the character data types. For other databases, such as DB2 and Informix, you can create the CMS database with Unicode settings on your existing database server.

Creating an account, a home directory, and a login environmentCreate a specific user account and group under which the Crystal Enterprise daemons can run. You will log on as this user in order to perform the remainder of the installation procedures. Although you will require root privileges to set up this account, the account itself does not require root privileges. Neither the installation scripts nor Crystal Enterprise itself needs to run as root.

Use your usual administrative procedures to perform these recommended tasks.

To set up the crystal account1 Create a new group called crystal. Create a new user called crystal, and set

this user’s primary group to the new crystal group. Assign a secure password to the new user account.

2 Create the directory where you want to install Crystal Enterprise. These installation procedures use /usr/local/crystal as the installation directory. You can change /usr/local/crystal to the directory of your choice. If you do so, however, be sure to replace /usr/local/crystal throughout the installation procedures.

3 Set the new user’s HOME directory to the installation directory that you created. When you run the installation script, you can choose a “user” installation type so that all of the installed files are confined to the directory that you specify here.



4 Ensure that crystal has read, write, and execute permissions on the new HOME directory.

5 Assign the new user a default login shell, and create or modify the appropriate login script(s) for the crystal user account. In particular, make sure that the login script(s) set up a default login environment that meets these requirements:• The crystal user’s HOME directory must be included in the PATH environment

variable.• All of the commands and utilities required by the install.sh script must be

accessible in the PATH environment variable.For details, see “Checking for required commands and utilities” on page 67.

• The crystal user’s login environment must set up the database environment such that the install.sh script can access your database client software.

Providing and verifying connectivity to the CMS databaseTo create tables and write data to your new CEcms database, the installation scripts need to establish a connection to the database server. That is, when you log on to UNIX with the user name crystal to perform the installation, the default shell environment must include the appropriate database environment variables and/or initialization files. Only then can the installation script access the CEcms database using your database client software.

The environment variables and/or files required by the installation scripts depend upon the type of database server you are running:• If you choose to connect to Oracle through a native connection, the installation

searches the current shell for the ORACLE_HOME environment variable. This standard Oracle environment variable must be set in order for the setup.sh script to utilize the Oracle client software.

• If you choose to connect to DB2 through a native connection, the installation searches the current shell for the DB2INSTANCE environment variable. This standard DB2 environment variable must be set in order for the setup.sh script to utilize the DB2 client software.

• If you choose to connect to Sybase through a native connection, the installation searches the current shell for the SYBASE and SYBASE_OCS environment variables. These standard Sybase environment variables must be set in order for the setup.sh script to utilize the Sybase client software.

Additional database environment variables must be set in order for the installation script to use the database client software properly. Before running the installation script, test the shell environment of the new crystal user to verify database connectivity and privileges. See the procedure that corresponds to your database.



Note: Consult your database documentation and/or your database administrator if the crystal user’s shell environment has not yet been set up for your database client software, or if you are unable to connect successfully to the database.

To verify Oracle native connectivity through a TNS1 Log on to the UNIX server under the new crystal user account.

2 Echo the following environment variables and ensure that their values correspond to your database client software installation.

This example checks the required variables and shows sample output values.

$ echo $ORACLE_HOME/opt/oracle/817$ echo $LD_LIBRARY_PATH/opt/oracle/817/lib$ echo $PATH/usr/bin:/usr/ucb:/etc:.:/opt/oracle/817/bin

3 Issue the following command to run the Oracle SQL tool and connect to the appropriate service name:

sqlplus crystal/password@tnsname

Replace password and tnsname with the appropriate values. If the shell environment has been configured correctly, you are connected to Oracle.

4 Issue the following command to ensure that the crystal user account has permission to create tables:

create table sampletable (field1 char(10));

5 Issue the following command to ensure that the crystal user account has permission to delete tables:

drop table sampletable;

6 Type exit

Variable Value

ORACLE_HOME This variable contains the path to the root directory of your Oracle client installation (one level above the Oracle bin and lib directories).

library path The library search path (LD_LIBRARY_PATH on Solaris, LIBPATH on AIX, and so on) must include the lib directory of your Oracle client installation.

PATH The search path must include the bin directory of your Oracle client installation.



To verify DB2 native connectivity through a database alias1 Log on to the UNIX server under the new crystal user account.


This example checks the required variables and shows sample output values.

$ echo $DB2INSTANCEdb2inst1$ echo $DB2DIR/opt/IBMdb2/V7.1$ echo $LD_LIBRARY_PATH/export/home/db2inst1/sqllib/lib$ echo $PATH/usr/bin:/usr/ucb:/etc:.:/export/home/db2inst1/sqllib/adm:/export/home/db2inst1/sqllib/misc

3 Issue the following command to run the DB2 SQL tool:

db2

4 Issue the following command to connect to the desired database alias:

connect to db_alias user crystal using password

Replace db_alias and password with the appropriate values. If the shell environment has been configured correctly, you are connected to DB2.


create table sampletable (col_fld char(10) not null)


drop table sampletable

7 Type terminate

Variable Value

DB2INSTANCE This variable defines the current DB2 database instance.

DB2DIR This variable contains the path to the root directory of your DB2 installation (one level above the DB2 bin and lib directories).

library path The library search path (LD_LIBRARY_PATH on Solaris, LIBPATH on AIX, and so on) must include the lib directory of your DB2 client installation.

PATH The search path must include the bin directory of your DB2 client installation.



To verify Sybase native connectivity through a server name1 Log on to the UNIX server under the new crystal user account.


This example checks the required variables, and shows sample output values:

$ echo $SYBASE/opt/sybase/12.0$ echo $SYBASE_OCSOCS-12_O$ echo $LD_LIBRARY_PATH/export/home/sybase/12.0/OCS-12_0/lib$ echo $PATH/usr/bin:/usr/ucb:/etc:.:/export/home/sybase/12.0/OCS-12_0/bin

3 Issue the following command to run the Sybase SQL tool and connect to the database server:

isql -U user -P password -S servername

Replace user, password, and servername with the appropriate values. If the shell environment has been configured correctly, you are connected to Sybase.


use apsgocreate table sampletable (def_field char(10))gosp_help sampletablego

Variable Value

SYBASE This variable contains the path to the root directory of your Sybase client installation (one level above the SYBASE_OCS version directory).

SYBASE_OCS This variable contains the name of the Sybase version directory (one level above the Sybase bin and lib directories).

library path The library search path (LD_LIBRARY_PATH on Solaris, LIBPATH on AIX, and so on) must include the lib directory of your Sybase client installation.

PATH The search path must include the bin directory of your Sybase client installation.




drop table sampletablegosp_help sampletablego

6 Type quit

Installing the Java SDKIf your Java web application server does not install the Java SDK as part of its installation process, you must install the J2SE SDK first, before deploying the Crystal Enterprise Java SDK. You can download this software from java.sun.com.

Read the documentation on the Sun web site and select a version of the Java SDK that is compatible both with your application server and with the Crystal Enterprise Java SDK. Consult the Platforms.txt file included with your product distribution for more information.

Configuring the Java environment variableAfter installing the Java SDK you must set the JAVA_HOME environment variable. If your Java web application server installs the Java SDK as part of its installation process, install the application server first, and then set the environment variable.

You need to know the directory path containing your Java SDK bin directory.

To set the JAVA_HOME environment variable on UNIX1 Log on to the UNIX server under the new crystal user account.

2 Type setenv JAVA_HOME InstallDirectory (if you are using a C shell). Type JAVA_HOME= InstallDirectory (if you are using a Bourne shell).InstallDirectory is the directory containing your Java SDK bin directory.

3 To confirm that you’ve set the environment variable correctly, type echo $JAVA_HOME

4 Using a text editor such as vi, add the command to set JAVA_HOME to the login environment for the crystal user account. For example, if you are using a C shell, add the command to your .login file. This ensures that the value of JAVA_HOME is correctly set each time you log on to the crystal user account.



Running the installation scriptBefore following this procedure, ensure that you have set up your UNIX system appropriately. For details, see “Setting up your UNIX system” on page 67.

You can perform this installation remotely through a telnet session, or locally through a terminal window. Install Crystal Enterprise on the same machine where you installed the J2SE SDK. For details see “Installing the Java SDK” on page 74.

Installing the Crystal Enterprise files1 Log on to your UNIX system under the new crystal user account.

Note: For details on how to create this account, see “Creating an account, a home directory, and a login environment” on page 69.

2 Copy the install.sh script, the licensetext file (included with your product distribution), and the files containing the Crystal Enterprise binaries (with the extension .gz) from the full directory to your HOME directory.Note: If you transfer the .gz files by FTP to the UNIX machine, be sure to specify binary mode for the transfer.

3 Ensure that you are working in your HOME directory:

cd $HOME

4 Run the installation script:

./install.sh

5 When prompted, press Enter to continue.The script displays the product license agreement. Press the spacebar to read through the information in its entirety.

6 Press Enter, and then type yes and press Enter to accept the license agreement and to proceed with the installation.The script asks if you want to perform a system install or a user install. This procedure performs the user install. For details about the system option, see “Finishing a system installation” on page 77.

7 Type user and press Enter.The script prompts you for the absolute path of the installation directory.

8 Press Enter to accept the default, which is your current directory (equivalent to $HOME).The script creates a crystal directory below the directory that you specify here. The Crystal Enterprise subdirectories and files are installed below this crystal directory. The script next asks you if you would like to perform an upgrade install.


Running the installation script

9 Type no, and press Enter.The script notifies you that it has collected all of the required information, and asks you if you are ready to have the installation begin.

10 Type begin and press Enter.The installation script unpacks the archived installation files. This may take a few minutes. The install.sh script then calls postinstall.sh, which prompts you for the product activation keycode.

11 Type your product activation keycode and press Enter.The script validates your keycode and then runs the setup.sh script automatically.

Setting up the Crystal Enterprise servers1 When prompted, press Enter to continue with the setup portion of the script.

This section of the installation is actually provided by the setup.sh script, which is run automatically when the install.sh script finishes installing files. You can run this setup.sh script again independently at a later time if you choose to reconfigure Crystal Enterprise.

2 When prompted again, press Enter.The script asks you to select the desired setup type.

3 Type new and press Enter.

4 Specify the native database connection that the CMS must use to connect to the new CEcms database on your database server. The options are as follows:• Oracle• DB2• SybaseType your selection and press Enter. The script prompts you for the information that must be used for connecting to the CMS database. Note: If you encounter errors after making your selection, ensure that the crystal user account has access to the CMS database. For details, see “Setting up your UNIX system” on page 67.

5 Type the name of the empty CMS database that you created prior to running the installation script; then press Enter.Note: • For Oracle, enter the service name. For DB2, enter the database alias. For

Sybase, enter the database server name.• The database name that you enter here should be CEcms, so long as you

followed the naming convention suggested in “Setting up an empty database for the CMS”.

6 When prompted for a user name, type the user name for the account that you have provided with access to the CEcms database.



Note: The user name that you type here should be crystal, so long as you followed the naming convention suggested in “Setting up an empty database for the CMS”.

7 When prompted for a password, type the secure password that you assigned to the database user account.The script asks you for the port number of the CMS.

8 Press Enter to accept the default port, which is 6400. The setup script configures your new Crystal Enterprise system. The setup prompts you to reinitialize the CMS database. If you type yes, the CMS destroys the Crystal Enterprise tables in the CEcms database and recreates the database tables with fresh system data. Reinitializing the database does not affect any other tables in that database. You must type yes to proceed with the install.When finished, the script starts the servers as daemons and then enables each server (that is, each server is registered with the CMS). To control the servers manually, use the ccm.sh script. For preliminary details, see “Starting the Crystal Enterprise daemons with ccm.sh” on page 78.You must now deploy the Crystal Enterprise web desktop and the Crystal Enterprise Launchpads. See “Deploying the Crystal Enterprise web desktop” on page 81. For information on deploying the Web Component Adapter, including information on deploying multiple WCAs, see “Deploying the Web Component Adapter” on page 83.

Finishing a system installationIf you chose to perform a system installation, rather than a user installation, then the setup.sh script prompts you to run the setupinit.sh script, after setup.sh completes. The setupinit.sh script copies the run control scripts to your /etc/rc# directories. When implemented, these run control scripts start/stop the Crystal Enterprise servers on system startup/shutdown.

Note: You must have root privileges to run the system installation and/or the setupinit.sh script.

Running an expand installationThe Expand installation on UNIX is designed to set up a second set of Crystal Enterprise servers on a second machine. The Expand installation is similar to the user installation, but instead of recreating the CMS database, the installation allows you to cluster the new CMS with your current CMS. This means that the new CMS shares in the task of maintaining the system database. For complete information about adding servers to your installation and clustering CMS machines, see the Crystal Enterprise Administrator’s Guide.


Running the installation script

Running a silent installationA silent installation is one that you run from the command line to automatically install Crystal Enterprise on any machine in your system, without the installation program prompting for information during the installation. To install silently, run the silentinstall.sh script. This script contains parameters that provide information for installation settings and directory paths. By customizing the contents of the silentinstall.sh script, you can automatically install Crystal Enterprise silently on any machine in your system.

The silent installation is particularly useful when you need to perform multiple installations. You can also use the silent installation script in your own scripts. For example, if your organization uses scripts to install software on machines, you can add the silent Crystal Enterprise installation command to your scripts.

For information about each parameter, see the comments in the silentinstall.sh script.

Note: • Because the silentinstall.sh file is installed with Crystal Enterprise, you

cannot install silently the first time you install Crystal Enterprise.• The silent installation is not recommended for custom installations. The

installation options are simplified and do not allow for the same level of customization provided by the Crystal Enterprise install script program.

• Silent installations are not recommended for upgrades.• To install the Java application server on the same machine, see “Installing a

Java application server” on page 79. If your Java application server is installed on a different machine, see “Installing the Java application tier components” on page 80.

Starting the Crystal Enterprise daemons with ccm.shThe ccm.sh script provides you with a command-line interface to the various Crystal Enterprise server components. For more information about this script and others that are installed on your system, see the Crystal Enterprise Administrator’s Guide.

In Crystal Enterprise 10, the install.sh script starts and enables servers automatically. The following information is included for reference.

To manually start and enable the servers1 Go to the crystal directory that was created by the installation below your

HOME directory:

cd $HOME/crystal

2 Start all of the Crystal Enterprise servers as daemons:

./ccm.sh -start all



3 Enable all of the Crystal Enterprise servers. If you are using the default ports, type the following command:

./ccm.sh -enable all

If you are using a different port number for the CMS, issue the following command:

./ccm.sh -enable all -cms servername:portnumber

The daemons are now listening on the appropriate ports.

To view additional help on ccm.shThe ccm.sh script provides a detailed description of its command-line options. To see the help, issue the following command:

$HOME/crystal/ccm.sh -help | more

Installing a Java application serverBefore you can use the Crystal Enterprise web desktop, the Crystal Management Console, or your custom applications with Crystal Enterprise, you must install one of the supported Java application servers. Then you must install the Crystal Enterprise Java SDK and the Web Component Adapter on the same machine.

Make sure that your Java application server can communicate with the machine(s) that runs your Crystal Enterprise servers over TCP/IP. Alternatively, you can install your Java application server, Crystal Enterprise Java SDK, and all Crystal Enterprise servers on the same machine.

For a detailed list of tested Java application servers, consult the Platforms.txt file included with your product distribution.

Note: If you have a firewall between the machine running your Java application server and your other Crystal Enterprise servers, you must perform additional system configuration. See the section on how to configure firewalls, in your Crystal Enterprise Administrator’s Guide.

Follow the installation instructions that come with your Java web application server. Configure your application server to run the source env.sh command on startup. (The env.sh script is found in the root directory of your Crystal Enterprise installation.) This script sets a number of environment variables necessary for operation of Crystal Enterprise.

Once your server is installed and running, verify that the application server is running correctly by launching its default page, or administrative console in a web browser:• For Tomcat, type http://servername:8080/• For BEA WebLogic, type http://servername:7001/console• For IBM WebSphere 5, type http://servername:9090/admin


Installing the Java application tier components

Installing the Java application tier componentsThe Crystal Enterprise Java SDK and the Web Component Adapter must be installed on the machine that is running your Java web application server. These Java application tier components are installed as part of the full Crystal Enterprise installation. For details, see “Running the installation script” on page 75. If your Java application server is on the same machine as your Crystal Enterprise server components, then you can now deploy the Crystal Enterprise web desktop and the Crystal Enterprise Launchpads. See “Deploying the Crystal Enterprise web desktop” on page 81.

However, if the Java application server is on a different machine from the Crystal Enterprise components, you must ensure that the Java application tier components are installed on the Java web application server.

To install only the Java application tier components on a Java web application server, run the java_app_install.sh script on that machine. This script installs the Crystal Enterprise Java SDK and the Web Component Adapter (WCA), and configures the web archive file that implements the WCA (webcompadapter.war).

For information on installing the Java web application server, see “Installing a Java application server” on page 79. For information on deploying the Web Component Adapter, see “Deploying the Web Component Adapter” on page 83.

To install only the Java application tier components1 Copy the java_app_install.sh script, the licensetext file included with your

product distribution, and the files containing the Crystal Enterprise binaries (with the extension .gz) to your HOME directory.Note: If you transfer the files by FTP to the UNIX machine, be sure to specify binary mode for the transfer.


3 Press Enter, and then type yes and press Enter to accept the license agreement and to proceed with the installation.The script prompts you for the absolute path of the installation directory.

4 Type the path to the directory where you want to install the Crystal Enterprise Java application tier components.The script will create a crystal directory below the directory that you specify here. The Crystal Enterprise subdirectories and files are installed below this crystal directory.

5 Press Enter. The script notifies you that it has collected all of the required information, and asks you if you are ready to have the installation begin.



6 Type begin and press Enter.The installation script unpacks the archived installation files. This may take a few minutes. When finished, the script runs the webtiersetup.sh script automatically, and prompts you for the name of your Crystal Management Server (CMS).

7 Type the name of your CMS, and press Enter. The script will now prompt you for the port number that the Web Component Adapter should use to communicate with the CMS.

8 Press Enter to accept the default port, which is 6400.For information on deploying the Crystal Enterprise web desktop and the Crystal Enterprise Launchpads, see “Deploying the Crystal Enterprise web desktop” on page 81. For information on deploying the Web Component Adapter, including information on deploying multiple WCAs, see “Deploying the Web Component Adapter” on page 83.

Deploying the Crystal Enterprise web desktopTo deploy the Java version of the Crystal Enterprise web desktop, you must create virtual path mappings on your Java web application server. They map specific URLs to the web application archives (.war files) that implement the Crystal Enterprise User Launchpad and the Crystal Enterprise Admin Launchpad.

Once you have deployed the Launchpads and the Web Component Adapter, set the context path for the WCA in the Crystal Applications area of the Crystal Management Console. Setting the context path ensures that users can view reports using the Active X viewer and the Java viewer shipped with Crystal Enterprise.

To deploy the Crystal Enterprise Launchpads on Tomcat1 Shut down Tomcat if it is running. Type sh $CATALINA_HOME/bin/shutdown.sh

2 Open the file $CATALINA_HOME/conf/server.xml, in a text editor such as vi.


<Context path=”/crystal/enterprise10/adminlaunch”docBase=”crystal_root/enterprise/java/applications/admin.war”debug=”0” reloadable=”false”/>

<Context path=”/crystal/enterprise10/desktoplaunch”docBase=”crystal_root/enterprise/java/applications/desktop.war”debug=”0” reloadable=”false”/>

Substitute your Crystal Enterprise install directory for crystal_root

4 Save the file.

5 Restart Tomcat by typing sh $CATALINA_HOME/bin/startup.sh


Deploying the Crystal Enterprise web desktop

6 To test the Crystal Enterprise User Launchpad, open a web browser and type http://servername:8080/crystal/enterprise10/desktoplaunch in its address bar. For servername, substitute the name of the machine where you installed Tomcat.The Crystal Enterprise User Launchpad should start.


8 To test the Crystal Enterprise Admin Launchpad, open a web browser and type http://servername:8080/crystal/enterprise10/adminlaunch in its address bar. For servername, substitute the name of the machine where you installed Tomcat.The Crystal Enterprise Admin Launchpad opens. Do not click the link to the Crystal Management Console. You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 83 for instructions.


To deploy the Crystal Enterprise Launchpads on BEA WebLogic1 Open a web browser, and type http://servername:7001/console in its address

bar to open the BEA WebLogic Administrative Console. Substitute the name of the machine where you installed BEA WebLogic for servername. Note: By default, BEA WebLogic uses port 7001. If you configured your application server to use a different port number, substitute that port number in the URL.

2 Deploy the Crystal Enterprise User Launchpad as a new web application. Use the .war file found at crystal_root/enterprise/java/applications/desktop.war, and set the context root to /crystal/enterprise10/desktoplaunchNote: To set the context root for the web application, edit the Web Application Deployment Descriptor. [Click Edit Web Application Deployment Descriptors. Click WebApp Ext in the lefthand tree menu, then make your changes to the Context Root field. Click Apply].

3 To test that the Crystal Enterprise User Launchpad deploys correctly, type http://servername:7001/crystal/enterprise10/desktoplaunch in the address bar of a web browser. Click the Crystal Enterprise link to launch the application and test that desktop.war was deployed successfully.

4 Deploy the Crystal Enterprise Admin Launchpad as a new web application. Use the .war file found at crystal_root/enterprise/java/applications/admin.war, and set the context root to /crystal/enterprise10/adminlaunch



Do not click the link to the Crystal Management Console (CMC). You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 83 for instructions.


To deploy the Crystal Enterprise Launchpads on IBM WebSphere1 Start the IBM WebSphere Administrative Console. (http://servername:9090/

admin/).

2 Install the Crystal Enterprise User Launchpad as a new application. Use the .war file found at crystal_root/enterprise/java/applications/desktop.war, and set the context root to /crystal/enterprise/desktoplaunch


4 To test that the Crystal Enterprise User Launchpad deploys correctly, type http://servername:9080/crystal/enterprise10/desktoplaunch/launchpad.html in the address bar of a web browser. Click the Crystal Enterprise link to launch the application and test that desktop.war was deployed successfully.

5 Install the Crystal Enterprise Admin Launchpad as a new application. Use the .war file found at crystal_root/enterprise/java/applications/admin.war, and set the context root to /crystal/enterprise10/adminlaunch

6 Start the application.

7 To test that the Crystal Enterprise Admin Launchpad deploys correctly, type http://servername:9080/crystal/enterprise10/adminlaunch/launchpad.html in the address bar of a web browser. Do not click the link to the Crystal Management Console. You must configure the Web Component Adapter before the CMC can start. See “Deploying the Web Component Adapter” on page 83 for instructions.


Deploying the Web Component AdapterThe Web Component Adapter (WCA) is a Java web application that runs on your Web Application Server. The WCA hosts web components, including a CSP plug-in that allows you to run CSP applications on your Java Web Application Server. You must deploy the WCA to run the Crystal Management Console and CSP applications in a Java Crystal Enterprise environment.


Deploying the Web Component Adapter

The installation script configures the Web archive file that implements the WCA (webcompadapter.war) with specific information:• The name and location of your Crystal Management Server.• The default display name of the WCA.• The location of the directories where the WCA can find CSP applications.• The location it should use for log files.

In most situations you should not need to change these default values. If you do, see “Changing the default deployment values for the WCA” on page 86.

To deploy the WCA, you must first configure your Java web application server to source the env.sh script on startup, which sets a variety of environment variables used by Crystal Enterprise. (For details, see “Installing a Java application server” on page 79.) Then you must make cewcanative.jar available to your Java application server as a shared resource (either by placing cewcanative.jar in the application server’s shared lib directory, or by adding cewcanative.jar to the CLASSPATH environment variable. Consult your application server documentation for details.) Finally you must deploy the Web Component Adapter archive webcompadapter.war as a web application.

To deploy the WCA using Tomcat on UNIX1 Shut down Tomcat if it is running. Type $CATALINA_HOME\bin\shutdown in your

terminal window.

2 Copy the Java archive file cewcanative.jar (found in crystal_root/enterprise/java/applications) to $CATALINA_HOME/shared/lib Substitute the root directory of your Crystal Enterprise installation for crystal_root

3 Open the file $CATALINA_HOME/conf/server.xml, in a text editor such as vi.


<Context path=”/crystal”docBase=”crystal_root/enterprise/java/applications/webcompadapter.war”debug=”0” reloadable=”false”/>

where crystal_root is the root directory of your Crystal Enterprise installation.

5 Save the file.

6 Restart Tomcat by typing $CATALINA_HOME/bin/startup

7 To test the deployment of the WCA, launch the Crystal Management Console by typing http://servername:8080/crystal/enterprise10/admin in the address bar of a web browser. For servername, substitute the name of the machine where you installed Tomcat. If you chose to use a port number other than the default value, substitute that value for 8080.






11 Click Update.You can now view reports in the Crystal Enterprise web desktop using the Active X and Java viewers.

To deploy the WCA using BEA WebLogic on UNIX1 Make sure that your BEA WebLogic server is not running.

2 Edit your CLASSPATH environment variable to include crystal_root/enterprise/java/applications/cewcanative.jar

Substitute the root directory of your Crystal Enterprise installation for crystal_root

3 Start your BEA WebLogic server.

4 Open a web browser, and type http://servername:7001/console in its address bar to start the BEA WebLogic Administrative Console. For servername, substitute the name of the machine where you installed BEA WebLogic. If you use a port number other than the default value, substitute that value for 7001.

5 Deploy the Web Component Adapter as a new web application. Use the .war file found at crystal_root/enterprise/java/applications/webcompadapter.war, and set the context root to /crystal (for example, by changing the name of webcompadapter.war to crystal.war)Note: If the context root is not set to /crystal, the link to the Crystal Management Console from the Crystal Enterprise Admin Launchpad will not work.

6 To test that you have deployed the WCA correctly, launch the Crystal Management Console by opening a web browser and typing http://servername:7001/crystal/enterprise10/admin in its address bar. For servername, substitute the name of the machine where you installed BEA WebLogic. If you chose to use a port number other than the default value, substitute that value for 7001.







To deploy the WCA using IBM WebSphere on UNIX1 Make sure that your IBM WebSphere server is not running.

2 Edit your CLASSPATH environment variable to include crystal_root/enterprise/java/applications/cewcanative.jar


3 Start your IBM WebSphere Server, and launch the Administrative Console (at http://servername:9090/admin/). For servername, substitute the name of the machine where you installed IBM WebSphere. If you chose to use a port number other than the default value for the administrative console, substitute that value for 9090.

4 Deploy the Web Component Adapter as a new application. Use the .war file found at crystal_root/enterprise/java/applications/webcompadapter.war, and set the context root to /crystalNote: If the context root is not set to /crystal, the link to the Crystal Management Console from the Crystal Enterprise Admin Launchpad will not work.


6 To test that you have deployed the WCA correctly, launch the Crystal Management Console by opening a web browser and typing http://servername:9080/crystal/enterprise/admin/admin.cwr in its address bar. For servername, substitute the name of the machine where you installed IBM WebSphere. If you chose to use a port number other than the default value, substitute that value for 9080.





Changing the default deployment values for the WCAThe installation script configures the web archive file that implements the WCA (webcompadapter.war) with specific information:• The name and location of your Crystal Management Server.• The default display name of the WCA.• The location of the directories where the WCA can find CSP applications.• The location it should use for log files.



You may need to change some of these values to change the location of the WCA log files, if you want to deploy your custom CSP applications in a location other than the default directory, or if you plan to deploy multiple WCAs. To do so, edit the web.xml file contained in the WEB-INF directory of the archive.

Note: See “Installing multiple Web Component Adapters” on page 88 for further instructions before you install multiple WCAs.

To change the deployment values for the WCA1 Stop your Java application server, if it is running.

2 Extract web.xml from webcompadapter.war using the Java jar tool. Go to crystal_root/enterprise/java/applications, and type:

jar -xf webcompadapter.war WEB-INF/web.xml


3 Open web.xml using a text editor like vi.

4 To alter the values of cspApplication.dir (the directory for your CSP applications), log.file (the location of the log files created by the WCA), or connection.cms (the name and port number of your Crystal Management Server), edit the following lines to change the values between the <param-value></param-value> tags:

<context-param><param-name>cspApplication.dir</param-name><param-value>crystal_root/webcontent</param-value></context-param>

<context-param><param-name>log.file</param-name><param-value>crystal_root/logging/wca</param-value></context-param>

<context-param><param-name>connection.cms</param-name><param-value>servername:portnumber</param-value></context-param>

Note: Substitute the name of the server running your Crystal Management Server for servername, and its port number for portnumber.

5 Edit the value between the <display-name> </display-name> tags to edit the display name of your WCA. Changing the display name of your WCA is equivalent to changing the server name of the WCS in a Windows deployment of Crystal Enterprise.Use the format wcaname.wca

6 Save web.xml, then reinsert the file into the WEB-INF directory within webcompadapter.war. Type:

jar -uf webcompadapter.war WEB-INF/web.xml



7 Restart your application server and redeploy webcompadapter.war (for BEA WebLogic), or restart the application (for IBM WebSphere). The WCA should now use the new values from web.xml.

Deploying custom CSP applicationsTo deploy your own custom CSP applications, place them in the crystal_root/webcontent directory (or other directory specified by the cspApplication.dir parameter in web.xml. See “Changing the default deployment values for the WCA” on page 86 for details.) This is the same directory that contains the Crystal Management Console.

Alternatively, you can deploy a second WCA, with a separate CSP deployment directory for your custom applications. See “Installing multiple Web Component Adapters” on page 88 for details.

Installing multiple Web Component AdaptersYou can install multiple Web Component Adapters (WCA) by deploying multiple instances of webcompadapter.war.

If you deploy each WCA on a separate Java application server, installing multiple WCAs is roughly equivalent to installing multiple Web Component Servers (in a Windows installation of Crystal Enterprise that uses the Crystal Enterprise COM SDK). If you deploy each WCA on the same Java application server, installing multiple WCAs is equivalent to creating multiple virtual directories for your web server (in a Windows installation of Crystal Enterprise that uses the Crystal Enterprise COM SDK). See “Configuring Web Connectors” on page 91 for more information.

When you install more than one WCA, each webcompadapter.war file contains its own web.xml file that contains configuration parameters for that WCA. However, you can only set the following parameters individually for each WCA:• cspApplication.defaultPage

• cspApplication.dir

• connection.cms

• connection.listenPort

• log.file

• log.ext

• log.isRolling

• log.size

• log.level

• log.entryPattern

The remaining parameters must be the same for all WCAs.



Installing a Web Connector on a UNIX web serverThe default installation of Crystal Enterprise on Windows requires that you install a Web Connector on your web server to enable communications between the web server and the Web Component Server. You can install this web connector on either a Windows or a UNIX web server.

To install the Web Connector on a UNIX web server, run the install_webcon.sh script on that machine. This script installs the Web Connector, various configuration files, and all the Crystal Enterprise web content that is required by your web server.

Note: You do not need a Web Connector for a Crystal Enterprise installation (on UNIX or Windows) that uses the Crystal Enterprise Java SDK. The Java version of Crystal Enterprise uses a 3rd party Java application server, and does not install a Web Component Server.

On the web server machine, ensure that you have completed the preparatory steps described in the following sections:• “Meeting the host name and network requirements” on page 67• “Checking for required commands and utilities” on page 67

To install the Web Connector1 Copy the install_webcon.sh script, the licensetext file included with your

product distribution, and the files containing the Crystal Enterprise binaries (with the extension .gz) to your HOME directory.Note: If you transfer the files by FTP to the UNIX machine, be sure to specify binary mode for the transfer.


3 Press Enter, and then type yes and press Enter to accept the license agreement and to proceed with the installation.The script prompts you for the absolute path of the installation directory.

4 Type the path to the directory where you want to install the Web Connector and the web content files that are required by your web server.The script will create a crystal directory below the directory that you specify here. The Crystal Enterprise subdirectories and files are installed below this crystal directory.

5 Press Enter. The script notifies you that it has collected all of the required information, and asks you if you are ready to have the installation begin.


Installing a Web Connector on a UNIX web server

6 Type begin and press Enter.The installation script unpacks the archived installation files. This may take a few minutes. When finished, the script runs the webconsetup.sh script automatically, and prompts you for the port that the Web Connector should use to communicate with the Web Component Server (WCS).

7 Press Enter to accept the default port, which is 6401.The script asks if you want to connect to a web server on the local machine.

8 Type yes and press Enter.The script displays additional information. In particular, it shows the absolute path of the directory where it has saved the templates for your Web Connector configuration files. Note this directory, which should be $HOME/crystal/enterprise/PLATFORM_PATH/wcs/conf/

9 Press Enter to continue.The script prompts you for a list of WCS hosts.

10 Press Enter to accept the default.You must now configure your web server so it gives Crystal Enterprise requests to the Web Connector. For information on configuring the appropriate Web Connector for your web server, proceed now to “Configuring Web Connectors” on page 91.


Configuring Web Connectors 5

Web Connectors convert requests from your web serverinto a format that the Web Component Server canunderstand. This chapter focuses on configuring WebConnectors to work in conjunction with your web serversoftware.


What are Web Connectors?

What are Web Connectors?Web Connectors convert requests from your web server into a format the Web Component Server (WCS) can understand. The Web Connector must be installed on the machine that is running your web server software. This chapter explains the web server and Web Connector configuration that is required in order to provide effective communication between the web server and Crystal Enterprise on Windows.

You can install Web Connectors on web servers running on Windows or UNIX. However, you only need to install a Web Connector on UNIX when the UNIX web server must communicate with a WCS running on a Windows machine. When Crystal Enterprise itself is installed on UNIX, you do not need a Web Connector.

Note: There are a few other cases where a Web Connector is not required:• When you have deployed Java Crystal Enterprise components in your

Windows installation of Crystal Enterprise (as described in “Java component installation” on page 53), and your Windows installation of Crystal Enterprise does not include a WCS.

• When you have created an entirely customized ASP, ASPX, or JSP environment where your custom applications interface with the Crystal Enterprise SDKs, directly communicating with the framework and its components.

Path mapping overviewThis section explains the path mapping that occurs when you install Crystal Enterprise and configure Web Connectors on your web servers. On Windows, if you install the Web Connector on a machine that is running a supported web server, the setup program generally performs these mappings automatically as part of the installation process. On UNIX web servers, you must generally configure these mappings yourself. (See “Installing Web Connectors” on page 95 for more information).

When you integrate Crystal Enterprise with your existing web environment using Web Connectors, mapping occurs at several levels:• First, virtual directories on the web server are mapped to the Crystal

Enterprise “web content” and viewer directories on the web server machine. These mappings ensure that the web server can locate all HTML files, images, and viewer components that may be required by a Crystal Enterprise request.For details, see “Web server virtual directory mappings” on page 93.

• Second, Crystal Enterprise file types are mapped to the Web Connector, so the web server knows that those files require additional server-side processing. This application mapping ensures that the web server handles the relevant Crystal Enterprise file types differently to HTML and image files.For details, see “Web server application mappings” on page 94.


5: Configuring Web Connectors

• Third, a virtual path mapping is made in the Web Connector. This mapping ensures that the Web Component Server (WCS) is able to locate its own local copies of all relevant Crystal Enterprise files.Note: On Windows, this third mapping is typically required only when the Web Connector and the Web Component Server are installed on separate machines.For details, see “Web Connector virtual path mappings” on page 94.

The Web Connector installation and configuration steps described later in this chapter usually configure these mappings appropriately. Additional details to help you customize, modify, or troubleshoot your installation are provided in “Troubleshooting path mappings” on page 113.

Note: If a firewall separates your web server from the WCS or from other Crystal Enterprise components, you will need to make additional changes to your configuration. For details, see the section on working with firewalls in the Crystal Enterprise Administrator’s Guide.

Web server virtual directory mappingsYou create virtual directories on the web server in order to map URLs to actual directories on the web server machine. When you set up a virtual directory on your web server, you provide a name for the virtual directory along with the actual directory path of the corresponding HTML files, images, and so on. You typically define virtual directories with your web server’s administration tools and/or configuration files.

For Crystal Enterprise to function correctly, these virtual directories must be created on the web server:• The /crystal virtual directory• The viewer virtual directories

Note: For some UNIX web servers, Crystal Enterprise includes the appropriate web server directives in its default configuration files and templates. For complete details, see “Configuring UNIX Web Connectors” on page 104

For more information on web server virtual directory mappings, see “Web server virtual path mappings” on page 113.

The /crystal virtual directoryThe /crystal virtual directory must be mapped to the Crystal Enterprise web content directory on the web server machine. So, when a user requests a Crystal Enterprise web page, the HTML file and any associated images can be served up from the actual directory on the web server machine.

On a Windows web server, the default web content directory path is C:\Program Files\Crystal Decisions\Web Content; on a UNIX web server, it is /crystal_root/webcontent.


Path mapping overview

The viewer virtual directoriesThe /viewer and /crystalreportviewers10 virtual directories must be mapped to the Crystal Enterprise viewers directory on the web server machine. So, when a user requests a report from Crystal Enterprise, a Report Viewer (if required) can be served up from the actual directory on the web server machine. Although there must be two virtual directories on the web server, there is only one actual directory.

On a Windows web server, the default viewers directory path is C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10; on a UNIX web server, it is /crystal_root/viewers.

Web server application mappingsApplication mappings instruct your web server to pass certain file types to a particular program or module before returning any HTML to the user’s browser. In this way, application mappings ensure that server-side scripts and other special files are processed correctly.

Crystal Enterprise relies upon three application mappings—one for each Crystal Enterprise file type. Through these application mappings, you instruct the web server to pass all .csp, .cwr, and .cri requests to the Web Connector. The Web Connector then forwards the request to the Web Component Server, which communicates with the rest of Crystal Enterprise (as required) and generates the resultant HTML page.

For more information on web server application mappings, see “Web server application mappings” on page 114.

Web Connector virtual path mappingsCrystal Enterprise may require a third level of path mapping that establishes a virtual path between the Web Connector and the Web Component Server (WCS). Rather than passing entire files back and forth across the network, Crystal Enterprise increases overall efficiency and response time by duplicating its “web content” directory structure on both the web server and the WCS machines. For instance, when a user requests an HTML page that refers to ./logon.csp, the Web Connector does not send the logon.csp file across the network. Instead, the Web Connector instructs the WCS to evaluate its own local copy of the logon.csp file. The path to the logon.csp file on the web server may not match the absolute path to the corresponding logon.csp file on the WCS; therefore, the Web Connector uses a virtual path mapping in order to translate a path on the web server to an absolute path on the WCS.

The WCS must be able to locate its own local copy of each .csp file that it is asked to process. Thus, you must define virtual path mappings for .csp files (one virtual path mapping for the /crystal virtual directory, and one virtual path mapping for the /crystalreportviewers10 virtual directory).



Depending upon your web environment, you configure this virtual path mapping in the Web Connector or in your web server’s configuration files. On Windows, this virtual path mapping is typically required only when the Web Connector and the Web Component Server are installed on separate machines.

Note: • The WCS also responds to .cwr and .cri requests, but it generates these files

itself, so it does not have to find its own local copy first. In other words, the .cwr and .cri file types file types are handled by application mappings alone.

• If a firewall separates your web server from the WCS or from other Crystal Enterprise components, you will need to make additional changes to your configuration. For details, see the firewalls section in the Crystal Enterprise Administrator’s Guide.

For more information on Web Connector path mappings, see “Web Connector virtual path mappings” on page 118.

Installing Web ConnectorsFor full instructions on installing a Web Connector on your web server machine, see:• “To install the Web Connector on a Windows web server” on page 42• “Installing a Web Connector on a UNIX web server” on page 89

On WindowsWhen you install the Web Connector on a Windows machine that is running a supported web server, the Setup program configures your web server automatically. The Setup program creates virtual directories on the web server, and maps them to the Web Content and viewers directories of the Crystal Enterprise installation. The Setup program then configures application mappings on the web server, so all Crystal Enterprise requests (.csp, .cwr, and .cri file types) are passed to the appropriate Web Connector module.

If you installed the Windows Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101. If you want to use a CGI Web Connector with your Windows web server, you will have to perform some additional configuration steps manually. See “Configuring other supported CGI web servers” on page 99.

For more information, see “Configuring Windows Web Connectors” on page 96.


Configuring Windows Web Connectors

On UNIXWhen you install Web Connectors on a UNIX web server machine, several custom configuration files are generated in the following directories of your Web Connector installation:• /crystal_root/enterprise/platform/wcs/conf• /crystal_root/enterprise/platform/wcs/bin

Note: Throughout this chapter, the crystal_root value refers to the absolute path to the top-level crystal folder that was created by the installation on your web server machine. The platform value is specific to your operating system.

These custom configuration files are designed to help you configure the appropriate path mappings and application mappings for your web server.

See “Path mapping overview” on page 92 for details on the mappings that must be configured on your web server. Consult your web server documentation for more information about particular options that may be available.

For more information, see “Configuring UNIX Web Connectors” on page 104.

Note: • For a detailed list of tested environments, please consult the Platforms.txt file

included with your product distribution. This file includes specific version and Service Pack requirements for web servers, web browsers, databases, and operating systems. This file also lists the web server version requirements for each Web Connector.

• Additional information that is specific to your web server may be available from http://support.crystaldecisions.com/search, or consult the Crystal Enterprise 10 release notes.


Connecting Crystal Enterprise to IISWhen you install the Web Connector on a Windows machine that is running a supported version of Microsoft Internet Information Services (IIS), the Setup program configures your web server automatically.

The Setup program creates virtual directories on the web server, and maps them to the Web Content and viewers directories of the Crystal Enterprise installation. The Setup program then configures application mappings on the web server, so all Crystal Enterprise requests (.csp, .cwr, and .cri file types) are passed to the ISAPI Web Connector module. If you performed the full stand-alone installation, no additional configuration is required.

If you installed the Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101.



For information on the CGI web connector for IIS, see “Configuring other supported CGI web servers” on page 99.

Tip: For additional information about the virtual directories and mappings that are configured on your web server, see “Path mapping overview” on page 92. If necessary, consult your web server documentation for information on manually configuring these options.

Connecting Crystal Enterprise to Lotus DominoIf you are running Lotus Domino as your web server on Windows, you can choose between two different Web Connector technologies: DSAPI or CGI.

The CGI Web Connector for Domino is provided for systems where DSAPI modules are not implemented. This Web Connector works similarly to other CGI binaries. For details, see “Enabling the CGI Web Connector for Lotus Domino” on page 97.

Enabling the DSAPI Web ConnectorOn Windows, when you install the Web Connector on a machine that is running a Domino web server, the Setup program configures your web server automatically. The Setup program creates virtual directories on the web server, and maps them to the Web Content and viewers directories of the Crystal Enterprise installation. The Setup program then configures application mappings on the web server, so all Crystal Enterprise requests (.csp, .cwr, and .cri file types) are passed to the DSAPI Web Connector module. If you performed the full stand-alone installation, no additional configuration is required.

If you installed the Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101


Enabling the CGI Web Connector for Lotus DominoThis section shows how to configure Lotus Domino Server to use the CGI Web Connector.

The CGI configuration files are automatically generated with you install the Web Connector. On Windows, this is a manual process that involves copying the wcscgi.cgi to the Lotus Domino cgi-bin directory, and then configuring Domino to recognize the Crystal virtual directories, and to redirect Enterprise requests to the CGI binary (wcscgi.exe).

For more information about the CGI web connector, see “Configuring other supported CGI web servers” on page 111.



To configure the CGI Web Connector for Domino on WindowsConsult your Lotus Domino documentation for more information.

1 Copy wcscgi.cgi and wcscgi.exe (both found in C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\) to the Lotus Domino cgi-bin directory (usually C:\Lotus\Domino\Data\domino\cgi-bin).

2 Configure the Lotus Domino Administrator database to use the following virtual directories. Use the URL mapping:• /crystal must be mapped to C:\Program Files\Crystal Decisions\Enterprise

10\Web Content

• /viewer must be mapped to C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10

• /crystalreportviewers10 must be mapped to C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10

Note that the directory mappings are set to Read access, and not Execute.

3 Create an URL redirection entry in the Domino Administrator client to activate the CGI program wcscgi.exe.

4 Stop and restart your Domino http server.

Connecting Crystal Enterprise to iPlanetIf you are running iPlanet Enterprise Server as your web server, you can choose between two different Web Connector technologies: NSAPI or CGI.

The CGI Web Connector for iPlanet is provided for systems where NSAPI modules are not implemented. This Web Connector works similarly to other CGI binaries. For details, see “Configuring other supported CGI web servers” on page 99.

Enabling the NSAPI Web ConnectorOn Windows, when you install the Web Connector on a machine that is running an iPlanet web server, the Setup program configures your web server automatically. The Setup program creates virtual directories on the web server, and maps them to the Web Content and viewers directories of the Crystal Enterprise installation. The Setup program then configures application mappings on the web server, so all Crystal Enterprise requests (.csp, .cwr, and .cri file types) are passed to the NSAPI Web Connector module.

If you performed the full stand-alone installation, no additional configuration is required. If you installed the Windows Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101.

Tip: For additional information about the virtual directories and mappings that are configured on your web server, see “Path mapping overview” on page 92. If



necessary, consult your web server documentation for information on manually configuring these options.

Connecting Crystal Enterprise to the IBM HTTP ServerIf you are running the IBM HTTP Server as your web server, you can use the ASAPI Web Connector.

The ASAPI Web Connector is essentially an Apache Dynamic Shared Object (DSO). When started, Apache loads the ASAPI Web Connector module; this module handles all Crystal Enterprise requests and forwards them to the Web Component Server.

On Windows, when you install the Web Connector on a machine that is running an IBM HTTP web server, the Setup program configures your web server automatically. If you installed the Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101.


Configuring other supported CGI web serversThe CGI Web Connector allows you to connect Crystal Enterprise to web servers that support the Common Gateway Interface (CGI). Depending upon your web server, you typically configure CGI applications in one of two ways: either you specify a particular directory (the cgi-bin) as one that allows programs to execute commands or scripts, or you specify certain file types that are globally executable, regardless of the directory in which they are located. The default web applications provided with Crystal Enterprise—the Crystal Enterprise web desktop and the Crystal Management Console (CMC)—require the latter method.

In Crystal Enterprise, the actual CGI Web Connector program is wcscgi.cgi (also provided as wcscgi.exe on Windows). The program handles requests for .csp, .cwr, and .cri files. Consult your web server documentation to see how to specify certain file types as being globally executable by a particular interpreter; then associate all .csp, .cwr, and .cri files with the wcscgi.cgi script.

The Crystal Enterprise web desktop and the CMC do not contain all .csp, .cwr, and .cri files to a single cgi-bin directory. Therefore, these default applications will not function properly if your web server requires you to specify executable files by directory. In such cases, however, you can still deploy your own web applications that reference .csp scripts from the cgi-bin, so long as you map the Crystal Enterprise file types in the cgi-bin to the wcscgi.cgi script.



The CGI Web Connector is provided for use with web servers that support the CGI standard. The CGI connector obtains configuration information through environment variables. During installation, the setup script customizes the wcscgi.cgi script for your installation and saves the file in the following directory of your Web Connector installation:

C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86

This script sets up the environment variables and the library path and executes the connector binary.

To configure the CGI Web Connector on Windows1 Stop your web server.

2 If you do not already have a cgi-bin virtual directory set up on your web server, create one and map it to the actual directory where the wcscgi.cgi and wcscgi.exe files were installed (the default is C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86).Note: If you already have a cgi-bin virtual directory set up on your web server, or if your web server restricts your ability to map the cgi-bin to the actual win32_x86 directory, copy the wcscgi.cgi and wcscgi.exe files into the actual directory that is already mapped to the cgi-bin.

3 If you created a new cgi-bin virtual directory, ensure that it is marked as executable on the web server. You should also check that your file and directory permissions allow the wcscgi.cgi file to be executed when users make requests to the web server.

4 Configure the following virtual directories on your web server:• /crystal must be mapped to C:\Program Files\Crystal

Decisions\Enterprise 10\Web Content

• /viewer must be mapped to C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10

• /crystalreportviewers10 must be mapped to C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10

5 Restart your web server.

6 Ensure that the Crystal Enterprise servers are started and enabled.

7 Depending upon your web server configuration, you may not be able to access Crystal Enterprise and the Crystal Management Console from the links on the Crystal Enterprise Launchpads. For more information, see “Using Crystal Enterprise and the CMC with CGI” on page 101.



Note: If you performed the full stand-alone installation, no additional configuration is required. If you installed the Web Connector and the Web Component Server (WCS) on different machines, you must provide the Web Connector with information about the remote WCS. For details, see “Configuring the Web Connector for a remote WCS” on page 101.

Using Crystal Enterprise and the CMC with CGIOnce you have set up the CGI Web Connector, you can use Crystal Enterprise and the Crystal Management Console. However, you cannot access these applications from the links on the Crystal Enterprise Launchpads. Instead, for all requests, you must add cgi-bin/wcscgi.cgi to the URL, as demonstrated in the following examples.

Replace webserver with the name of your web server machine, and replace language with the information appropriate to your version of Crystal Enterprise: use en for English, fr for French, de for German, and ja for Japanese.

To log on to Crystal EnterpriseGo to the following URL:

http://webserver/cgi-bin/wcscgi.cgi/crystal/enterprise10/eportfolio/language/logon.csp

To log on to the CMCGo to the following URL:

http://webserver/cgi-bin/wcscgi.cgi/crystal/enterprise10/admin/language/admin.cwr

Configuring the Web Connector for a remote WCS If you installed the Web Connector and the Web Component Server (WCS) on different machines, follow these steps to provide the Web Connector with the information it requires in order to communicate with the remote WCS.

To configure the Web Connector for a remote WCS on Windows1 From the Crystal Enterprise program group, click Crystal Configuration

Manager.

2 In the CCM, click Configure web connector.The Web Connector Configuration dialog box appears.



3 In the Web Component Servers area, ensure that the WCS Host Name and Port number correspond to your system configuration.In the example above, the WCS is running on a machine named PBROWNSEYA, and it is listening on the default port (6401).

4 In the Path Mapping area, click Add.The Path Mapping dialog box appears.

5 In the Virtual Path field, type /crystalThis entry must match the name of your web server’s virtual directory that is mapped to the Crystal Enterprise web content directory on the web server. By default, this virtual directory is named /crystal.



6 In the Extension field, type .cspThis entry flags .csp files as exceptions, so the web server does not attempt to send the file directly to the user’s browser.

7 In the Actual Path field, type the absolute path of the Crystal Enterprise web content directory on the Web Component Server.This entry must specify the physical drive path on the Web Component Server, because this denotes the directory where the WCS will look for any .csp files that it must process.On Windows, the default web content directory path is:"C:\Program Files\Crystal Decisions\Enterprise 10\Web Content"Note: If the Actual Path contains spaces, enclose the string in double-quotes.

8 Click OK.Now, before it forwards .csp requests to the WCS, the Web Connector translates the path to the .csp file so that the WCS can locate the corresponding .csp file on its local drive.

9 In the Virtual Path field, type /crystalreportviewers10This entry must match the name of your web server’s virtual directory that is mapped to the Crystal Enterprise viewers directory on the web server. By default, this virtual directory is named /crystalreportviewers10.


11 In the Actual Path field, type the absolute path of the viewers directory on the Web Component Server.On Windows, the default viewer directory path is:

"C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10"

Note: If the Actual Path contains spaces, enclose the string in double-quotes.

12 Click OK.

13 Click OK and restart your web server and all associated services.

Note: • The CCM does not allow you to specify multiple actual paths for one virtual

directory. Consequently, when you are running more than one WCS machine, the actual path to your .csp files (and any other Crystal Enterprise file types) must be identical on each WCS machine.

• If you require additional information about the mappings that must be set up between the WCS and the Web Connector, see the “Troubleshooting Path Mapping” chapter of the Crystal Enterprise Administrator’s Guide.


Configuring UNIX Web Connectors


Connecting Crystal Enterprise to ApacheIf you are running Apache as your web server, you can choose between two different Web Connector technologies: ASAPI or CGI. When you installed the Web Connector, the setup script created configuration files that contain custom Apache configuration directives for both Web Connectors.

The ASAPI Web Connector is essentially an Apache Dynamic Shared Object (DSO). When started, the Apache daemon loads the ASAPI Web Connector module; this module handles all Crystal Enterprise requests and forwards them to the Web Component Server.

Apache takes its configuration information from Apache configuration directives, which are typically found in the httpd.conf file. During installation, the setup script creates a file called crystal/enterprise/platform/wcs/conf/asapi.conf, which contains custom Apache configuration directives for the ASAPI Web Connector. Use the Include command to include this file in your Apache httpd.conf file. This ensures that Apache loads the ASAPI Web Connector configuration automatically at startup.

For security reasons, these custom directives are only accessible from within the server’s .conf files. This prevents a user from re-directing the ASAPI Web Connector through an .htaccess file or other files defined by the AccessFileName directive.

On UNIX, you must enable the ASAPI Web Connector. For details, see “Enabling the ASAPI Web Connector” on page 104.

The CGI Web Connector for Apache is provided for systems where DSOs are not implemented. This Web Connector works similarly to other CGI binaries. For details, see “Enabling the CGI Web Connector for Apache” on page 106.

Enabling the ASAPI Web Connector Before configuring Apache to use the ASAPI Web Connector, ensure that your version of Apache supports DSOs. Note also that you can use a version of the Web Connector that uses the AP13 Apache API, or EAPI.

Follow the procedure for enabling the Web Connector by including the asapi.conf file in your web server’s httpd.conf file. The asapi.conf file was generated when you installed the Web Connector; it is located in the crystal/enterprise/platform/wcs/conf directory of your Web Connector installation.



To enable the ASAPI Web Connector1 On the web server machine, open the asapi.conf file from the crystal/

enterprise/platform/wcs/conf directory of your Web Connector installation.

2 By default, the AP13 API is selected in the asapi.conf file:

LoadModule wcs_connector_module crystal_root/enterprise/platform/wcs/lib/mod_wcs.ap13.so#LoadModule wcs_connector_module crystal_root/enterprise/platform/wcs/lib/mod_wcs.eapi.so

To select the EAPI Web Connector, place a # in front of the line specifying the AP13 API Web Connector, and remove the # at the beginning of the line specifying the EAPI web connector.

3 The WCSHosts directive indicates the list of WCS hosts to connect to. The WCSHosts directive should be followed by the full list of WCS hosts, and there should be only one WCSHosts directive per virtual server:

# List of WCS hosts to connect to.WCSHosts machinename:port machinename:port

Verify that the WCHosts list provides the name and port number for each of your WCS machines. The default port number for the WCS is 6401.

4 The Alias directives define the virtual directories that allow your web server to serve up Crystal Enterprise web content.

# Alias the crystal and viewer directoriesAlias /crystal /crystal_root/webcontentAlias /viewer /crystal_root/viewersAlias /crystalreportviewers10 /crystal_root/viewers

Ensure that /crystal_root/webcontent and /crystal_root/viewers point to the webcontent and viewers directories on your web server machine.Note: Alias directives are valid only if the mod_alias module is enabled on your installation of Apache. (This module is typically enabled at runtime, in the httpd.conf file.)

5 Ensure that the path mapping directives map the virtual directories on the web server to the actual Web Content and crystalreportviewers10 directories on your Windows WCS machine:

# Path MappingAddPathMap /crystal csp "C:\Program Files\Crystal Decisions\Enterprise 10\Web Content"AddPathMap /crystalreportviewers10 csp "C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10"

6 On the web server machine, open the Apache httpd.conf file in a text editor such as vi.



7 Add the following line to the file:

Include /crystal_root/enterprise/platform/wcs/conf/asapi.conf

8 Restart the Apache daemon using the command appropriate to the version that you are running.

9 Connect to Crystal Enterprise by opening your web browser and going to:


Here, the term webserver represents the name of the web server machine.Note: If mod_wcs.so does not match your version of Apache, you will see the following error message when you attempt to restart the server.

“API module structure ’wcs_connector_module’ in file mod_wcs.so is garbled - perhaps this is not an Apache module DSO?"

Enabling the CGI Web Connector for ApacheThis section shows how to configure Apache to use the CGI Web Connector. This configuration consists of including the cgi.apache.conf file in your web server’s httpd.conf file. The cgi.apache.conf file was generated when you installed the Web Connector; it is located in the crystal/enterprise/platform/wcs/conf directory of your Web Connector installation.

The configuration directives within the cgi.asapi.conf file ensure that Apache passes Crystal Enterprise scripting requests to the Web Connector. Additional directives set the ExecCGI option on the appropriate Crystal Enterprise directories and map the various virtual directories to the actual directories on the web server.

For more information about the CGI binary itself (wcscgi.bin), and the environment variables that are defined in its configuration script (wcscgi.cgi), see “Configuring other supported CGI web servers” on page 111.

To enable the CGI Web Connector for Apache1 On the web server machine, open the Apache httpd.conf file in a text editor

such as vi.

2 Add the following line to the file:

Include /crystal_root/enterprise/platform/wcs/conf/cgi.apache.conf

The cgi.apache.conf file uses the Alias directives, which are valid only if the mod_alias module is enabled on your installation of Apache. (This module is typically enabled at runtime, in the httpd.conf file.)

3 Restart the Apache daemon using the command appropriate to the version that you are running.

4 Connect to Crystal Enterprise by opening your web browser and going to:




Here, the term webserver represents the name of the web server machine. If you are unable to use the links on the Crystal Enterprise Launchpad, see “Troubleshooting path mappings” on page 113.

Connecting Crystal Enterprise to iPlanetIf you are running iPlanet Enterprise Server as your web server, you can choose between two different Web Connector technologies: NSAPI or CGI. When you installed the Web Connector, the setup script created configuration files that contain custom iPlanet configuration directives for both Web Connectors.

The NSAPI Web Connector works similarly to other NSAPI modules. When started, the iPlanet daemon loads the NSAPI Web Connector module; this module handles all Crystal Enterprise requests and forwards them to the Web Component Server.

On UNIX, you must enable the NSAPI Web Connector. For details, see “Enabling the NSAPI Web Connector on UNIX” on page 107.

The CGI Web Connector for iPlanet is provided for systems where NSAPI modules are not implemented. This Web Connector works similarly to other CGI binaries. For details, see “Enabling the CGI Web Connector for iPlanet on UNIX” on page 110.

Enabling the NSAPI Web Connector on UNIXWhen you install the Web Connector on a UNIX machine that is running a supported version of iPlanet Enterprise Server, the setup script generates the following configuration files that are customized for your installation of Crystal Enterprise:• mime.types.conf• obj.conf-ip7 (for iPlanet 7) or obj.conf-ip6 (for iPlanet 6)

These files are located in the crystal/enterprise/platform/wcs/conf directory of your Web Connector installation. Copy the information from these files into the appropriate iPlanet configuration files, as described in the following procedures.

Note: The iPlanet configuration files are usually located in the servers/https-servername/config directory of your iPlanet installation. Here, https-servername represents the name of the web server that you want to configure for use with Crystal Enterprise. The relevant iPlanet files differ, depending upon which version of iPlanet Enterprise Server you are running.

To enable the NSAPI Web Connector on UNIX1 On the web server machine, open the mime.types.conf file from the crystal/

enterprise/platform/wcs/conf directory of your Web Connector installation.The file contains the following lines:type=magnus-internal/csp exts=csptype=magnus-internal/cri exts=critype=magnus-internal/cwr exts=cwr



2 Copy these lines from mime.types.conf to the bottom of the iPlanet mime.types file.

3 Open the obj.conf-ip6 (for iPlanet 6), or obj.conf-ip7 (for iPlanet 7) from the crystal/enterprise/platform/wcs/conf directory of your Web Connector installation. Note the Service lines:

# Add to Service partService fn="req_handler" method="(GET|POST)" type="magnus-internal/csp"Service fn="req_handler" method="(GET|POST)" type="magnus-internal/cri"Service fn="req_handler" method="(GET|POST)" type="magnus-internal/cwr"

4 Add the Service lines to the <Object name="default"> section of the appropriate iPlanet configuration file, after any existing Service lines.The application mappings on your web server are now configured.Note: If you are running iPlanet Enterprise Server version 6, add these lines to the obj.conf file. If you are running iPlanet Enterprise Server version 7, add these lines to the servername-obj.conf file, where servername is the name that you gave to the server instance you created when you configured iPlanet 7.

5 Return to the wcs/conf/obj.conf-ip6 or obj.conf-ip7 file and note the customized Init lines (in this case, for iPlanet 6):

# Add to init part - IPlanet 6 uses nsapi with c4 flagInit fn="load-modules" funcs=req_handler,req_init shlib="/crystal_root/enterprise/platform/wcs/lib/libnsapi_c4.so"# For connecting to WCSInit fn="req_init" WCSHosts="WCSLIST" ClientPool="5" ConnectorTimeout="600000" WCSPathMap="/crystal;.cwr;webcontent,/crystal;.csp;webcontent,/crystal;.cri;webcontent,/crystalreportviewers10;.csp;viewers"

6 Verify that the WCSLIST value provides the name and port number for each of your WCS machines.If each WCS is listening on its default port (6401), you can enter just the machine names. If a WCS is listening on a different port, its entry must appear as machinename:portnumber. Separate multiple WCS entries with commas.

7 Verify that the webcontent value accurately reflects the actual location of the web content directory on your WCS machine(s).The default directory is:

C:/Program Files/Crystal Decisions/Enterprise 10/Web Content/

Note: • You must use forward slashes (/) when specifying directory paths in

iPlanet configuration files.• For iPlanet 7, directory paths cannot contain spaces. Consider moving the

Web Content directory on your WCS machines to C:/WebContent

8 Verify that the viewers value accurately reflects the actual location of the viewers directory on your WCS machine(s).



The default directory is:

C:/Program Files/Common Files/Crystal Decisions/2.5/crystalreportviewers10/

Note: • You must use forward slashes (/) when specifying directory paths in

iPlanet configuration files.• For iPlanet 7, directory paths cannot contain spaces. Consider moving the

viewers directory on your WCS machines to C:/crystalreportviewers10

9 Add the two Init lines to the appropriate configuration file. Add these lines immediately after any Init lines that are already in the iPlanet file. The Web Connector virtual path mappings are now configured.Note: • If you are running iPlanet Enterprise Server version 6, add these lines to the

magnus.conf file. If you are running iPlanet Enterprise Server version 7, add these lines to the init.conf file.

• If the Init fn="req_init" line is commented out, be sure to remove the preceding # symbol when you add the line to the iPlanet configuration file.

10 Return to the wcs/conf/obj.conf-ip6 or obj.conf-ip7 file and note the customized NameTrans lines that correspond to the following template:

# Add to NameTrans partNameTrans fn=pfx2dir from=/crystal dir="/crystal_root/webcontent"NameTrans fn=pfx2dir from=/viewer dir="/crystal_root/viewers"NameTrans fn=pfx2dir from=/crystalreportviewers10 dir="/crystal_root/viewers"

11 Add the NameTrans lines to the <Object name="default"> section of the appropriate iPlanet configuration file. Be sure to add these lines before the NameTrans fn="document-root" line.The web server virtual path mappings are now configured.Note: If you are running iPlanet Enterprise Server version 6.x, add these lines to the obj.conf file. If you are running iPlanet Enterprise Server version 7.x, add these lines to the servername-obj.conf file.

12 Return to the obj.conf-ip6 or obj.conf-ip7 file and note the <Object> section that corresponds to the following template:

# Add to the end of the file<Object ppath="/crystal_root/viewers/*.exe">ObjectType fn="force-type" type="application/octet-stream"Service fn="send-file"</Object>

13 Add the <Object> section to the end of the iPlanet 6 obj.conf file or the iPlanet 7 servername-obj.conf file. This code tells iPlanet where to find the Crystal report viewers.

14 Restart your iPlanet Enterprise Server.



15 Connect to the Crystal Enterprise User Launchpad by opening your web browser and going to:


Here, the term webserver represents the name of the web server machine.

Enabling the CGI Web Connector for iPlanet on UNIXThis section shows how to configure iPlanet Enterprise Server on UNIX to use the CGI Web Connector. This configuration consists of copying the contents of the cgi.netscape.conf file into the appropriate web server configuration files. The cgi.netscape.conf file was generated when you installed the Web Connector; it is located in the crystal/enterprise/platform/wcs/conf directory of your Web Connector installation.

Note: The iPlanet configuration files are usually located in the servers/https-servername/config directory of your iPlanet installation. Here, https-servername represents the name of the web server that you want to configure for use with Crystal Enterprise. The relevant iPlanet files differ, depending upon which version of iPlanet Enterprise Server you are running.

For more information about the CGI binary itself (wcscgi.bin), and the environment variables that are defined in its configuration script (wcscgi.cgi), see “Configuring other supported CGI web servers” on page 111.

To configure the CGI Web Connector for iPlanet1 On the web server machine, open the cgi.netscape.conf file from the crystal/

enterprise/platform/wcs/conf directory of your Web Connector installation.Note the following type lines:

#Add these lines to your mime.types filetype=magnus-internal/csp exts=csptype=magnus-internal/cri exts=critype=magnus-internal/cwr exts=cwr

2 Add these type lines to the bottom of the iPlanet mime.types file.

3 Ensure that the magnus.conf file (for iPlanet 6) or init.conf file (for iPlanet 7) contains the line:

Init fn="load-types" mime-types="mime.types"

4 Return to the cgi.netscape.conf file and note the customized NameTrans lines that correspond to the following template:

# Add to NameTrans partNameTrans fn=pfx2dir from=/crystal dir="/crystal_root/webcontent"NameTrans fn=pfx2dir from=/viewer dir="/crystal_root/viewers"NameTrans fn=pfx2dir from=/crystalreportviewers10 dir="/crystal_root/viewers"These lines map the web server virtual directories.



5 Add the NameTrans lines to the <Object name="default"> section of the iPlanet obj.conf file (for iPlanet 6) or servername-obj.conf (for iPlanet 7, where servername is the name that you gave to the server instance you created when you configured iPlanet 7).Be sure to add these lines before the NameTrans fn="document-root" line.

6 Return to the cgi.netscape.conf file and note the Service lines:

# Set the CGI handler for our mime typesService fn=query-handler path="/crystal_root/enterprise/platform/wcs/bin/wcscgi.cgi" type="magnus-internal/csp"Service fn=query-handler path="/crystal_root/enterprise/platform/wcs/bin/wcscgi.cgi" type="magnus-internal/cri"Service fn=query-handler path="/crystal_root/enterprise/platform/wcs/bin/wcscgi.cgi" type="magnus-internal/cwr"These lines map Crystal file types to the CGI Web Connector.

7 Add the Service lines to the <Object name="default"> section of the iPlanet obj.conf file (for iPlanet 6) or servername-obj.conf (for iPlanet 7) after any existing Service lines.

8 Restart your iPlanet Enterprise Server.

9 Connect to the Crystal Enterprise User Launchpad by opening your web browser and going to:


Here, the term webserver represents the name of the web server machine. If you are unable to use the links on the Crystal Enterprise Launchpad, see “Using Crystal Enterprise and the CMC with CGI” on page 112.

Configuring other supported CGI web serversThe CGI Web Connector allows you to connect Crystal Enterprise to web servers that support the Common Gateway Interface (CGI). Depending upon your web server, you typically configure CGI applications in one of two ways: either you specify a particular directory (the cgi-bin) as one that allows programs to execute commands or scripts, or you specify certain file types that are globally executable, regardless of the directory in which they are located. The default web applications provided with Crystal Enterprise—the Crystal Enterprise web desktop and the Crystal Management Console (CMC)—require the latter method.

In Crystal Enterprise, the actual CGI Web Connector program is wcscgi.cgi (also provided as wcscgi.exe on Windows). The program handle.s requests for .csp, .cwr, and .cri files. Consult your web server documentation to see how to specify certain file types as being globally executable by a particular interpreter; then associate all .csp, .cwr, and .cri files with the wcscgi.cgi script. (As far as the web server is concerned, the wcscgi.cgi script is the interpreter. However, on UNIX this script really serves as a wrapper that sets additional environment variables before passing the scripting request along to wcscgi.bin, which is the actual CGI Web Connector binary.)



The Crystal Enterprise web desktop and the CMC do not contain all .csp, .cwr, and .cri files to a single cgi-bin directory. Therefore, these default applications will not function properly if your web server requires you to specify executable files by directory. In such cases, however, you can still deploy your own web applications that reference .csp scripts from the cgi-bin, so long as you map the Crystal Enterprise file types in the cgi-bin to the wcscgi.cgi script.

The CGI Web Connector is provided for use with web servers that support the CGI standard. The CGI connector obtains configuration information through environment variables. During installation, the setup script customizes the wcscgi.cgi script for your installation and saves the file in the following directory of your Web Connector installation:/crystal_root/enterprise/platform/wcs/bin

This script sets up the environment variables and the library path and executes the connector binary.

On UNIX, when you install the Web Connector, the setup script generates additional Apache and iPlanet CGI configuration files and customizes them for your installation of Crystal Enterprise. For details, see “Enabling the CGI Web Connector for Apache” on page 106 and “Enabling the CGI Web Connector for iPlanet on UNIX” on page 110.

Note: See the Platforms.txt file included with your product distribution for a complete list of web servers that are officially supported for use with the CGI Web Connector. Using the CGI Web Connector with other web servers is neither recommended nor supported.

Using Crystal Enterprise and the CMC with CGIOnce you have set up the CGI Web Connector, you can use Crystal Enterprise and the Crystal Management Console. However, depending upon your web server configuration, you may not be able to access these applications from the links on the Crystal Enterprise Launchpads. You may need to add cgi-bin/wcscgi.cgi to the URL, as demonstrated in the following examples.


To log on to Crystal EnterpriseGo to the following URL:http://webserver/cgi-bin/wcscgi.cgi/crystal/enterprise10/eportfolio/language/logon.csp

To log on to the CMCGo to the following URL:http://webserver/cgi-bin/wcscgi.cgi/crystal/enterprise10/admin/language/admin.cwr



Troubleshooting path mappingsPath mappings are usually configured appropriately when you set up Crystal Enterprise, and install and configure the Web Connectors. This section provides additional details to help you customize, modify, or troubleshoot your installation.

For more information on path mappings, see “Path mapping overview” on page 92.

Web server virtual path mappingsVirtual directories on the web server are mapped to the Crystal Enterprise “web content” and viewer directories on the web server machine. These mappings ensure that the web server can locate all HTML files, images, and viewer components that may be required by a Crystal Enterprise request. For details, see “Web server virtual directory mappings” on page 93.

For information on configuring virtual path mappings, consult your web server documentation.

To check the /crystal virtual directory configuration• Type the entire Crystal Enterprise User Launchpad URL in your browser:

http://webserver/crystal/enterprise10/desktoplaunch/language/default.htm

Replace webserver with the name of your web server machine, and replace language with the information appropriate to your version of Crystal Enterprise: use en for English, fr for French, de for German, and ja for Japanese.If you cannot access this page, ensure that the /crystal virtual directory is configured correctly on your web server. For additional details on creating or editing virtual directories, see your web server documentation.

To check the configuration of the viewer virtual directories1 Go to the Crystal Enterprise User Launchpad at:

http://webserver/crystal/enterprise10/desktoplaunch/language/default.htm


2 Click the Crystal Offline Viewer link.You should be prompted to download the cvwsetup.exe file, which is located in the viewers directory of your Crystal Enterprise installation. If the web server cannot find this file, you may need to check the configuration of the /viewer virtual directory.For additional details on creating or editing virtual directories, see your web server documentation.


Troubleshooting path mappings

Web server application mappingsCrystal Enterprise file types are mapped to the Web Connector, so the web server knows that those files require additional server-side processing. This application mapping ensures that the web server handles the relevant Crystal Enterprise file types differently to HTML and image files. For details, see “Web server application mappings” on page 94.

Configuring application mappings on WindowsIf you use Microsoft Internet Information Services or iPlanet Enterprise Server as your web server, the Crystal Enterprise setup program typically configures the application mappings for your web server during the installation.

If you need to modify or to manually configure the application mappings, you must associate the Crystal Enterprise file types (.csp, .cwr, and .cri) with the Web Connector that is provided for your web server:• wcsisapi.dll (for Internet Information Services)• wcsnsapi.dll (for iPlanet Enterprise Server)• wcsdsapi.dll (for Lotus Domino)• wcscgi.cgi (provides a wrapper to wcscgi.exe for supported CGI-compatible

web servers).

After a default installation, the Web Connectors are located in the C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\ directory on your web server machine.

The exact procedure for adding application mappings under Windows depends on your operating system and your web server. Consult your web server documentation for more details. This example shows how you would add the appropriate application mappings to Internet Information Services 5.0 running on Windows 2000.

To add application mappings to IIS 5.0 on Windows 20001 On the Start menu, point to Administrative Tools and, on the submenu, click

Internet Services Manager.

2 Select Default Web Site (or the web site you are using), and on the Action menu, click Properties.



3 In the Properties dialog box, click the Home Directory tab.

4 In the Application Settings area, click Configuration.The Application Configuration dialog box appears.



5 On the App Mappings tab, look in the Extension list for the .csp, .cwr, and .cri entries. These entries are typically created by the Crystal Enterprise setup program.

6 If the entries are not there, or if you need to modify an existing entry, click Add or Edit.The Add/Edit Application Extension Mapping dialog box appears.

7 In the Executable field, type the absolute path to the ISAPI Web Connector. The default path is:

C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\wcsisapi.dll

8 In the Extension field, type .csp

9 Select All Verbs.

10 Select the Script engine check box.

11 Clear the Check that file exists check box.

12 Click OK.

13 Repeat steps 6 to 12 for .cwr and .cri files.

14 Return to the Internet Services Manager and restart your web server.

Configuring application mappings on UNIXThe configuration entries that affect application mappings depend upon both the type of web server and the type of Web Connector that you are using.

Apache (ASAPI Web Connector)

If you are using Apache with the ASAPI Web Connector, the application mappings are made with the AddHandler directive.

Ensure that the following line appears in the asapi.conf file (so long as you used the Include command in your httpd.conf file to reference the Crystal Enterprise asapi.conf file, as outlined in “Enabling the ASAPI Web Connector” on page 104):

AddHandler wcs_connector_handler cri cwr csp



This line instructs Apache to pass all requests for Crystal Enterprise file types to the ASAPI Web Connector.

iPlanet Enterprise Server (NSAPI Web Connector)

If you are using iPlanet Enterprise Server with the NSAPI Web Connector, the application mappings are made with the req_handler function.

Ensure that the following lines appear in the <Object name="default"> section of the iPlanet 6 obj.conf file (or iPlanet 7 servername-obj.conf file), after any existing Service lines:Service fn="req_handler" method="(GET|POST)" type="magnus-internal/csp"Service fn="req_handler" method="(GET|POST)" type="magnus-internal/cri"Service fn="req_handler" method="(GET|POST)" type="magnus-internal/cwr"

Also ensure that the following lines appear in the iPlanet mime.types file:type=magnus-internal/csp exts=csptype=magnus-internal/cri exts=critype=magnus-internal/cwr exts=cwr

Together, these configuration entries serve to define the Crystal Enterprise file types and to allow the NSAPI Web Connector to handle requests for such files.

Supported web servers with the CGI Web Connector

Depending upon your web server, you typically configure CGI application mappings in one of two ways: either you specify a particular directory (the cgi-bin) as one that contains all scripts that are executable by the CGI interpreter, or you specify certain file types that are always executable by the CGI interpreter, regardless of the directory in which they are located. The default web applications provided with Crystal Enterprise—the Crystal Enterprise web desktop and the Crystal Management Console (CMC)—require the latter method.

Consult your web server documentation to see how to specify certain file types as being globally executable by a particular interpreter; then associate all .csp, .cwr, and .cri files with the wcscgi.cgi script. (As far as the web server is concerned, the wcscgi.cgi script is the interpreter. However, this script really serves as a wrapper that sets additional environment variables before passing the scripting request along to wcscgi.bin, which is the actual CGI Web Connector binary.)

Note: The Crystal Enterprise web desktop and the CMC do not contain all .csp, .cwr, and .cri files to a single cgi-bin directory. Therefore, these default applications will not function properly if your web server requires you to specify executable files by directory. In such cases, however, you can still deploy your own web applications that reference .csp scripts from the cgi-bin, so long as you map the Crystal Enterprise file types in the cgi-bin to the wcscgi.cgi script.



Web Connector virtual path mappingsA virtual path mapping is made in the Web Connector. This mapping ensures that the Web Component Server (WCS) is able to locate its own local copies of all relevant Crystal Enterprise files.

Note: On Windows, this third mapping is typically required only when the Web Connector and the Web Component Server are installed on separate machines.

For details, see “Web Connector virtual path mappings” on page 94.

Checking Web connector virtual path mappings

To check the Web Connector virtual path mappings1 Type the following URL in your browser:

http://webserver/crystal/enterprise10/eportfolio/default.htm

If you are successfully redirected to the Crystal Enterprise web desktop or its logon page, then the path mapping between the Web Connector and the WCS is configured to process .csp files properly for the /crystal virtual directory.If the redirection is unsuccessful, you should check not only the virtual path mappings, but also the configuration of the virtual directory and of the application mappings on your web server.

2 Type the following URL in your browser:

http://webserver/crystalreportviewers10/crystalimagehandler.csp

If you receive a blank web page (and not a web server error), then the path mapping between the Web Connector and the WCS is configured to process .csp files properly for the /crystalreportviewers10 virtual directory.If you receive a web server error (404 or other), you should check not only the virtual path mappings, but also the configuration of the virtual directory and of the application mappings on your web server.

Configuring virtual path mappings on WindowsIf Crystal Enterprise is running on Windows, you can use the Crystal Configuration Manager (CCM) to configure the virtual path mappings for the Web Connector.

To create a virtual path1 From the Crystal Enterprise program group, click Crystal Configuration

Manager.

2 In the CCM, click Configure web connector.



The Web Connector Configuration dialog box appears.

3 In the Web Component Servers area, ensure that the WCS Host Name and Port number correspond to your system configuration.In the example above, the WCS is running on a machine named PBROWNSEYA, and it is listening on the default port (6401).

4 In the Path Mapping area, click Add.The Path Mapping dialog box appears.

5 In the Virtual Path field, type /crystalThis entry must match the name of your web server’s virtual directory that is mapped to the Crystal Enterprise web content directory on the web server. By default, this virtual directory is named /crystal.




7 In the Actual Path field, type the absolute path of the Crystal Enterprise web content directory on the Web Component Server.This entry must specify the physical drive path on the Web Component Server, because this denotes the directory where the WCS will look for any .csp files that it must process.On Windows, the default web content directory path is:"C:\Program Files\Crystal Decisions\Enterprise 10\Web Content"Note: If the Actual Path contains spaces, enclose the string in double-quotes.

8 Click OK.Now, before it forwards .csp requests to the WCS, the Web Connector translates the path to the .csp file so that the WCS can locate the corresponding .csp file on its local drive.

9 In the Virtual Path field, type /crystalreportviewers10This entry must match the name of your web server’s virtual directory that is mapped to the Crystal Enterprise viewers directory on the web server. By default, this virtual directory is named /crystalreportviewers10.


11 In the Actual Path field, type the absolute path of the viewers directory on the Web Component Server.On Windows, the default viewer directory path is:

"C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10"

Note: If the Actual Path contains spaces, enclose the string in double-quotes.

12 Click OK and restart your web server and all associated services.

Note: The CCM does not allow you to specify multiple actual paths for one virtual directory. Consequently, when you are running more than one WCS machine, the actual path to your .csp files (and any other Crystal Enterprise file types) must be identical on each WCS machine.

Configuring virtual path mappings on UNIXThe configuration entries that affect your virtual path mappings depend upon both the type of web server and the type of Web Connector that you are using.



Apache (ASAPI Web Connector)

If you are using Apache with the ASAPI Web Connector, the virtual path mapping is made in the asapi.conf file (so long as you used the Include command in your httpd.conf file to reference the Crystal Enterprise asapi.conf file, as outlined in “Enabling the ASAPI Web Connector” on page 104).

The relevant lines are as follows:• WCSHosts WCSLIST

This line defines the Web Component Server(s) that the ASAPI module must communicate with. WCSLIST is a list of one or more WCS hosts, specified as machinename:portnumber (separate multiple entries with spaces).Note: There can be only one WCSHosts directive per virtual server.

• AddPathMap /crystal csp "webcontent"This line defines how the ASAPI module translates file paths for each Crystal Server Page (.csp file) that is requested from the /crystal virtual directory structure on the web server.Any .csp request made to http://webserver/crystal must be mapped relative to the web content directory on the WCS. The virtual directory on the web server is specified first (/crystal); the file extension is specified second (csp); and the absolute path of the Crystal Enterprise web content directory on the Web Component Server is specified last (webcontent).The default webcontent value is:

C:\Program Files\Crystal Decisions\Enterprise 10\Web Content

• AddPathMap /crystalreportviewers10 csp "viewers"This line defines how the ASAPI module translates file paths for each Crystal Server Page (.csp file) that is requested from the /crystalreportviewers10 virtual directory structure on the web server.Any .csp request made to http://webserver/crystalreportviewers must be mapped relative to the viewers directory on the WCS. The virtual directory on the web server is specified first (/crystalreportviewers10); the file extension is specified second (csp); and the absolute path of the viewers directory on the Web Component Server is specified last (viewers).The default viewers value is:

C:\Program Files\Common Files\Crystal Decisions\2.5\crystalreportviewers10

Note: Additional Path Mapping configuration can be done through the AddPathMap directive. There can be many AddPathMap directives in your Apache configuration. These must be separated by a space (rather than by a semicolon in the case of CGI).

You must instruct Apache to reinitialize its child worker processes after you modify WCSHosts entries in the Web Connector configuration files. You can generally do this with one of the following commands:

kill -HUP `cat <absolute path to httpd.pid file>`kill -USR1 `cat <absolute path to httpd.pid file>`

Consult the Apache documentation for more information.



iPlanet Enterprise Server (NSAPI Web Connector)

If you are using iPlanet Enterprise Server 6 with the NSAPI Connector, the virtual path mapping is made in the Init line of the iPlanet magnus.conf file. If you are using iPlanet Enterprise Server 7 with the NSAPI Connector, the virtual path mapping is made in the Init line of the iPlanet init.conf file. In either case, ensure that the following line appears:Init fn="req_init" WCSHosts="WCSLIST" ClientPool="5" ConnectorTimeout="600000" WCSPathMap="/crystal;.cwr;webcontent,/crystal;.csp;webcontent,/crystal;.cri;webcontent,/crystalreportviewers10;.csp;viewers"

This Init line provides the NSAPI Web Connector module with the instructions necessary for mapping paths correctly. The relevant portions can be broken down as follows:• WCSHosts="WCSLIST"

This line defines the Web Component Server(s) that the NSAPI module must communicate with. WCSLIST is a list of one or more WCS hosts, specified as machinename:portnumber (separate multiple entries with commas).

• WCSPathMap="/crystal;.csp;webcontent,..."The WCSPathMap command maps paths from the web server to the WCS based on file type. The portion quoted here defines how the NSAPI module translates file paths for each Crystal Server Page (.csp file) that is requested from the /crystal virtual directory structure on the web server.Any .csp request made to http://webserver/crystal must be mapped relative to the web content directory on the WCS. The virtual directory on the web server is specified first (/crystal); the file extension is specified second (.csp); and the absolute path of the Crystal Enterprise web content directory on the Web Component Server is specified last (webcontent).The default webcontent value is:


• /crystalreportviewers10;.csp;viewers"This final portion of the WCSPathMap command translates file paths for each Crystal Server Page (.csp file) that is requested from the /crystalreportviewers10 virtual directory structure on the web server.Any .csp request made to http://webserver/crystalreportviewers10 must be mapped relative to the viewers directory on the WCS. The virtual directory on the web server is specified first (/crystalreportviewers10); the file extension is specified second (csp); and the absolute path of the viewers directory on the Web Component Server is specified last (viewers).The default viewers value is:


Note: The entries for each mapped file type are separated by commas, but all entries are contained within double-quotes.



Supported web servers with the CGI Web Connector

If you are using the CGI Web Connector, the virtual path mapping is made in the wcscgi.cgi script, regardless of the type of web server you are running.

The relevant lines in the wcscgi.cgi script are as follows:

First, ensure that the following line appears in the wcscgi.cgi script:• WCSHOST1=machinename:portnumber; export WCSHOST1;

This line sets the WCSHOST1 environment variable, which specifies the host machine that is running the Web Component Server (WCS). Replace machinename with the fully qualified domain name (or IP address) of the machine that is running the WCS. Replace portnumber with the port that the WCS is listening on (by default, this is port 6401). You may specify additional WCS machines by defining similar environment variables with names WCSHOST2, WCSHOST3, and so on if you are load-balancing over two Web Component Servers, for example.

Second, ensure that the following lines appears in the wcscgi.cgi script:• WCSPATHMAP1="/crystal;csp;webcontent"; export WCSPATHMAP1

This line defines how the CGI Web Connector handles a request for a Crystal Server Page (.csp files) that is requested from the /crystal virtual directory structure on the web server. Any .csp request made to http://webserver/crystal must be mapped relative to the web content directory on the WCS. The virtual directory on the web server is specified first (/crystal); the file extension is specified second (csp); and the absolute path of the Crystal Enterprise web content directory on the Web Component Server is specified last (webcontent).The default webcontent value is:


• WCSPATHMAP2="/crystalreportviewers10;csp;viewers"; export WCSPATHMAP2This line defines how the CGI Web Connector translates file paths for each Crystal Server Page (.csp file) that is requested from the /crystalreportviewers10 virtual directory structure on the web server.Any .csp request made to http://webserver/crystalreportviewers10 must be mapped relative to the viewers directory on the WCS. The virtual directory on the web server is specified first (/crystalreportviewers10); the file extension is specified second (csp); and the absolute path of the viewers directory on the Web Component Server is specified last (viewers).The default viewers value is:


To map different paths or different file extensions, add a new environment variable with the prefix “WCSPATHMAP”.


Upgrading, Migrating, and Importing 6

This chapter shows how to upgrade Crystal Enterprise,migrate system data, and import content from earlierreleases of Crystal Enterprise and Info.


Upgrading overview

Upgrading overviewThis chapter describes the process of upgrading Crystal Enterprise, migrating system data, and importing content from earlier releases of Crystal Enterprise and Info. Upgrading consists of replacing existing Crystal Enterprise programs and files with the latest versions; migrating consists of copying data from your old Automated Process Scheduler (APS) database to a new Crystal Management Server (CMS) database, while at the same time updating the database schema to the latest version; importing consists of copying objects (reports, users, groups, and so on) and instances from one system to another. This chapter presupposes knowledge of Crystal Enterprise and its architecture, in addition to familiarity with your current deployment.

Several options are available to you, depending upon your current system and your preferred method of upgrading:• Upgrade an earlier version of Crystal Enterprise directly and migrate its

system data into a new CMS database.In this scenario, you first upgrade the existing APS and migrate its system database; then you upgrade all other Crystal Enterprise components before bringing the system back online. For details, see “Upgrading earlier versions of Crystal Enterprise” on page 127.

• Set up a new Crystal Enterprise system alongside your original system, and then migrate old system data into the new CMS database.In this scenario, you need additional hardware for the new Crystal Enterprise system. When the new system is ready, you migrate your original APS database so it becomes the CMS database for the new system, and you ensure that the new Input and Output File Repository Servers can access the root directories that were used by the older system. For details, see “Migrating system data from earlier versions” on page 129.

• Set up a new Crystal Enterprise system, and then import content from an existing Crystal Enterprise or Info system. Again, this scenario requires additional hardware for the new Crystal Enterprise system. Instead of migrating an existing database, you selectively import content (user accounts, groups, folders, reports, and so on) into the new system. For details, see “Importing content from Crystal Enterprise or Info” on page 129.

Note: Before proceeding with any upgrade or migration, see “Before upgrading or migrating” on page 126.

If you require further assistance in upgrading particularly large-scale and/or mission-critical deployments, or in migrating customized reporting applications, it is recommended that you contact a Crystal Services consultant, who can then assess your reporting environment and assist in the upgrade and migration process.


6: Upgrading, Migrating, and Importing

Before upgrading or migratingIt is expected that you will follow your usual administrative practices before upgrading Crystal Enterprise or migrating system data from earlier product releases. However, you should also consider the following common tasks and guidelines that are particularly relevant to Crystal Enterprise deployments:• For further information that may pertain to your reporting environment,

consult the Release Notes included with your product distribution (release.pdf, release.htm, or release.rtf).

• Disable and subsequently stop all Crystal Enterprise components before upgrading any components.

• Stop the web servers and/or web application servers that are configured for use with Crystal Enterprise.

• Ensure that you have details about the database server and accounts that are used for the existing system database and that will be used by the new system database. For more information, see “Setting up the CMS database” on page 31.

• Back up your existing system database and the root directories used by the Input and Output File Repository Servers.

• Back up any custom web applications, HTML pages, or scripts that you have added to Crystal Enterprise.

• Log on as an administrator of any machine upon which you install or upgrade Crystal Enterprise components.

• Close any other programs that are running locally before you start the Crystal Enterprise setup program.

• Because the upgrade requires you to migrate your existing APS database to the latest format, ensure that you first upgrade an APS machine, so you can immediately create a new CMS database and then migrate system data from the old APS database.

• If you’re upgrading a UNIX installation, it is important to note that the UNIX version of Crystal Enterprise 10 uses your existing Java web application server. A Java web application server must be installed and configured before you can use Crystal Enterprise on UNIX. For more information about configuring Crystal Enterprise components to work with your Java web application server, see “Installing Crystal Enterprise on UNIX” on page 65.

Upgrading earlier versions of Crystal EnterpriseWhen run on machines that have older Crystal Enterprise components installed, the setup program recognizes and updates existing Crystal Enterprise files. The setup program is designed to accommodate direct upgrades from versions 8.0, 8.5, and 9 of both Crystal Enterprise and the Report Application Server.

Because the upgrade requires you to migrate your existing APS database to the latest format, ensure that you first upgrade an APS machine, so you can immediately create a new CMS database and then migrate system data from the old APS database.


Upgrading earlier versions of Crystal Enterprise

Note: Silent installations are not recommended for upgrading. Although you can use a silent installation to add components to a machine, using it to replace existing components is not recommended. Alternatively, you can uninstall the existing components and then install the new ones using the silent installation.

To upgrade an earlier version of Crystal Enterprise1 Disable and subsequently stop all Crystal Enterprise servers.

2 Run the Crystal Enterprise setup program on your APS machine (or one of your APS machines, if you have an APS cluster).The setup program detects your earlier version of Crystal Enterprise and leads you through the upgrade process and the creation of a new CMS database. Follow the instructions on your screen when you are prompted to specify the database server and credentials that you want the CMS to use for its new system database. For more information about the CMS database, see “Setting up the CMS database” on page 31.When the setup program has finished upgrading components, you are prompted to migrate system data from the old database to the new one.

3 Use the Specify Data Source dialog box (in the Crystal Configuration Manager) to copy data from the original database into the newly created CMS database.This dialog box allows you to specify the source database (the original database) whose contents are to be copied into the destination database (the newly created CMS database). For complete details on migrating databases, see the Crystal Enterprise Administrator’s Guide.Note: At the end of the database migration, you may be prompted to update certain report objects. You cannot complete this step until the File Repository Servers have been upgraded and Crystal Enterprise is back online. Therefore, you must postpone this step until you have finished upgrading components.

4 Run the setup program on all other machines that are running older Crystal Enterprise components.When you upgrade components, the setup program does not install any new components that did not exist previously on your machine. For instance, if you are upgrading from version 8.0 of Crystal Enterprise, the Event Server is not automatically installed. Or, if you were not running an earlier version of the Report Application Server (RAS), then the new RAS is not automatically installed. After you upgrade all existing components, you can run the Crystal Enterprise setup program again to modify your installation and add these additional server components. Alternatively, you can run the Crystal Enterprise setup program on a new machine to install these additional server components.


6: Upgrading, Migrating, and Importing

5 When you have upgraded all components, use the Crystal Configuration Manager to start the CMS that you first upgraded.

6 Start and subsequently enable all remaining Crystal Enterprise servers.

7 You can now return to the Crystal Configuration Manager on the CMS machine that you first upgraded and click Update Objects on the toolbar.Objects that require updating are typically report files whose properties differ from those of their database representations. (In particular, reports with alerts will need certain properties added to the new CMS database.) Follow the instructions on your screen to update objects as required.

Migrating system data from earlier versionsIf you install a new Crystal Enterprise system alongside your original installation, you can subsequently use the latest version of the Crystal Configuration Manager to migrate system data from the old APS database into the new CMS database. In addition, you will need to provide the newly installed File Repository Servers with access to the root directories used by the File Repository Servers in the old Crystal Enterprise system.

For complete details, see the Crystal Enterprise Administrator’s Guide.

Importing content from Crystal Enterprise or InfoThe Crystal Import Wizard allows you to selectively import objects and instances from an existing Crystal Enterprise or Info system to a newly installed Crystal Enterprise system. Run the Crystal Import Wizard from the Crystal Enterprise 9 program group.

Tip: Because the Crystal Enterprise setup program cannot directly upgrade Info systems to Crystal Enterprise, the Crystal Import Wizard is the tool to use if you are copying Info user accounts, groups, folders, and reports into a new Crystal Enterprise system.

For more information on the Crystal Import Wizard, see its online help or the Crystal Enterprise Administrator’s Guide.

Note: To import Repository objects from Crystal Enterprise 9 into a newly installed Crystal Enterprise system, use the Crystal Repository Wizard.


Upgrading other Crystal components

Upgrading other Crystal components

Upgrading the Report Application ServerThe upgrade scenario for the Report Application Server varies, depending upon your original installation:• If are running a RAS (version 8.x) that is already integrated with Crystal

Enterprise (version 8.x), then you can upgrade the RAS to the latest version directly, by running the Crystal Enterprise setup program on the RAS machine. For details, see “Upgrading earlier versions of Crystal Enterprise” on page 127.

• If you are running the standalone version of the RAS that is included with Crystal Reports 9, it is recommended that you migrate your applications to the integrated version of the RAS that is installed with this latest release of Crystal Enterprise, because the Crystal Enterprise setup program upgrades your standalone version of the RAS.

Note: To create and modify reports over the Web through the Report Application Server, be sure to enter your additional licence key(s) in the Authorization management area of the Crystal Management Console.

Upgrading Crystal ReportsThis release of Crystal Enterprise includes an updated version of Crystal Reports. Run the Crystal Reports setup program to directly upgrade existing versions of Crystal Reports.

Upgrading Crystal AnalysisVersions 8.5 and earlier of Crystal Analysis are not supported for use with this release of Crystal Enterprise. Contact your Crystal Decisions sales representative for information about obtaining an updated version of Crystal Analysis.


Custom SDK Deployments 7

This chapter details the various SDKs that are includedwith Crystal Enterprise. It also provides deploymentguidelines for different SDK environments.


Software Development Kit overview

Software Development Kit overviewBy default, if you have a version of Crystal Enterprise that includes developer components, the Crystal Enterprise Software Development Kits (SDKs) are installed and configured when you install Crystal Enterprise. (The Crystal Enterprise .NET SDK will be installed only if you already have the .NET Framework installed on your machine.) After you install Crystal Enterprise, all of the Crystal Enterprise servers are enabled and running by default. You can implement custom web applications using Crystal Server Pages (CSP), Active Server Pages (ASP), ASP.NET (ASPX), and Java Server Pages (JSP).

The following Application Programming Interfaces (APIs), along with developer documentation, are included with Crystal Enterprise:• Crystal Enterprise COM and Java interfaces• Report Application Server COM and Java interfaces• Report Viewer COM and Java interfaces• .NET assemblies

Note: • Report Application Server supports COM and Java viewer SDKs. In addition,

however, the Report Application Server includes its own Software Development Kit (SDK) for report-creation and modification, thereby providing you with tools for building your own web-based reporting and query tools. Your Crystal Enterprise license key determines whether or not the report-creation SDK and the Crystal Enterprise web desktop integration features are available to you.

• Refer to the Release Notes and the Platforms.txt on your product distribution for information on limitations, system requirements, and so on.

• For developer-specific information, see the developer documentation available on your product CD.

Crystal Server Pages environmentCrystal Enterprise supports web applications that are implemented using Crystal Server Pages (CSP). CSP is similar to Active Server Pages (ASP), but is specific to Crystal Enterprise and is processed by the Web Component Server. Both CSP and ASP drive the COM SDKs. Crystal Enterprise includes applications such as the Crystal Enterprise web desktop and the Advanced DHTML viewer that are written in CSP.

On Windows, if you are processing scripts with the Web Component Server that ships with Crystal Enterprise, you must create your web applications using CSP; however, if you are using a web server such as Microsoft Internet Information Server (IIS), you will want to develop your Crystal Enterprise web applications using ASP.

If you are running the Java version of Crystal Enterprise (on UNIX or Windows), you can use the Web Component Adapter to run legacy web applications written in CSP. It is not recommended that you develop new applications in CSP if you are using the Java platform.


7: Custom SDK Deployments

Active Server Pages environmentCrystal Enterprise supports web applications that are implemented using Active Server Pages (ASP). Both CSP and ASP drive the COM SDKs. Crystal Enterprise installs the necessary files so that Internet Information Server (IIS) can process the ASP files.

Java Server Pages environmentCrystal Enterprise supports web applications that are implemented using Java Server Pages (JSP).

On UNIX, Crystal Enterprise uses the Crystal Enterprise Java SDK and includes a version of the Crystal Enterprise web desktop written in JSP. It uses a Java web application called the Web Component Adapter to run legacy CSP applications. On Windows, you can optionally install the Crystal Enterprise Java SDK and deploy the JSP version of the Crystal Enterprise web desktop.

Before you run any of your applications that are implemented using JSP, ensure that you have deployed these to the appropriate folder for the web application server you are using. For more information on deploying WAR and JAR files, consult “Installing Crystal Enterprise on UNIX” on page 65, or “Java component installation” on page 53, and the documentation that is specific to your web application server.

.NET environmentIn order to use .NET assemblies, you must set up your development machine and web server to be able to run a reporting application using .NET.

To create .NET applications to view or modify Enterprise reports, or to use the Crystal Reports .NET report viewers to view a SOAP report web service, you need to install Visual Studio .NET, Crystal Reports, Crystal Enterprise, and Report Application Server. Crystal Reports enhances VS .NET by adding Crystal Reports features to the Visual Studio .NET IDE. Therefore, you must install your .NET products before you install Crystal Reports, or you must run the Crystal Reports installation program again after you install a .NET product.

In general, follow this installation order for setting up your development machine:• Ensure Internet Information Server (IIS) 5 or higher is installed if you intend to

host web applications on your development machine.Note: If you are installing on Windows NT 4, you will not be able to create web applications on your machine’s IIS web server; you will need to point to a Windows 2000 Server or Windows .NET Server machine when creating web applications in Visual Studio .NET. See the Visual Studio .NET documentation for more details.

• Install Visual Studio .NET or the .NET Framework.


.NET environment

• Install any optional .NET tools such as Visual J# or the .NET mobile controls.• Install Crystal Reports.• Install Crystal Enterprise.

Note: The Crystal Enterprise .NET assemblies and the .NET Server Components will be installed on your machine if: • You perform a default installation of Crystal Enterprise on a machine that

has Visual Studio .NET or the .NET Framework installed.• You perform a Custom installation on a machine that has Visual Studio

.NET or the .NET Framework installed, and select “Crystal Enterprise .NET SDK” from the Developer Components listed in the Select Features dialog.

If you install Crystal Enterprise before installing a .NET product, you must install one and then run the Setup program again.

For a web server to run a reporting application using Crystal Enterprise for .NET, the web server must be running the .NET Framework and provide access to the Crystal Enterprise .NET libraries.


Uninstalling 8

This chapter tells you how to uninstall Crystal Enterprise.


Uninstalling Crystal Enterprise from Windows

Uninstalling Crystal Enterprise from WindowsIf Crystal Enterprise was set up with the default Microsoft Data Engine (MSDE) database, then removing Crystal Enterprise will not remove the MSDE. For details, see “Uninstalling MSDE” on page 136.

Stop your web server before uninstalling Crystal Enterprise. Then disable and stop all Crystal Enterprise servers. If you want to save reports and system information, backup the root directories used by the Input and Output File Repository Servers and backup the CMS database. Before restarting your web server, manually remove any changes that you made to your web server’s configuration files when you set up Crystal Enterprise.

To remove Crystal Enterprise from Windows 20001 In Windows, click Start, point to Settings, and then select Control Panel.

2 Double-click Add/Remove Programs.

3 Select Crystal Enterprise and click Remove.The Add/Remove Programs dialog box prompts you to confirm that you want to remove Crystal Enterprise from your computer.

4 Click Yes.Please wait while the appropriate files are removed and the necessary configuration is carried out.

5 Click Finish.Crystal Enterprise has been uninstalled and you are returned to the Add/Remove Program Properties dialog box.

Uninstalling MSDEBecause the Microsoft Data Engine (MSDE) is not a Crystal application, it has its own uninstall program. If you no longer want the CMS system data contained in the database, and if you hadn’t previously installed MSDE for another use, you can remove it.

Note: The MSDE service must be stopped before the application can be removed.

To stop MSDE1 Click Start, point to Programs, point to MSDE, and then select Service

Manager.

2 Select each running service from the Services list box and click Stop.

3 Close the SQL Server Service Manager dialog box.Note: If the MSDE Service Manager appears on your Windows status bar, right-click it and then click Exit.


8: Uninstalling

To remove MSDE1 Click Start, point to Programs, point to MSDE, and then select Uninstall MSDE.

2 Click Yes to remove MSDE and all of its components.Please wait while the unInstallShield program removes MSDE.

3 Click OK to exit.

Uninstalling Crystal Enterprise from UNIXThe uninstallCE.sh script is installed to the crystal directory of your installation. This script deletes all of the files installed during your original installation of Crystal Enterprise by running the scripts in the crystal/uninstall directory. Do not run the scripts in the uninstall directory yourself: each of these scripts removes only the files associated with a single Crystal Enterprise component, which may leave your Crystal Enterprise system in an indeterminate state.

Before running this script, you must disable and stop all of the Crystal Enterprise servers. If you are uninstalling a Web Connector, you should stop your web server, because the Web Connector modules and related files will be deleted.

If you performed the “system” installation type, you will also need to delete the run control scripts from the appropriate /etc/rc# directories.

Note: • When you uninstall a Web Connector, you must manually remove any

changes that you made to your web server’s configuration files when you set up Crystal Enterprise. Failure to remove these changes may result in web server errors, because the uninstall.sh script deletes the Web Connector modules and configuration files that your web server loads when it starts. Thus, you should remove these entries manually before restarting the web server. If someone else in your organization installed and set up Crystal Enterprise, see the Crystal Enterprise Installation Guide for details about the Web Connector entries for your web server.

• The uninstallCE.sh script will not remove files created during the installation process, or files created by the system or by users after installation. To remove these files, after running installCE.sh, perform an rm -Rf command on the crystal directory.


Uninstalling Crystal Enterprise from UNIX


Index

AAddPathMap directive ............................................ 121Apache................................................................... 104

application mappings on UNIX ........................ 116configuration directives.................................... 121reinitializing child processes ............................ 121virtual paths on UNIX ...................................... 121

application mappings ............................................... 94application server

choosing ............................................................ 11WCA.................................................................. 12WCS .................................................................. 11

ASAPI Web Connector............................................ 104asapi.conf ............................................................... 121audience, intended..................................................... 2automated startup on UNIX ...................................... 77

Bbutton conventions ..................................................... 5

Cccm.sh...................................................................... 78CGI

application mappingson UNIX...................................................... 117on Windows................................................ 114

virtual path mappingson UNIX...................................................... 123on Windows................................................ 118

CGI Web Connectoron UNIX .......................................................... 111on Windows ...................................................... 99using the web desktop and the CMC ........ 101, 112

choosingapplication servers ............................................. 11CMS database servers........................................... 9web development environments ........................ 12web servers ........................................................ 10

client tools, installing................................................ 46CMC, using with CGI...................................... 101, 112CMS database........................................................... 31

migrating............................................................ 31on UNIX ............................................................ 70setting up on UNIX ............................................ 68

command conventions ............................................... 5commands required on UNIX................................... 67

Common Gateway Interface. See CGIcomponents, selecting individually on Windows...... 47configuring

Crystal Enterprise, after install ............................ 23UNIX Web Connectors and web servers ............ 91wcscgi.cgi on UNIX....................................99, 111Web Connectors

virtual path mappings ................................... 94web servers

application mappings.................................... 94virtual directories .......................................... 93

.cri files, application mappings................................. 94Crystal Enterprise Java SDK

Windows installation ......................................... 53Crystal Enterprise web desktop, using with CGI...... 112Crystal Import Wizard .............................................. 46Crystal Management Console. See CMCCrystal Publishing Wizard ...................................46, 66crystal virtual directory............................................. 93crystal_root directory................................................ 96crystalreportviewers virtual directory........................ 94.csp files, application mappings................................ 94custom installation, on Windows ............................. 47.cwr files, application mappings ............................... 94

Ddaemons, starting with ccm.sh ................................. 78data

choosing live/saved............................................ 26live .................................................................... 26saved ................................................................. 26

database, CMS ....................................................31, 68DB2 ....................................................................68, 70directives, ASAPI Web Connector .......................... 121directories

crystal_root ........................................................ 96platform............................................................. 96virtual ................................................................ 93

distributingWeb Connector and WCS................................ 101Web Connector on a UNIX machine ................. 89

DSAPI Web Connector............................................. 97DSO....................................................................... 104dynamic shared objects. See DSO


EEAPI ........................................................................104enabling

ASAPI Web Connector on UNIX.......................104CGI for Apache on UNIX..................................106CGI for iPlanet on UNIX...................................110CGI Web Connector on UNIX ..........................111CGI Web Connector on Windows ......................99NSAPI Web Connector on UNIX ......................107servers with ccm.sh ............................................78

environmentcommands and utilities.......................................67database ....................................................... 68, 70login...................................................................69

Expand installationon UNIX.............................................................77on Windows.......................................................43

Ffax numbers, registration.............................................3firewalls .............................................................. 33, 67

Hhelp

product registration ..............................................3technical support..................................................4

IIBM HTTP Server ......................................................99importing content during an upgrade ......................129installation scenarios, overview ................................15installation script, on UNIX.......................................75installing

client tools..........................................................46on UNIX....................................................... 66, 75on Windows.......................................................30SDKs ................................................................132UNIX install script ..............................................75Web Connectors on UNIX..................................89Web Connectors on Windows............................42

install.sh ............................................................. 66, 75Internet Information Services (IIS)

application mappings .......................................114Web Connector ..................................................96

iPlanet Enterprise ServerUNIX.......................................................... 98, 107

application mappings ..................................117virtual paths.................................................122

Windowsapplication mappings ..................................114virtual paths.................................................118

ISAPI Web Connector ...............................................96

JJava application server, installing........................ 55, 79Java application tier components, installing .............. 53Java components

installing on UNIX ............................................. 80installing on Windows ....................................... 53

java_app_install.sh ................................................... 80

Kkey combinations ....................................................... 5keyboard shortcuts...................................................... 5

Llive data.................................................................... 26locale, setting on UNIX............................................. 68login environment .................................................... 69Lotus Domino........................................................... 97

Mmappings

application......................................................... 94virtual directories ............................................... 93Web Connector virtual paths.............................. 94

Microsoft SQL Server ................................................ 31migrating CMS database ........................................... 31migrating system data during an upgrade................ 129minimum requirements

UNIX ................................................................. 66Windows ........................................................... 31

MSDE ....................................................................... 31installing Crystal Enterprise without.................... 48stopping ........................................................... 136uninstalling ...................................................... 136

NNSAPI Web Connector ............................................. 98

Ooptimizing, for report viewing................................... 20Oracle ................................................................ 68, 70

Ppath mapping ........................................................... 92planning

to maximize data sharing ................................... 20to optimize report viewing ................................. 20your Crystal Enterprise installation ....................... 8

platform directory ..................................................... 96product registration..................................................... 3

Rregistration.................................................................. 3report viewing, optimizing for................................... 20


requirementsUNIX ................................................................. 66Windows ........................................................... 31

Ssaved data ................................................................ 26SDK

COM ............................................................... 132Java ................................................................. 133.NET ................................................................ 133overview.......................................................... 132

selectingapplication servers ............................................. 11CMS database servers .......................................... 9web development environments ........................ 12web servers........................................................ 10

servers starting with ccm.sh...................................... 78server-side installation, Windows ............................. 37setupinit.sh............................................................... 77shortcuts, keyboard .................................................... 5silent installation

on UNIX ............................................................ 78on Windows ...................................................... 51

stand-alone installation, Windows............................ 33stopping MSDE....................................................... 136support

product registration.............................................. 3technical.............................................................. 4web site ............................................................... 4

Sybase.................................................................68, 70system installation on UNIX ..................................... 77system requirements

UNIX ................................................................. 66Windows ........................................................... 31

Ttechnical support........................................................ 4telnet........................................................................ 75troubleshooting

application mappings ...................................... 114web connector virtual paths............................. 118Web Connectors .............................................. 113web server virtual paths ................................... 113

UUnicode .................................................... 8, 32, 68, 69uninstalling

from UNIX....................................................... 137from Windows................................................. 136MSDE .............................................................. 136

UNIXcreating login environment ................................ 69host name requirements..................................... 67network requirements ........................................ 67required commands and utilities ........................ 67

running installation script ...................................75setting the locale ................................................68setting up your system ........................................67

UNIX web serversapplication mappings .......................................116configuring virtual paths ...................................120installing Web Connectors..................................89

upgradingconsiderations ..................................................127Crystal Analysis ................................................130Crystal Enterprise..............................................127Crystal Reports .................................................130importing content .............................................129migrating system data .......................................129overview ..........................................................126Report Application Server.................................130

Vviewer virtual directory .............................................94virtual directories ......................................................93

crystal.................................................................93crystalreportviewers............................................94viewer ................................................................94

virtual path mappings, for Web Connector................94

WWCA

changing deployment values ........................ 62, 86deploying on UNIX ............................................83deploying on Windows ......................................58installing multiple......................................... 63, 88installing on UNIX..............................................80installing on Windows........................................53

WCS, connecting to remote Web Connector...........101wcscgi.cgi and wcscgi.bin ................................ 99, 111WCSHosts

Apache.............................................................121CGI Web Connector.........................................123NSAPI Web Connector .....................................122

WCSPathMapCGI Web Connector.........................................123NSAPI Web Connector .....................................122

Web Component Adapter. See WCAWeb Connectors

and remote Web Component Servers ...............101application mappings .........................................94CGI virtual paths ..............................................123described............................................................92installing

on UNIX........................................................89on Windows..................................................42

on UNIX web servers........................................104on Windows web servers....................................96virtual path mappings .........................................94


web serversapplication mappings .........................................94selecting .............................................................10virtual directories................................................93Web Connectors

installing on UNIX .........................................89installing on Windows ...................................42

web sitesconsulting.............................................................5training.................................................................4

webcon_install.sh .....................................................89Windows

Crystal Enterpriseclient tools installation...................................46Crystal Import Wizard....................................46Crystal Publishing Wizard..............................46custom installation.........................................47expanded installation.....................................43full installation...............................................33installing Java components ............................53installing on non-system drive .......................33server-side installation ...................................37silent installation............................................51

installation overview ..........................................30system requirements ...........................................31

Windows web serversapplication mappings .......................................114configuring virtual paths ...................................118installing Web Connector ...................................42


crystal enterprise installation guide - sap q&a · crystal training whether you’re a...

Documents