1. technology and computing
2. software
3. databases

Crystal Enterprise™ 10
Administrator’s Guide
Crystal Decisions, Inc.
895 Emerson St.
Palo Alto
California, USA 94301
© 2003 Crystal Decisions, Inc. 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
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.
Contents
Chapter 1: Welcome to Crystal Enterprise
What is Crystal Enterprise? ............................................................... 2
Who should use this guide? ............................................................... 2
About this guide ................................................................................ 2
Chapter contents ................................................................................................... 2
Online help ........................................................................................................... 6
Product registration .......................................................................... 6
Customer Handbook ......................................................................... 7
Crystal Care technical support .......................................................... 7
Crystal Training ................................................................................. 7
Crystal Consulting ............................................................................. 8
Document conventions ..................................................................... 8
Chapter 2: What’s New in Crystal Enterprise
End-user experience ........................................................................ 10
Microsoft Office integration ................................................................................. 10
Ad Hoc reporting and analysis ............................................................................ 10
Scheduling .......................................................................................................... 10
Report design .................................................................................. 11
Simplified data access ......................................................................................... 11
Integrated report component repository ............................................................... 11
Report hyperlinking ............................................................................................. 11
Developer flexibility ....................................................................... 12
.NET Server Controls ........................................................................................... 12
Application migration and upsizing ..................................................................... 12
System administration ..................................................................... 12
Crystal Enterprise Administrator’s Guide
iii
Security ............................................................................................................... 12
Object Management ............................................................................................ 13
System Management ........................................................................................... 14
Data access, security and management ............................................................... 15
Platform support .................................................................................................. 15
Chapter 3: Administering Crystal Enterprise
Administration overview ................................................................. 18
Working with the Crystal Management Console ............................. 18
Logging on to the Crystal Management Console .................................................. 19
Navigating within the Crystal Management Console ............................................ 19
Setting console preferences ................................................................................. 20
Setting the Query size threshold .......................................................................... 21
Logging off of the Crystal Management Console .................................................. 22
Working with the Crystal Configuration Manager .......................... 22
Accessing the CCM for Windows ........................................................................ 22
Accessing the CCM for UNIX .............................................................................. 23
Making initial security settings ........................................................ 24
Setting the Administrator password ...................................................................... 24
Disabling the Sign Up feature .............................................................................. 24
Disabling the Guest account ............................................................................... 25
Modifying the default security levels ................................................................... 25
Managing the Crystal Enterprise web desktop ................................. 26
Chapter 4: Crystal Enterprise Architecture
Architecture overview and diagram ................................................ 28
Client tier ........................................................................................ 29
Crystal Enterprise web desktop ............................................................................ 29
Crystal Management Console .............................................................................. 30
Crystal Configuration Manager ............................................................................ 30
iv
Crystal Enterprise Administrator’s Guide
Crystal Publishing Wizard ................................................................................... 30
Crystal Import Wizard ......................................................................................... 31
Application tier ............................................................................... 31
Windows COM platform ..................................................................................... 31
Java platform ....................................................................................................... 32
Windows .NET platform ...................................................................................... 33
Web application environments ............................................................................ 33
Intelligence tier ............................................................................... 34
Crystal Management Server ................................................................................. 34
File Repository Servers ........................................................................................ 35
Event Server ........................................................................................................ 36
Cache Server ....................................................................................................... 36
Processing tier ................................................................................. 37
Report Job Server ................................................................................................ 37
Program Job Server .............................................................................................. 37
Page Server ......................................................................................................... 38
Report Application Server .................................................................................... 38
Data tier .......................................................................................... 39
Report viewers ................................................................................ 39
Information Flow ............................................................................ 40
What happens when you view a report? .............................................................. 40
What happens when you schedule a report? ....................................................... 42
Choosing between live and saved data ............................................ 43
Live data ............................................................................................................. 43
Saved data .......................................................................................................... 44
Chapter 5: Crystal Enterprise Security Concepts
Security overview ........................................................................... 46
How Crystal Enterprise authenticates and authorizes ..................... 46
Primary authentication ........................................................................................ 47
Crystal Enterprise Administrator’s Guide
v
Secondary authentication and authorization ........................................................ 48
Security management components ................................................. 49
Web Component Server ...................................................................................... 49
Crystal Management Server ................................................................................. 50
Security plug-ins .................................................................................................. 50
Processing extensions .......................................................................................... 56
Active trust relationship .................................................................. 57
Logon tokens ....................................................................................................... 57
Ticket mechanism for distributed security ............................................................ 58
Sessions and session tracking .......................................................... 59
WCS session tracking .......................................................................................... 59
CMS session tracking ........................................................................................... 60
Environment protection .................................................................. 60
Web browser to web server ................................................................................. 60
Web server to Crystal Enterprise .......................................................................... 61
Auditing web activity ...................................................................... 61
Protection against malicious logon attempts ................................... 61
Password restrictions ........................................................................................... 61
Logon restrictions ................................................................................................ 62
User restrictions .................................................................................................. 62
Guest account restrictions ................................................................................... 62
Chapter 6: Managing User Accounts and Groups
What is account management? ....................................................... 64
Crystal Enterprise default users and groups .................................... 64
Default users ....................................................................................................... 64
Default groups ..................................................................................................... 65
Default Windows NT group ................................................................................ 66
Available authentication types ........................................................ 66
vi
Crystal Enterprise Administrator’s Guide
Managing Enterprise and general accounts ..................................... 67
Creating an Enterprise user account ..................................................................... 68
Modifying a user account .................................................................................... 69
Deleting a user account ...................................................................................... 69
Changing password settings ................................................................................ 70
Creating a group ................................................................................................. 71
Modifying a group ............................................................................................... 72
Viewing group members ..................................................................................... 73
Deleting a group ................................................................................................. 73
Disabling the Sign Up feature .............................................................................. 73
Disabling the Guest account ............................................................................... 74
Granting access to users and groups .................................................................... 74
Managing NT accounts ................................................................... 74
Mapping NT accounts ......................................................................................... 75
Unmapping NT users and groups ........................................................................ 78
Viewing mapped NT users and groups in Crystal Enterprise ................................ 80
Using account aliases for NT ............................................................................... 80
Troubleshooting NT accounts ............................................................................. 82
Setting up NT Single Sign On .............................................................................. 83
Managing LDAP accounts ............................................................... 84
Configuring LDAP authentication and mapping LDAP accounts .......................... 85
Mapping LDAP groups ........................................................................................ 89
Unmapping LDAP users and groups .................................................................... 89
Viewing mapped LDAP users and groups in Crystal Enterprise ............................ 90
Changing LDAP connection parameters and member groups .............................. 91
Managing multiple LDAP hosts ........................................................................... 92
Using account aliases for LDAP ........................................................................... 92
Troubleshooting LDAP accounts ......................................................................... 94
Managing AD accounts ................................................................... 95
Mapping AD accounts ........................................................................................ 95
Crystal Enterprise Administrator’s Guide
vii
Unmapping AD users and groups ........................................................................ 98
Viewing mapped AD users and groups in Crystal Enterprise ................................ 99
Using account aliases for AD .............................................................................. 99
Troubleshooting AD accounts ........................................................................... 101
Using AD Single Sign On .................................................................................. 102
Chapter 7: Managing Folder Objects
Folders overview ........................................................................... 106
Creating and deleting folders ........................................................ 106
Creating a new folder ........................................................................................ 106
Creating a new subfolder at any level ................................................................ 107
Deleting folders ................................................................................................. 108
Copying and moving folders ......................................................... 108
Adding a report to a new folder .................................................... 109
Specifying folder rights ................................................................. 111
Setting limits for folders, users, and groups .................................. 112
Managing User Folders ................................................................. 113
Chapter 8: Publishing Objects to Crystal Enterprise
Publishing overview ...................................................................... 116
Publishing options ............................................................................................. 117
Publishing with the Crystal Publishing Wizard .............................. 117
Logging on to Crystal Enterprise ........................................................................ 118
Adding objects .................................................................................................. 118
Duplicating the folder structure ......................................................................... 118
Creating and selecting a folder on the CMS ....................................................... 119
Moving objects between folders ........................................................................ 120
Changing scheduling options ............................................................................ 120
Enabling repository refresh ................................................................................ 121
viii
Crystal Enterprise Administrator’s Guide
Selecting a program type ................................................................................... 121
Specifying program credentials .......................................................................... 122
Changing default values .................................................................................... 122
Changing object properties ............................................................................... 122
Entering database logon information ................................................................. 123
Setting parameters ............................................................................................. 124
Setting the schedule format ............................................................................... 124
Adding extra files for programs .......................................................................... 124
Specifying command line arguments ................................................................. 124
Finalizing the objects to be added ..................................................................... 125
Publishing with the Crystal Management Console ........................ 125
Saving objects directly to the CMS ................................................ 127
Chapter 9: Importing Objects to Crystal Enterprise
Crystal Import Wizard overview ................................................... 130
Importing information from Crystal Enterprise ................................................... 130
Importing information from Info ........................................................................ 133
Importing with the Crystal Import Wizard .................................... 135
Specifying the source and destination environments .......................................... 136
Selecting information to import ......................................................................... 137
Chapter 10: Controlling User Access
Controlling user access overview .................................................. 142
Controlling users’ access to objects .............................................. 142
Viewing object rights settings ............................................................................ 143
Setting common access levels ........................................................................... 144
Setting advanced object rights ........................................................................... 146
Using inheritance to your advantage ................................................................. 149
Inheritance with advanced rights ....................................................................... 151
Customizing a ‘top-down’ inheritance model .................................................... 154
Crystal Enterprise Administrator’s Guide
ix
Controlling access to Crystal applications ..................................... 173
Controlling administrative access ................................................. 174
Controlling access to users and groups .............................................................. 175
Controlling access to servers and server groups ................................................. 176
Chapter 11: Managing Objects
Managing objects overview ........................................................... 178
General object management ......................................................... 178
Copying, moving, or creating a shortcut for an object ....................................... 179
Deleting an object ............................................................................................. 180
Searching for an object ...................................................................................... 180
Changing properties of an object ....................................................................... 181
Setting object rights for users and groups ........................................................... 182
Report object management ........................................................... 184
What are report objects and instances? .............................................................. 184
Setting report refresh options ............................................................................. 185
Setting report viewing options ........................................................................... 186
Specifying servers for viewing and modification ................................................ 187
Applying processing extensions to reports ......................................................... 189
Specifying alert notification ............................................................................... 192
Changing database information ......................................................................... 194
Updating parameters ......................................................................................... 196
Using filters ....................................................................................................... 197
Working with hyperlinked reports .................................................................... 199
Program object management ........................................................ 201
What are program objects and instances? .......................................................... 201
Specifying command-line arguments ................................................................. 202
Setting a working directory for a program object ............................................... 202
Configuring executable programs ...................................................................... 203
Configuring Java programs ................................................................................ 205
x
Crystal Enterprise Administrator’s Guide
Authentication and program objects .................................................................. 206
Object package management ........................................................ 208
What are object packages, components, and instances? .................................... 208
Creating an object package ............................................................................... 208
Adding objects to an object package ................................................................. 209
Configuring object packages and component objects ........................................ 210
Authentication and object packages .................................................................. 210
Chapter 12: Scheduling Objects
Scheduling objects overview ......................................................... 212
Setting up scheduling .................................................................... 212
Specifying servers for scheduling ....................................................................... 212
Managing calendars .......................................................................................... 214
Scheduling objects ........................................................................ 220
Scheduling on demand ..................................................................................... 221
Scheduling an object to run once ...................................................................... 222
Scheduling a daily object .................................................................................. 223
Scheduling a weekly object ............................................................................... 226
Scheduling a monthly object ............................................................................. 227
Scheduling an object with a calendar ................................................................ 231
Scheduling objects in batches ........................................................................... 232
Scheduling an object with events ...................................................................... 234
Managing instances ....................................................................... 236
Selecting a destination ...................................................................................... 237
Choosing a format ............................................................................................. 243
Setting printer and page layout options .............................................................. 244
Setting instance limits for an object ................................................................... 246
Managing and viewing the history of instances .................................................. 248
Setting notification for an object’s success or failure .......................................... 249
Crystal Enterprise Administrator’s Guide
xi
Chapter 13: Managing Crystal Repository
Crystal Repository overview ......................................................... 254
Copying data from one repository database to another ................ 254
Copying data from a Crystal Enterprise 10 CMS ................................................. 254
Copying data from a Crystal Enterprise 9 repository database ............................ 255
Copying data from a Crystal Reports 9 repository database ................................ 257
Refreshing repository objects in published reports ....................... 258
Chapter 14: Managing Events
Managing events overview ............................................................ 262
File-based events ........................................................................... 263
Schedule-based events .................................................................. 264
Custom events ............................................................................... 266
Specifying event rights .................................................................. 267
Chapter 15: Managing and Configuring Servers
Server management overview ....................................................... 270
Viewing current metrics ................................................................ 271
Viewing current server metrics .......................................................................... 271
Viewing system metrics ..................................................................................... 273
Viewing and changing the current status of servers ...................... 274
Starting, stopping, and restarting servers ............................................................ 274
Enabling and disabling servers ........................................................................... 276
Printing, copying, and refreshing server status ................................................... 278
Configuring the application tier .................................................... 279
Configuring properties for the Web Component Server ...................................... 279
Configuring the Web Component Adapter ......................................................... 282
Configuring the intelligence tier ................................................... 284
xii
Crystal Enterprise Administrator’s Guide
Clustering Crystal Management Servers ............................................................. 284
Copying CMS data from one database to another .............................................. 289
Deleting and recreating the CMS database ........................................................ 298
Selecting a new or existing CMS database ......................................................... 298
Setting root directories and idle times of the File Repository Servers ................. 300
Modifying Cache Server performance settings ................................................... 301
Modifying the polling time of the Event Server .................................................. 303
Configuring the processing tier ..................................................... 304
Modifying Page Server performance settings ...................................................... 304
Modifying database interaction settings for the RAS ........................................... 306
Modifying performance settings for the RAS ...................................................... 308
Modifying performance settings for Job Servers ................................................. 308
Setting default scheduling destinations for Job Servers ....................................... 309
Configuring Windows processing servers for your data source .......................... 313
Configuring UNIX processing servers for your data source ................................ 315
Logging server activity .................................................................. 320
Advanced server configuration options ......................................... 321
Changing the default server port numbers ......................................................... 321
Configuring Crystal Enterprise on a multihomed machine ................................. 324
Adding and removing Windows server dependencies ....................................... 325
Changing the server startup type ........................................................................ 326
Changing the server user account ...................................................................... 326
Chapter 16: Managing Auditing
Auditing overview ......................................................................... 330
How does auditing work? .................................................................................. 330
Which actions can I audit? ................................................................................ 331
Configuring the auditing database ................................................ 334
Enabling auditing of user and system actions ................................ 335
Controlling synchronization of audit actions ................................ 337
Crystal Enterprise Administrator’s Guide
xiii
Optimizing system performance while auditing ............................ 338
Reporting on audit results ............................................................. 339
Using sample audit reports ................................................................................ 339
Creating custom audit reports ............................................................................ 341
Chapter 17: Managing Server Groups
Server group overview .................................................................. 350
Creating a server group ................................................................. 350
Working with server subgroups .................................................... 352
Modifying the group membership of a server ............................... 353
Chapter 18: Scaling Your System
Scalability overview ...................................................................... 356
Common configurations ................................................................ 356
One-machine setup ........................................................................................... 357
Three-machine setup ......................................................................................... 357
Six-machine setup ............................................................................................. 358
General scalability considerations ................................................ 359
Increasing overall system capacity ..................................................................... 359
Increasing scheduled reporting capacity ............................................................ 359
Increasing on-demand viewing capacity ............................................................ 360
Enhancing custom web applications .................................................................. 361
Improving web response speeds ........................................................................ 361
Configuring your web farm for load balancing .................................................. 362
Getting the most from existing resources ........................................................... 363
Adding and deleting servers .......................................................... 364
Adding a server ................................................................................................. 365
Deleting a server ............................................................................................... 366
xiv
Crystal Enterprise Administrator’s Guide
Chapter 19: Working with Firewalls
Firewalls overview ........................................................................ 368
What is a firewall? ............................................................................................. 368
Firewall types .................................................................................................... 369
Understanding Crystal Enterprise and firewall integration ............ 371
Communication between Crystal Enterprise servers ........................................... 371
Overview of Crystal Enterprise and firewall configuration ................................. 373
Typical firewall scenarios .................................................................................. 373
Configuring Crystal Enterprise to work with firewalls ................... 374
Configuring for Network Address Translation .................................................... 375
Configuring for packet filtering .......................................................................... 383
Configuring for SOCKS servers .......................................................................... 387
Chapter 20: General Troubleshooting
Troubleshooting overview ............................................................. 394
Documentation resources ............................................................. 395
Web accessibility issues ................................................................ 396
Using an IIS web site other than the default ....................................................... 396
UNIX Web Connector cannot access WCS on Windows ................................... 396
Communication error when accessing the CMC ................................................ 396
Unable to connect to CMS when logging on to the CMC .................................. 397
Windows NT authentication cannot log you on ................................................ 397
Report viewing and processing issues ........................................... 398
Troubleshooting reports with Crystal Reports ..................................................... 398
Troubleshooting reports and looping database logon prompts ........................... 400
Error detected by database driver ...................................................................... 402
Ensuring that server resources are available on local drives ............................... 404
Page Server error when viewing a report ........................................................... 404
Crystal Enterprise Administrator’s Guide
xv
Crystal Enterprise web desktop considerations ............................. 405
Supporting users in multiple time zones ............................................................ 405
Setting default report destinations ...................................................................... 405
Setting preferences and report viewers for Crystal Enterprise
web desktop users ............................................................................................. 405
Crystal Enterprise web desktop and Windows Single Sign On ........................... 406
Chapter 21: Licensing Information
Licensing overview ........................................................................ 408
Accessing license information ....................................................... 409
Adding a license key ..................................................................... 410
Viewing current account activity .................................................. 410
Express Edition vs. Professional Edition ......................................... 411
Appendix A: Rights and Access Levels
Rights ............................................................................................ 414
Access levels ................................................................................. 415
No Access ......................................................................................................... 415
View ................................................................................................................. 415
View On Demand ............................................................................................. 416
Full Control ....................................................................................................... 416
Default rights on the top-level folder ............................................ 417
Object rights for the Report Application Server ............................ 417
Appendix B: Configuring NTFS Permissions
Configuring NTFS permissions ...................................................... 420
Configuring NTFS permissions for Crystal Enterprise components ...................... 420
xvi
Crystal Enterprise Administrator’s Guide
Appendix C: Server Command Lines
Command lines overview .............................................................. 426
Standard options for all servers ..................................................... 426
Crystal Management Server .......................................................... 428
Web Component Server ................................................................ 429
Page Server and Cache Server ....................................................... 429
Report and Program Job Servers ................................................... 431
Report Application Server ............................................................. 432
Input and Output File Repository Servers ..................................... 433
Event Server .................................................................................. 434
Appendix D: UNIX Tools
UNIX tools overview ..................................................................... 436
Script utilities ................................................................................ 436
ccm.sh .............................................................................................................. 436
cmsdbsetup.sh .................................................................................................. 438
configpatch.sh ................................................................................................... 439
serverconfig.sh .................................................................................................. 439
sockssetup.sh .................................................................................................... 440
uninstallCE.sh ................................................................................................... 441
Script templates ............................................................................ 442
startservers ........................................................................................................ 442
stopservers ........................................................................................................ 442
silentinstall.sh ................................................................................................... 442
Scripts used by Crystal Enterprise ................................................. 443
crystalrestart.sh ................................................................................................. 443
env.sh ............................................................................................................... 443
Crystal Enterprise Administrator’s Guide
xvii
env-locale.sh ..................................................................................................... 443
initlaunch.sh ..................................................................................................... 443
patchlevel.sh ..................................................................................................... 443
postinstall.sh ..................................................................................................... 444
setup.sh ............................................................................................................. 444
setupinit.sh ........................................................................................................ 444
Appendix E: International Deployments
International deployments overview ............................................. 446
Deploying Crystal Enterprise internationally ................................. 446
Planning an international Crystal Enterprise deployment ................................... 446
Configuring a solution for multiple languages .................................................... 449
Providing a client tier for multiple languages ..................................................... 453
Designing reports for an international audience ........................... 453
Conditional formatting for multiple languages ................................................... 453
Formatting text in multilingual reports ............................................................... 454
Formatting based on cultural conventions ......................................................... 456
Providing multiple languages in a single report ................................................. 457
Appendix F: Creating Accessible Reports
About accessibility ........................................................................ 460
Benefits of accessible reports ............................................................................. 460
About the accessibility guidelines ...................................................................... 461
Accessibility and Crystal products ..................................................................... 462
Improving report accessibility ....................................................... 462
Placing objects in reports .................................................................................. 462
Text ................................................................................................................... 464
Color ................................................................................................................. 467
Navigation ........................................................................................................ 469
Parameter fields ................................................................................................. 469
xviii
Crystal Enterprise Administrator’s Guide
Designing for flexibility ................................................................. 470
Accessibility and conditional formatting ............................................................ 471
Accessibility and suppressing sections ............................................................... 472
Accessibility and subreports .............................................................................. 472
Improving data table accessibility ................................................. 473
Text objects and data table values ..................................................................... 473
Other data table design considerations .............................................................. 478
Accessibility and Crystal Enterprise .............................................. 478
Setting accessible preferences for Crystal Enterprise .......................................... 479
Accessibility and customization .................................................... 479
Resources ...................................................................................... 481
Glossary ......................................................................... 483
Index .............................................................................. 497
Crystal Enterprise Administrator’s Guide
xix
xx
Crystal Enterprise Administrator’s Guide
Welcome to Crystal Enterprise
1
This chapter briefly describes Crystal Enterprise and
outlines the contents and the intended audience of this
Administrator’s Guide. Product registration and technical
support information is also included, along with a brief
description of the document conventions used within this
guide.
Crystal Enterprise Administrator’s 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 system administrators who are responsible for
configuring, managing, and maintaining a Crystal Enterprise installation.
Familiarity with your operating system and your network environment is
certainly beneficial, as is a general understanding of web server management and
scripting technologies. However, in catering to all levels of administrative
experience, this guide aims to provide sufficient background and conceptual
information to clarify all administrative tasks and features.
For more information about the product, consult the Crystal Enterprise Getting
Started Guide, the Crystal Enterprise Installation 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 guide
This guide provides you with information and procedures covering a wide range
of administrative tasks. Procedures are provided for common tasks. Conceptual
information and technical details are provided for all advanced topics.
Chapter contents
The following list provides a short description of each of the remaining chapters in
this guide.
Chapter 2: What’s New in Crystal Enterprise
Crystal Enterprise 10 continues to extend the market-leading scalability, reliability,
and flexibility of the Crystal Enterprise system, cementing it firmly as a premium
enterprise reporting system. Crystal Enterprise 10 delivers significant productivity
gains across enterprise reporting deployments, by helping both IT and end users
use the system more effectively. This chapter provides a high-level overview of
new features and enhancements.
2
Crystal Enterprise Administrator’s Guide
1: Welcome to Crystal Enterprise
Chapter 3: Administering Crystal Enterprise
This chapter provides a general description of system administration as it relates
to Crystal Enterprise. It then introduces the administration tools that allow you to
manage and configure Crystal Enterprise, and it shows how to make some
common changes to the system’s default security settings.
Chapter 4: Crystal Enterprise Architecture
This chapter provides an overview of the Crystal Enterprise architecture, describes
the different components, and identifies how they work together to distribute
reports over the web.
Chapter 5: Crystal Enterprise Security Concepts
This chapter details the ways in which Crystal Enterprise addresses enterprise
security concerns, thereby providing administrators and system architects with
answers to typical questions regarding security.
Chapter 6: Managing User Accounts and Groups
This chapter describes the tasks related to account management for users and
groups. It includes instructions that describe how to add, modify, and remove
accounts within Crystal Enterprise. It also details how to use and integrate NT and
LDAP authentication with Crystal Enterprise.
Chapter 7: Managing Folder Objects
This chapter describes basic folder administration tasks and shows how to add
folders and how to change settings, such as object rights and limits, for new folders.
Chapter 8: Publishing Objects to Crystal Enterprise
This chapter focuses on the publishing process: it introduces the Crystal Publishing
Wizard and tells you how you can use it to add Crystal reports and other objects to
the Crystal Enterprise web desktop or to your custom web desktop; it also describes
alternative ways of adding objects to the Crystal Enterprise environment.
Chapter 9: Importing Objects to Crystal Enterprise
The Crystal Import Wizard allows you to import information from other Crystal
Enterprise or Info systems into your new Crystal Enterprise system. This chapter
provides a general overview of the Crystal Import Wizard along with a series of
procedures that lead you through the process of importing information.
Chapter 10: Controlling User Access
This chapter describes the ways in which object rights enable you to secure the
content that you publish to Crystal Enterprise. Predefined access levels, advanced
Crystal Enterprise Administrator’s Guide
3
About this guide
rights, and inherited rights are all discussed in detail. Examples and procedures
are provided in the form of tutorials.
Chapter 11: Managing Objects
This chapter describes the management of report objects and instances using the
Crystal Management Console. It includes information on scheduling and choosing
the settings for a report object, such as the format, the intended destination, the
rights settings, and so on.
Chapter 12: Scheduling Objects
This chapter provides information on scheduling objects. It includes information
about configuring servers and creating calendars for scheduling. It provides
detailed instructions for scheduling objects individually and in batches, and
scheduling with events. It also describes distributing objects, specifying schedule
notifications, and managing instances.
Chapter 13: Managing Crystal Repository
This chapter discusses the use of a Crystal Repository in a Crystal Enterprise
environment. It shows how to connect Crystal Enterprise to a Crystal Repository
located in a database server, and how to refresh repository objects in reports.
Chapter 14: Managing Events
This chapter provides information on creating and managing events. It describes
file-based events, custom events, and schedule-based events.
Chapter 15: Managing and Configuring Servers
This chapter provides information on a range of server tasks that allow you to
customize the behavior of Crystal Enterprise. The chapter first covers
straightforward tasks like starting and stopping servers, and then proceeds to
more advanced configuration options, including CMS clustering and other serverspecific settings.
Chapter 16: Managing Auditing
This chapter provides an overview of the auditing functionality in Crystal
Enterprise. It also describes how to configure the auditing database, how to select
actions to audit, and how to create a custom audit report.
Chapter 17: Managing Server Groups
This chapter shows how to create server groups and subgroups. It also shows how
to modify the group membership of an individual server.
4
Crystal Enterprise Administrator’s Guide
1: Welcome to Crystal Enterprise
Chapter 18: Scaling Your System
This chapter provides general information about ways in which you might begin
to scale, or expand, your Crystal Enterprise system. The chapter also provides
general scalability considerations, and shows how to add server components to
your installation.
Chapter 19: Working with Firewalls
This chapter describes how Crystal Enterprise works with firewall systems. After
providing some background information on the supported types of firewalls, this
chapter explains how to configure firewalls and Crystal Enterprise to work together.
Chapter 20: General Troubleshooting
This chapter provides general troubleshooting steps and solutions to some specific
configuration problems. For up-to-date answers to commonly asked questions,
registered customers can freely download additional technical documents or
knowledge base articles from Crystal Care technical support.
Chapter 21: Licensing Information
This chapter describes how to view licensing information and add license keys
with the Crystal Management Console (CMC). It also shows how to view your
current account activity.
Appendix A: Rights and Access Levels
This appendix maps the object rights that are available in the Crystal Management
Console (CMC) to the actual rights available through the Crystal Enterprise SDK;
it also lists the object rights that make up each of the predefined access levels, and
the default rights that are applied to the system root folder. This appendix is
provided primarily for reference purposes. For complete details on setting object
rights, see “Controlling User Access” on page 141.
Appendix B: Configuring NTFS Permissions
This appendix provides the recommended user account and NTFS permissions for
Crystal Enterprise components.
Appendix C: Server Command Lines
This appendix lists the command-line options that control the behavior of each
Crystal Enterprise server.
Crystal Enterprise Administrator’s Guide
5
Product registration
Appendix D: UNIX Tools
This appendix details each of the administrative tools and scripts that are included
with the UNIX distribution of Crystal Enterprise. This appendix is provided
primarily for reference purposes. Concepts and configuration procedures are
discussed in more detail throughout this guide.
Appendix E: International Deployments
From server configuration to report design, this appendix recommends the best
practices for improving your Crystal Enterprise deployment’s efficiency for a
multilingual, worldwide audience.
Appendix F: Creating Accessible Reports
This appendix provides design recommendations to help you create Crystal
reports that are accessible to people with disabilities.
Glossary
This section defines some common Crystal Enterprise terminology.
Online help
Access the online help in Crystal Enterprise by clicking Help. The online help
contains all of the information found in this guide.
Product registration
There are several ways you can register your product:
• Fill out the Product Registration form on the Crystal Decisions 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 numbers
USA/Canada +1 604 681-5147
United Kingdom +44 (0) 20 8231 0601
Australia +6 2 9955 7682
Germany +49 (0) 69 9509 6182
Hong Kong +852 2893 2727
Singapore +65 777 8786
Registering the product ensures that you are kept up-to-date with product
advancements.
6
Crystal Enterprise Administrator’s Guide
1: Welcome to Crystal Enterprise
Customer Handbook
For 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 support
For 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 Training
Whether 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/
Crystal Enterprise Administrator’s Guide
7
Crystal Consulting
Crystal Consulting
Our 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 conventions
This 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 shortcuts
Delete 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 combinations
CTRL+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/
8
Crystal Enterprise Administrator’s Guide
What’s New in Crystal Enterprise
2
Crystal Enterprise 10 extends the robust information
infrastructure provided by earlier versions of Crystal
Enterprise. Crystal Enterprise 10 brings together features
from across the Crystal product line to meet the diverse
needs of users, from presentation-quality reporting to indepth data analysis. This includes a variety of major
enhancements spread across our data access methods,
administration capabilities, and report design options. This
chapter provides a high level overview of the new features
and enhancements as they pertain to end-users, report
designers, developers, and IT professionals.
Crystal Enterprise Administrator’s Guide
9
End-user experience
End-user experience
Crystal Enterprise 10 brings powerful analytic reporting tasks and capabilities to
the average business user. Power users and analysts can also use Crystal
Enterprise as a central repository for accessing accurate data to conduct analyses,
to create spreadsheets and presentation-quality reports, and to share information
across the enterprise.
Microsoft Office integration
Crystal Enterprise 10 provides a range of integration points with the Microsoft
Office system. To complement the Excel Add-In for Crystal Enterprise, Crystal
Enterprise 10 can store and manage Excel, Word, and PowerPoint files. This allows
you to associate background information, proposals, and other documents with
existing reports in the Crystal Enterprise system, providing a single source for
information on various projects.
Ad Hoc reporting and analysis
Crystal Enterprise 10 provides a broad range of interactive reporting and analysis
capabilities. These capabilities are available through updated out-of-the-box tools
and our Smart Reporting Software Development Kit (SDK), which allows custom
development.
Scheduling
The Crystal Enterprise 10 web interfaces have been updated to increase usability
and accessibility. Common operations, such as scheduling and printing, have been
simplified with the introduction of new features, such as calendars and DHTML
printing.
• Calendars
Calendars simplify scheduling for you, the end-user. You can now run reports
based on predefined calendars that include key business events, such as the
close of quarter, holidays, and data warehouse refresh days. This eliminates the
complex data and time selections that are often required to set up recurring
jobs. For example, you might want to schedule a report to run on the first
morning of each week. Because of holidays, this event might fall on a Monday,
Tuesday, or even Wednesday. Rather than scheduling each instance of the
report individually, or manually selecting the run days, you can set the report
to run against a business calendar that already includes first day or week logic.
• Notification
You can now set scheduling options that automatically send notification when
an object instance succeeds or fails. For example, you may have a large number
of reports that run a new instance every day. You need to check each instance
10
Crystal Enterprise Administrator’s Guide
2: What’s New in Crystal Enterprise
to make sure it ran properly, and then send out emails to the users who need to
know that the new report is available. With thousands of reports, it would take
too much time to manually check the reports and contact the users who need the
information. Using notification settings in Crystal Enterprise, you can set each
object to automatically notify you when the report fails to run properly, and you
can automatically inform users when new report instances run successfully.
Report design
Crystal Enterprise 10 provides greater fluidity between reports and between data
sources through the new Business Views, through the Crystal Repository, and
through new report navigation features.
Simplified data access
Business Views, a new feature of Crystal Enterprise 10, offers a new data
abstraction layer that simplifies the process of connecting to enterprise data
sources. This new central data access model exposes predefined, domain-specific
data sources, which reduces the need for complex joins, filters, or formulas within
individual report designs. Using Business Views, you can integrate data from
disparate sources. You can also bring together data from multiple data collection
platforms and application boundaries so that the differences in data resolution,
coverage, and structure between collection methods are eliminated.
Integrated report component repository
Through the Crystal Repository, Business Views also provides centralized access
to common report components, which makes it easier to share useful components
with other report designers. You store these components in the Crystal Repository
through Crystal Enterprise and access them through either the Crystal Reports
designer or through Business Views.
Report hyperlinking
You can use hyperlinks in Crystal reports (RPT and CAR files) to tie together
information on multiple reports and to enhance navigation for end users. These
hyperlinks pass data context, allowing you to specify a dynamic path between two
specific pieces of information. This functionality is implemented as a Hyperlink in
Crystal Reports and as an Action in Crystal Analysis. You can use Hyperlinks to
link between reports published to an object package in Crystal Enterprise, or to a
specific instance of a report stored in the object history. Use Actions in Crystal
Analysis reports to link between Crystal reports and to other key information.
Crystal Enterprise Administrator’s Guide
11
Developer flexibility
Developer flexibility
Crystal Enterprise 10 allows you, the developer, to take advantage of the powerful
capabilities Crystal Enterprise platform with minimal coding or application
redesign. New features accelerate the process of creating new applications and
they provide a more seamless migration of application built on small components
of the Crystal Enterprise platform.
.NET Server Controls
The .NET Server Controls allow you to rapidly incorporate content and
functionality from Crystal Enterprise into Microsoft Visual Studio.NET
applications. Crystal Enterprise 10 provides visual and non-visual controls that
contain the logic for common operations, such as authentication, folder listing, and
report viewing. You can manipulate these controls in the Visual Studio.NET
environment and insert them seamlessly into applications.
Application migration and upsizing
You can use Crystal Enterprise 10 to centralize and scale existing stand-alone
applications created using the products from the Crystal family. Available in the
Report Application Server (RAS) and Crystal Reports for Visual Studio.NET
Server, a new feature allows you to easily upsize applications to run on a full
Crystal Enterprise deployment with multiple servers.
System administration
Crystal Enterprise 10 helps you, the administrator, to streamline system
management by delegating tasks and automating regular operations. Crystal
Enterprise 10 also provides cross-platform support, comprehensive data
management, and detailed usage auditing capabilities.
Security
Crystal Enterprise 10 extends Active Directory and LDAP functionality to support
a broader set of security scenarios.
• Active Directory (native mode)
Active Directory support allows you to authenticate Crystal Enterprise users
against and Active Directory server. You can also map Active Directory users
and groups to Crystal Enterprise, simultaneously implementing object, folder,
and data-level security.
12
Crystal Enterprise Administrator’s Guide
2: What’s New in Crystal Enterprise
• LDAP (secure socket layer)
The extension of LDAP support in Crystal Enterprise 10 provides a secure
channel for communication between Crystal Enterprise and a directory server,
through which all authentication and authorization requests between Crystal
Enterprise and the LDAP server flow. This feature supports both server
authentication and mutual authentication.
Object Management
Crystal Enterprise 10 increases your ability to centralize critical information and
distribute it consistently to users. Crystal Enterprise 10 allows you to manage and
secure a broad range of information and objects, including spreadsheets, text files,
programs, reports, and hyperlinks. An updated publishing tool and anew object
packaging feature round out this broad set of object management capabilities.
• Hyperlink Objects
Hyperlink objects provide a standard mechanism for accessing information
from external systems. You can use these objects to provide a URL connection
to legacy reports, web services, or other information resources hosted in third
party systems, and you can apply Crystal Enterprise security to these objects.
This allows customers to standardize on managing relevant business
intelligence content in Crystal Enterprise—delivering and securing the content
in a common interface.
• Object packages
Object packages simplify administration by allowing you to schedule, secure
and manage a set of related reports and programs as a single object. This
ensures that each instance of a package provides a consistent and synchronized
snapshot of a set of related data. The new managed report navigation feature
provides a means to link reports in an object package so that end users can
easily move between related report instances.
• Third party object support
The third party object support available in Crystal Enterprise 10 allows you to
distribute additional information associated with core operational reports (for
example, closely related documents or legacy reports). With the Crystal
Enterprise 10 security model and user interface you can distribute Microsoft
Word, Microsoft PowerPoint, Microsoft Excel, Adobe Acrobat, rich text, text,
and program files.
• Unified Publishing Wizard
The Crystal Enterprise 10 Publishing Wizard allows you to publish a number
of objects, such as reports, Microsoft Office documents, and other files, to
Crystal Enterprise simultaneously.
Crystal Enterprise Administrator’s Guide
13
System administration
System Management
Crystal Enterprise 10 allows you to decentralize the administration of large
deployments, for example you can delegate or automate specific tasks.
Additionally, you can use the new auditing capabilities to monitor system usage.
• Delegated administration
Delegated administration allows you, the system administrator, to distribute
administration tasks to application administrators or IT resources in specific
business units. The IT group can configure the system and ensure server health,
while each business unit gains responsibility for object management and security.
While in previous versions of Crystal Enterprise, delegated administration
capabilities were available only through the Software Development Kit (SDK),
Crystal Enterprise 10 directly exposes these capabilities in its primary
management tool, the Crystal Management Console (CMC).
Delegated administration is based on three types of Crystal Enterprise
administrators:
• Global administrators
A global administrator manages the entire Crystal Enterprise deployment.
This person can assign specific users and groups to be managed by specific
application administrators.
• Application administrators
An application administrator can manage folders, reports, and cubes for
specific business unit, but cannot see objects of other business units. An
application administrator can implement an application-level security
model by assigning users and groups to objects.
• Server administrators
A server administrator can mange the addition, removal, and/or
modification of Crystal Enterprise servers.
• Notification
Notification is an object-level trigger, primarily designed to help you catch critical
job failures or notify users when new information is available. Based on the
success or failure of an individual object instance, you can send notification via:
• An email to an administrator, the object owner, or other users.
• An event that triggers a program or report object to run.
• An audit file, stored in the Crystal Enterprise auditing database.
• Program objects
Program objects are executables, scripts, or Java programs that you can
schedule to run regularly or based on an event. Crystal Enterprise 10’s new
program object features allow you to automate a wide range of administrative
tasks, making Crystal Enterprise a self-managing environment. Additionally,
you can use program objects to trigger external processes, thus integrating
Crystal Enterprise into a broader work flow.
14
Crystal Enterprise Administrator’s Guide
2: What’s New in Crystal Enterprise
The following is an example of how program objects can be incorporated into
the administration of a Crystal Enterprise system:
A reconciliation process runs nightly and populates a database. On completion,
a file—nightlybatch.txt—is created, with a batch number. A file event in Crystal
Enterprise detects the file creation and runs five reports against the reconciliation
data from that night. The completion of these five report jobs triggers a program
object. This program object runs a script that moves nightlybatch.txt to another
directory, which launches another process in another system.
• Auditing
New auditing capabilities in Crystal Enterprise 10 provide you, the administrator,
with a detailed historical view of user and object interaction, and of system usage.
This allows you to fine-tune system performance, retire unused reports, and
provide business units with a comprehensive snapshot of their usage patterns.
Servers in Crystal Enterprise are now designed to record pertinent statistical
metrics to an auditing database. (System administrators specify whether or not
to audit metrics and the time interval of the audit for each server.) The auditing
cache file is periodically passed to the Crystal Management Server (CMS),
where the auditing sub-system maintains a database that stores the information.
You can compile and present this data using performance sample audit reports,
supplied with Crystal Enterprise or your own custom Crystal report.
Data access, security and management
Business Views, a metadata service that is part of Crystal Enterprise 10, allows you
to better manage reporting across multiple data sources. You can efficiently
abstract and organize data for end-users, while managing query efficiency and
data-level security. Additionally, Business Views facilitates the migration of
reports between various versions of an underlying database, for example,
development, testing, and production databases.
Platform support
Crystal Enterprise 10 allows flexibility in choice of operating systems, platforms, and
programming languages, based on individual application requirements. This ensures
that each business unit or application use its existing resources most efficiently.
• Operating systems
Crystal Enterprise 10 provides comprehensive support for all server functions—
including reporting and analysis—on Microsoft Windows, Sun Solaris, and IBM
AIX. You can deploy Crystal Enterprise 10 across any mixture of these platforms
to meet the specific needs of various business units or applications.
• Crystal Enterprise web desktop
Crystal Enterprise’s standard web interface now supports both COM and Java
environments.
Crystal Enterprise Administrator’s Guide
15
System administration
16
Crystal Enterprise Administrator’s Guide
Administering Crystal Enterprise
3
This chapter provides a general description of system
administration as it relates to Crystal Enterprise. It then
introduces the administration tools that allow you to
manage and configure Crystal Enterprise, and it shows
how to make some common changes to the system’s default
security settings.
Crystal Enterprise Administrator’s Guide
17
Administration overview
Administration overview
The regular administrative tasks associated with Crystal Enterprise can be roughly
divided into three major categories: user management, content management, and
server management. The remainder of this guide provides technical and procedural
information corresponding to each of these management categories. This chapter
briefly introduces new Crystal Enterprise administrators to some of the available
management tools. It also shows you how to make initial security settings, such as
setting the password for the system’s default Administrator account.
You will typically use the following applications to manage Crystal Enterprise:
• Crystal Management Console (CMC)
This web application is the most powerful administrative tool provided for
managing a Crystal Enterprise system. It offers you a single interface through
which you can perform almost every task related to user management, content
management, and server management.
For an introduction to the CMC, see “Working with the Crystal Management
Console” on page 18.
• Crystal Configuration Manager (CCM)
This server administration tool is provided in two forms. In a Windows
environment, the CCM allows you to manage local and remote servers through its
Graphical User Interface (GUI) or from a command line. In a UNIX environment,
the CCM shell script (ccm.sh) allows you to manage servers from a command line.
For an introduction to the CCM, see “Working with the Crystal Configuration
Manager” on page 22.
• Crystal Publishing Wizard
This application allows you to publish your reporting content to Crystal
Enterprise quickly. It also allows you to specify a number of options on each
report that you publish. Although this application runs only on Windows, you
can use it to publish reports to Crystal Enterprise servers that are running on
Windows or on UNIX.
For more information on publishing content to Crystal Enterprise, see
“Publishing overview” on page 116.
Working with the Crystal Management Console
You will use the Crystal Management Console (CMC) extensively to manage your
Crystal Enterprise system. This tool allows you to perform user management tasks
such as setting up authentication and adding users and groups. And it allows you
to publish, organize, and set security levels for all of your Crystal Enterprise
content. Additionally, the CMC enables you to manage servers and create server
groups. Because the CMC is a web-based application, you can perform all of these
administrative tasks remotely.
Any user with valid credentials to Crystal Enterprise can log on to the CMC and
set his or her preferences. However, users who are not members of the
18
Crystal Enterprise Administrator’s Guide
3: Administering Crystal Enterprise
Administrators group cannot perform any of the available management tasks
unless they have been granted rights to do so. For complete details about object
rights, see “Controlling User Access” on page 141.
Logging on to the Crystal Management Console
There are two ways to access the CMC: type the name of the machine you are
accessing directly into your browser, or select Crystal Enterprise Admin
Launchpad from the program group on the Windows Start menu.
To log on to the CMC
1 Go to the following page:
http://webserver/crystal/enterprise10/admin/
Replace webserver with the name of the web server machine that has the Web
Connector component installed. If you changed this default virtual directory on
the web server, you will need to type your URL accordingly.
Tip: On Windows, you can click Start > Programs > Crystal Enterprise 10>
Crystal Enterprise Admin Launchpad, and then click the Crystal Management
Console link.
2 When the Log On page appears, select Enterprise in the Authentication Type
list.
Windows NT and LDAP authentication also appear in the list; however, you
must map your third-party user accounts and groups to Crystal Enterprise
before you can use these types of authentication.
3 Type your User Name and Password.
For this example, type Administrator as the User Name. This default Enterprise
account does not have a password until you create one. For details, see “Setting
the Administrator password” on page 24.
If you’re using LDAP or Windows NT authentication, you may log on using an
account that has been mapped to the Crystal Enterprise Administrators group.
4 Click Log On.
The CMC Home page appears.
Navigating within the Crystal Management Console
Because the CMC is a web-based application, you can navigate through its areas
and pages in a number of ways:
• Click the links on the Home page to go to specific “management areas.”
• Select the same “management areas” from the drop-down list in the upper-left
corner of the console. Click Go if your browser doesn’t take you directly to the
new page.
• Click hyperlinks and icons that let you to jump to other areas.
Crystal Enterprise Administrator’s Guide
19
Working with the Crystal Management Console
Once you leave the Home page, your location within the CMC is indicated by a
path that appears above the title of each page. For example, Home > Users > New
User indicates that you’re on the New User page. You can click the hyperlinked
portions of the path to jump quickly to different parts of the application. In this
example, you could click Home or Users to go to the corresponding page.
Setting console preferences
The Preferences area of the CMC allows you to customize your administrative
view of Crystal Enterprise. Log on to the CMC and click the “Preferences” button
in the upper-right corner of the CMC. Select from the following options:
• Viewer
This list sets the default report viewer that is loaded when you view a report in
the CMC. To set the available and default viewers for all users, see
“Configuring the processing tier” on page 304.
• Maximum number of objects per page
This option limits the number of objects listed on any page or tab in the CMC.
Note: This setting does not limit the number of objects displayed, simply the
number displayed per page. For details about limiting the number of objects
displayed on a page or in a search, see “Setting the Query size threshold” on
page 21.
• Maximum number of characters for each page index
When a list of objects spans multiple pages, the full list is sorted alphanumerically
and indexed before being subdivided. At the top of every page, hyperlinks are
displayed as an index to each of the remaining pages. This setting determines the
number of characters that are included in each hyperlink.
In this example, the maximum number of characters is set to 3, so threecharacter hyperlinks are used to index the report objects on each page.
20
Crystal Enterprise Administrator’s Guide
3: Administering Crystal Enterprise
•
•
•
•
Note: To specify an unlimited maximum number of characters, select the
Unlimited check box.
Measuring units for report page layout
Specify inches or millimeters as the measuring units used by default when you
customize a report’s page layout on the report object’s Print Setup tab.
Time zone
If you are managing Crystal Enterprise remotely, use this list to specify your
time zone. Crystal Enterprise synchronizes scheduling patterns and events
appropriately. For instance, if you select Eastern Time (US & Canada), and you
schedule a report to run at 5:00 a.m. every day on a server that is located in San
Francisco, then the server will run the report at 2:00 a.m. Pacific Time.
For more information about time zones, see “Supporting users in multiple time
zones” on page 405.
Menu style
These options change the ways in which menus are displayed in the CMC. You
can view buttons, text, or both.
My Password
Click the Change Password link to change the password for the account under
which you are currently logged on.
Setting the Query size threshold
By default, when you go to the Objects, Folders, Groups, or Users management
areas of the CMC, a list of objects in that management area is displayed. Because
Crystal Enterprise loads each of the objects in the list, if you have numerous objects
this can heavily tax your system resources. You can modify the number of objects
displayed by setting the Query size threshold in the Web Applications
management area of the CMC. By default the Query size threshold value is 500.
This means that Crystal Enterprise prompts users to use the search function of the
CMC if the return size exceeds 500 objects. Modify this value to specify the
maximum number of objects that displayed on the initial pages of the Objects,
Folders, Groups, and Users management areas of the CMC and when displaying
search results in these management areas.
To set the Query size threshold
1 In the CMC, go to the Crystal Applications management area by clicking its link.
2 Click the Crystal Management Console link.
Crystal Enterprise Administrator’s Guide
21
Working with the Crystal Configuration Manager
The Query size threshold page appears.
3 In the Prompt for search if the return size exceeds field, type the maximum
number of objects you want to be returned in searches and on the initial pages
of the Objects, Folders, Groups, and Users management areas.
4 Click Update.
Note: To modify the number of objects displayed on a page (rather than the total
number of objects displayed), see “Setting console preferences” on page 20.
Logging off of the Crystal Management Console
When you have finished using the CMC, end the session by logging off. The Logoff
button is located in the upper-right corner of the console.
Working with the Crystal Configuration Manager
The Crystal Configuration Manager (CCM) is a server-management tool that
allows you to configure each of your Crystal Enterprise server components. This
tool allows you to start, stop, enable, and disable servers. It also allows you to view
and to configure advanced server settings such as default port numbers, CMS
database and clustering details, SOCKS server connections, and more.
Accessing the CCM for Windows
From a Windows machine, use the CCM to manage Crystal Enterprise server
components that are running locally or on a remote Windows machine. To run the
CCM, you must have NT administrator rights on the local machine. If you are
managing servers on a remote machine, you must also have NT administrator
rights on the machine you are connecting to. Depending on the configuration of
your network, you might be prompted to enter a user name and password.
22
Crystal Enterprise Administrator’s Guide
3: Administering Crystal Enterprise
To start the CCM
From the Crystal Enterprise 10 program group, click Crystal Configuration
Manager. The servers that are available on the local machine appear in the list. A
status icon is displayed for each server:
• A green arrow indicates the server is running.
• A yellow arrow indicates the server is starting.
• A red arrow indicates the server is not running.
Note: The status icons do not indicate whether servers are enabled or disabled.
Servers must be enabled before they will respond to Crystal Enterprise requests.
Click Enable/Disable on the toolbar to log on and enable or disable servers. For
details, see “Enabling and disabling servers” on page 276.
To connect to servers on a remote machine
1 Once you have started the CCM, you can connect to a remote machine in
several ways:
• In the Computer Name field, type the name of the machine you want to
connect to; then press Enter.
• In the Computer Name field, select a remote machine from the list.
• On the toolbar, click Browse. Select the appropriate computer; then click OK.
2 If prompted, log on to the remote machine with an account holding
administrative rights.
Note: You may need to type your user name as domain\username.
The CCM lists the servers associated with this machine.
Accessing the CCM for UNIX
Run the CCM on your UNIX server to manage Crystal Enterprise server components
that are running on that machine. You can run the CCM remotely through a telnet
session or locally through a terminal window. To run the CCM, you must have
execute permissions on the ccm.sh script and on its parent crystal directory.
To run the CCM
1 Go to the crystal directory that was created by the Crystal Enterprise installation:
cd INSTALL_ROOT/crystal
2 Run ccm.sh with command-line options to manage one or more servers.
For instance, the following set of commands starts the Crystal Enterprise
servers and enables each server on its default port:
./ccm.sh -start all
./ccm.sh -enable all
Note: The main options for the CCM are covered in more detail in “UNIX
Tools” on page 435.
Crystal Enterprise Administrator’s Guide
23
Making initial security settings
To view additional help on ccm.sh
The ccm.sh script also provides a detailed description of its command-line options.
To see the command-line help, issue the following command:
./ccm.sh -help | more
Making initial security settings
This section focuses on some of the key security settings that you may want to
make immediately, before publishing content and providing users with access to
Crystal Enterprise. The list of “Related topics” shows where you can find
additional procedures and information related to security.
Related topics
• For a technical overview of security within Crystal Enterprise, see “Crystal
Enterprise Security Concepts” on page 45.
• For procedures on setting up authentication, see “Available authentication
types” on page 66.
• For details about object rights, see “Controlling User Access” on page 141.
Setting the Administrator password
As part of the installation, Crystal Enterprise creates an Administrator account and
a Guest account that do not have passwords. Log on to the Crystal Management
Console (CMC) with the Administrator account and use the following procedure
to create a secure password for the Administrator account.
Note: Do not create a password for the Guest account if you plan to use the
anonymous Single Sign On or the Sign Up features available in Crystal Enterprise.
To change the Administrator password
1 Go to the Users management area of the CMC.
2 Click the link for the Administrator account.
3 In the Enterprise Password Settings area, enter and confirm the new password.
4 If it is selected, clear the “User must change password at next logon” check box.
5 Click Update.
Disabling the Sign Up feature
When users connect to Crystal Enterprise without specifying a user name and
password, the system logs them on automatically under the Guest account. By
default, each user then has the ability to sign up and create a new account on the
system. You have the option to change this default behavior and to prevent guest
users from creating their own accounts.
24
Crystal Enterprise Administrator’s Guide
3: Administering Crystal Enterprise
To disable the Sign Up feature
1 Go to the Authorization management area of the CMC.
2 Click the Enterprise tab.
3 In the “Guest Account Restrictions” area, clear the “Guest” users can create
their own Enterprise accounts check box.
4 Click Update.
Disabling the Guest account
By disabling the Guest account, you ensure that no one can log on to Crystal
Enterprise with this account. In doing so, you also disable the anonymous Single
Sign On functionality of Crystal Enterprise, so users will be unable to access the
Crystal Enterprise web desktop without providing a valid user name and password.
To disable the Guest account
1 Go to the Users management area of the CMC.
2 In the Account Name column, click Guest.
3 On the Properties tab, select the Account is disabled check box.
4 Click Update.
5 If you are prompted for confirmation, click OK.
Modifying the default security levels
This procedure shows where you can modify the default object rights that users are
granted to the top-level Crystal Enterprise folder.
Initially, the Everyone group is granted Schedule access to the top-level folder, and
the Administrators group is granted Full Control. You can change these default
security levels to suit your needs. For a full description of object rights and
inheritance patterns, see “Controlling users’ access to objects” on page 142.
To modify top-level security settings
1 Go to the Settings management area of the CMC.
2 Click the Rights tab.
3 As required, change the entry in the Access Level list for each user or group
that is displayed.
4 Click Update.
5 Click Add/Remove to grant different levels of security to additional users or
groups.
Crystal Enterprise Administrator’s Guide
25
Managing the Crystal Enterprise web desktop
Managing the Crystal Enterprise web desktop
You can use the Crystal Applications area of the Crystal Management Console to
make minor changes to the appearance and functionality of the Crystal Enterprise
web desktop, without doing any programming. You can also configure settings
that control which viewers are available to users.
When users view a report using the Advanced DHTML viewer, the report is
processed by the Report Application Server, which is optimized for report
modification. For simple report viewing you can achieve better system
performance if users select one of the other viewers. If the ability to modify reports
is not needed at your site, you can disable the Advanced DHTML viewer.
If you are using the Java version of the Crystal Enterprise web desktop and want
users to be able to use the Active X or Java viewers, you must enter the context path
of the Web Component Adapter. Consult the Crystal Enterprise Installation Guide for
more information.
To manage settings for the Crystal Enterprise web desktop
1 In the Crystal Management Console, select Crystal Applications.
2 Select Web Desktop.
3 On the Preferences tab, select the options that you want.
4 Click Update.
26
Crystal Enterprise Administrator’s Guide
Crystal Enterprise Architecture
4
This chapter provides an overview of the Crystal Enterprise
architecture, describes the different components, and
identifies how they work together to distribute reports over
the web.
Crystal Enterprise Administrator’s Guide
27
Architecture overview and diagram
Architecture overview and diagram
Crystal Enterprise is a multi-tier system. Although the components are responsible
for different tasks, they can be logically grouped based on the type of work they
perform. If you are new to Crystal Enterprise, use this chapter to gain familiarity
with the Crystal Enterprise framework, its components, and the general tasks that
each component performs.
In Crystal Enterprise, there are five tiers: the client tier, the application tier, the
intelligence tier, the processing tier, and the data tier. To provide flexibility, the
components that make up each of these tiers can be installed on one machine, or
spread across many.
The following diagram illustrates how each of the components fits within the
multi-tier system. Other Crystal products, such as Crystal Analysis and Smart
Reporting Technology, plug in to the Crystal Enterprise framework in various
ways. This chapter describes the framework itself. Consult each product’s
installation or administration guides for details about how it integrates with the
Crystal Enterprise framework.
The “servers” run as services on Windows machines. On UNIX, the servers run as
daemons. These services can be “vertically scaled” to take full advantage of the
hardware that they are running on, and they can be “horizontally scaled” to take
28
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
advantage of multiple computers over a network environment. This means that
the services can all run on the same machine, or they can run on separate machines.
The same service can also run in multiple instances on a single machine.
For example, you can run the Crystal Management Server and the Event Server on one
machine, while you run the Page Server on a separate machine. This is called
“horizontal scaling.” If the Page Server is running on a multi-processor computer, then
you may choose to run multiple Page Servers on it. This is called “vertical scaling.” The
important thing to understand is that, even though these are called servers, they are
actually services and daemons that do not need to run on separate computers.
Note: Crystal Enterprise Standard requires all of the components, except for the
Web Connector, to be installed on one machine.
The remainder of this chapter describes each tier, the key Crystal Enterprise
components, and their primary responsibilities.
Tip: When you are familiar with the architecture and want to customize your
system configuration, see “Managing and Configuring Servers” on page 269 and
“Scaling Your System” on page 355.
Note: Crystal Enterprise supports reports created in versions 6 through 10 of
Crystal Reports. Once published to Crystal Enterprise, reports are saved,
processed, and displayed in version 10 format.
Client tier
The client tier is the only part of the Crystal Enterprise system that administrators
and end users interact with directly. This tier is made up of the applications that
enable people to administer, publish, and view reports and other objects.
Crystal Enterprise web desktop
Crystal Enterprise comes with a web-based interface that end users access to view,
schedule, and keep track of published reports. Each Crystal Enterprise request that
a user makes is directed to the Crystal Enterprise application tier. What happens
next depends upon which Crystal Enterprise Software Development Kit (SDK)
your system uses. In a Windows installation with the COM SDK (the default
Windows option), the web server passes the user request to the Web Connector.
The Web Connector then forwards the request to the WCS for processing. In an
installation that uses the Java SDK, the web server forwards the user request
directly to an application server where the request is processed by components
built on the Crystal Enterprise SDK.
Crystal Enterprise Administrator’s Guide
29
Client tier
The Crystal Enterprise web desktop also serves as a demonstration of the ways in
which you can use the Crystal Enterprise Software Development Kit (SDK) to
create a custom web application for end users. For more information, see the
developer documentation available on your product CD.
Crystal Management Console
The Crystal Management Console (CMC) allows you to perform user management
tasks such as setting up authentication and adding users and groups. It also allows
you to publish, organize, and set security levels for all of your Crystal Enterprise
content. Additionally, the CMC enables you to manage servers and create server
groups. Because the CMC is a web-based application, you can perform all of these
administrative tasks remotely. For more information, see “Working with the
Crystal Management Console” on page 18.
The CMC also serves as a demonstration of the ways in which you can use the
administrative objects and libraries in the Crystal Enterprise SDK to create custom
web applications for administering Crystal Enterprise. For more information, see
the developer documentation available on your product CD.
Crystal Configuration Manager
The Crystal Configuration Manager (CCM) is a server-management tool that
allows you to configure each of your Crystal Enterprise server components. This
tool allows you to start, stop, enable, and disable servers, and it allows you to view
and to configure advanced server settings. On Windows, these settings include
default port numbers, CMS database and clustering details, SOCKS server
connections, and more. In addition, on Windows the CCM allows you to add or
remove servers from your Crystal Enterprise system. On UNIX, some of these
functions are performed using other tools. For more information, see “Working
with the Crystal Configuration Manager” on page 22 and “Managing and
Configuring Servers” on page 269.
Crystal Publishing Wizard
The Crystal Publishing Wizard is a locally installed Windows application that
enables both administrators and end users to add reports to Crystal Enterprise. By
assigning object rights to Crystal Enterprise folders, you control who can publish
reports and where they can publish them to. For more information, see “Publishing
overview” on page 116 and “Controlling users’ access to objects” on page 142.
The Crystal Publishing Wizard publishes reports from a Windows machine to
Crystal Enterprise servers running on Windows or on UNIX.
30
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
Crystal Import Wizard
The Crystal Import Wizard is a locally installed Windows application that guides
administrators through the process of importing users, groups, reports, and folders
from an existing Crystal Enterprise or Info implementation to Crystal Enterprise.
For more information, see “Crystal Import Wizard overview” on page 130.
The Crystal Import Wizard runs on Windows, but you can use it to import
information into a new Crystal Enterprise system running on Windows or on UNIX.
Application tier
The application tier hosts the server-side components that are needed to process
requests from the client tier as well as the components that are needed to
communicate these requests to the appropriate server in the intelligence tier. The
application tier includes support for report viewing and logic to understand and
direct web requests to the appropriate Crystal Enterprise server in the intelligence tier.
Because Crystal Enterprise is designed to support a variety of web development
platforms, the components included in your application tier will vary.
Windows COM platform
The default installation of Crystal Enterprise on Windows uses the Crystal
Enterprise COM SDK. It includes a Web Connector and a Web Component Server,
and requires the use of a web server.
Web Component Server
Crystal Enterprise systems that use the Windows COM SDK include a Web
Component Server (WCS), and a Web Connector. The WCS is the gateway
between the Web Connector on the web server and the rest of the components in
Crystal Enterprise. The WCS is responsible for processing requests from your
browser, including Crystal Server Pages (.csp files), which are used to customize
your access to Crystal Enterprise. As a result, this server also acts as an application
server. For more information, see the developer documentation available on your
product CD.
Crystal Enterprise Administrator’s Guide
31
Application tier
In addition to processing CSP requests, the WCS also handles other types of
requests. These include requests from the CMC and the handling of prompts and
database logon requests.
If you are running multiple Cache Servers, the WCS automatically load-balances
reporting requests across the available servers.
Note: There is no WCS in UNIX installations of Crystal Enterprise, or in Windows
installations that use the Crystal Enterprise Java SDK. The functionality of the
WCS is provided by the Web Component Adapter (WCA).
Web Connectors
Crystal Enterprise systems that use the Windows COM SDK include a Web
Connector. In these systems, the web server uses the Web Connector to forward
user requests to the Web Component Server. Crystal Enterprise includes different
Web Connectors for different operating systems and web servers.
If you are running multiple WCS machines, the Web Connector automatically
balances the load across the available servers. For details about how the Web
Connector handles communications with the WCS, especially with respect to
security issues, see “Ticket mechanism for distributed security” on page 58.
For details on installing and configuring Web Connectors, see the Crystal Enterprise
Installation Guide.
Note: There is no Web Connector in UNIX installations of Crystal Enterprise,or in
Windows installations that use the Java SDK. In these systems the web server
communicates directly with the application server that hosts the Crystal
Enterprise SDK. Web connectors are still available for UNIX web servers that
communicate with a Windows WCS.
Java platform
All UNIX installations of Crystal Enterprise and all Windows installations
configured to use the Crystal Enterprise Java SDK include a Web Component
Adapter. In this configuration, a Java application server is required to host the Web
Component Adapter and the Crystal Enterprise Java SDK. The use of a web server
is optional as you may choose to have static content hosted by the application server.
Application server and Crystal Enterprise Java SDK
Crystal Enterprise systems that use the Crystal Enterprise Java SDK run the SDK
on a third party application server. See the Platforms.txt file included with your
product distribution for a complete list of tested application servers and version
requirements.
The application server acts as the gateway between the web server and the rest of
the components in Crystal Enterprise. The application server is responsible for
32
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
processing requests from your browser, sending Crystal Server Pages (.csp files) to
the Web Component Adapter, and using the Java SDK to interpret Crystal
components in Java Server Pages (.jsp files). The application server also supports
Java versions of the Crystal Enterprise web desktop and other Crystal applications,
and uses the SDK to convert report pages (.epf files) to HTML format when users
view pages with a DHTML viewer.
The application server replaces the Web Component Server (WCS) in Crystal
Enterprise installations that run on UNIX, and in Windows installations that use
the Crystal Enterprise Java SDK. For more information, see the developer
documentation available on your product CD.
Web Component Adapter
In UNIX installations of Crystal Enterprise, or in Windows installations that use a
Java SDK, there is no WCS and no Web Connector. Instead, the web server
communicates directly with the application server that hosts the Crystal Enterprise
SDK. The Web Component Adapter (WCA) runs within the application server and
provides all WCS services that are not directly supported by the Java SDK. Because
the WCA runs on an application server, it is not necessary to have a Web
Connector on the web server. The web server passes requests directly to the
application server, which then forwards the requests on to the WCA.
In this environment the WCA has two primary roles: it processes Crystal Server
Pages (.csp files), and it also supports Crystal applications that formerly relied upon
the WCS. These applications include the Crystal Management Console (CMC) and
Crystal report viewers (that are implemented through viewrpt.cwr requests).
Windows .NET platform
Crystal Enterprise installations that use the .NET Framework include Primary
Interop Assemblies (PIAs) that allow you to use the COM Crystal Enterprise SDK
with ASP.NET, and a set of .NET Server Components that you can optionally use
to simplify the development of custom applications. This configuration requires
the use of a Microsoft Internet Information Services (IIS) web server.
You do not need a Web Connector, Web Component Server, or a Web Component
Adapter for custom ASP.NET applications.
Web application environments
Crystal 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 and the sample
applications available via the Crystal Enterprise Launchpads. It also supports the
development of custom web applications that use .csp, .asp, .jsp, and ASP.NET pages.
Crystal Enterprise Administrator’s Guide
33
Intelligence tier
Crystal Server Pages (.csp) provide functionality similar to that provided by
Microsoft’s Active Server Pages (.asp). Java Server Pages (.jsp) 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 for more information.
Intelligence tier
The intelligence tier manages the Crystal Enterprise system. It maintains all of the
security information, sends requests to the appropriate servers, manages audit
information, and stores report instances.
Crystal Management Server
Note: In previous versions of Crystal Enterprise, the Crystal Management Server
(CMS) was known as the Automated Process Scheduler (APS).
The CMS is responsible for maintaining a database of information about your
Crystal Enterprise system; the other components can therefore access that data as
required. The data stored by the CMS includes information about users and
groups, security levels, Crystal Enterprise content, and servers. The CMS also
maintains the Crystal Repository, and a separate audit database of information
about user actions. This data allows the CMS to perform its four main tasks:
• Maintaining security
By maintaining a database of users and their associated object rights, the CMS
enforces who has access to Crystal Enterprise and the types of tasks they are
able to perform. This also includes enforcing and maintaining the licensing
policy of your Crystal Enterprise system.
• Managing objects
The CMS keeps track of the location of objects and maintains the folder
hierarchy. By communicating with the Report and Program Job Servers, the
CMS is able to ensure that scheduled jobs run at the appropriate times.
34
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
• Managing servers
By staying in frequent contact with each of the servers in the system, the CMS is
able to maintain a list of server status. Report viewers access this list, for instance,
to identify which Cache Server is free to use for a report viewing request.
• Managing auditing
By collecting information about user actions from each Crystal Enterprise
server, and then writing these records to a central audit database, the CMS acts
as the system auditor. This audit information allows system administrators to
better manage their Crystal Enterprise deployment.
Typically, you provide the CMS with database connectivity and credentials when
you install Crystal Enterprise, so the CMS can create its own system database and
Crystal Repository database using your organization’s preferred database server.
For details about setting up CMS databases, see the Crystal Enterprise Installation
Guide, and “Configuring the auditing database” on page 334. See the
Platforms.txt file included with your product distribution for a complete list of
tested database software and version requirements.
Note:
• It is strongly recommended that you back up the CMS system database, and
the audit database frequently. The backup procedure depends upon your
database software. If you are unsure of the procedure, consult with your
database administrator.
• The CMS database should not be accessed directly. System information should
only be retrieved using the calls that are provided in the Crystal Enterprise
Software Development Kit (SDK). For more information, see the developer
documentation available on your product CD.
• You can access the audit database directly to create custom audit reports. See
“Reporting on audit results” on page 339 for more information.
On Windows, the Setup program can install and configure its own Microsoft Data
Engine (MSDE) database if necessary. 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 uses it to
create the CMS system database. You can migrate your default CMS system
database to a supported database server later.
For details about configuring the CMS, its system database, and CMS clusters, see
“Configuring the intelligence tier” on page 284. For more information about
Auditing, see “Managing Auditing” on page 329.
File Repository Servers
There is an Input and an Output File Repository Server in every Crystal Enterprise
implementation. The Input File Repository Server manages all of the report objects
and program objects that have been published to the system by administrators or
end users (using the Crystal Publishing Wizard, the Crystal Management Console,
Crystal Enterprise Administrator’s Guide
35
Intelligence tier
the Crystal Import Wizard, or a Crystal designer component such as Crystal
Reports). The Output File Repository Server manages all of the report instances
generated by the Report Job Server and the program instances generated by the
Program Job Server.
Tip: If you use the Crystal Enterprise SDK, you can also publish reports from
within your own code.
The File Repository Servers are responsible for listing files on the server, querying
for the size of a file, querying for the size of the entire file repository, adding files
to the repository, and removing files from the repository.
Note:
• The Input and Output File Repository Servers cannot share the same
directories. This is because one of the File Repository Servers could then delete
files and directories belonging to the other.
• In larger deployments, there may be multiple Input and Output File Repository
Servers, for redundancy. In this case, all Input File Repository Servers must
share the same directory. Likewise, all Output File Repository Servers must
share a directory.
• Objects with files associated with them, such as text files, Microsoft Word files,
or PDFs, are stored on the File Repository Server.
Event Server
The Event Server manages file-based events. When you set up a file-based event
within Crystal Enterprise, the Event Server monitors the directory that you
specified. When the appropriate file appears in the monitored directory, the Event
Server triggers your file-based event: that is, the Event Server notifies the CMS that
the file-based event has occurred. The CMS then starts any jobs that are dependent
upon your file-based event.
After notifying the CMS of the event, the Event Server resets itself and again
monitors the directory for the appropriate file. When the file is newly created in the
monitored directory, the Event Server again triggers your file-based event.
Note: Schedule-based events, and custom events are managed by the Crystal
Management Server.
Cache Server
The Cache Server is responsible for handling all report viewing requests. The
Cache Server checks whether or not it can fulfill the request with a cached report
page. If the Cache Server finds a cached page that displays exactly the required
data, with data that has been refreshed from the database within the interval that
you have specified as the default, the Cache Server returns that cached report page.
36
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
If the Cache Server cannot fulfil the request with a cached report page, it passes the
request along to the Page Server. The Page Server runs the report and returns the
results to the Cache Server. The Cache Server then caches the report page for future
use, and returns the data to the viewer. By storing report pages in a cache, Crystal
Enterprise avoids accessing the database each and every time a report is requested.
If you are running multiple Page Servers for a single Cache Server, the Cache
Server automatically balances the processing load across Page Servers.
For more information, see “Modifying Cache Server performance settings” on
page 301.
Processing tier
The processing tier accesses the data and generates the reports. It is the only tier
that interacts directly with the databases that contain the report data.
Report Job Server
A Job Server processes scheduled actions on objects at the request of the CMS. You
can configure a Job Server to process either report objects or program objects when
you add it to your Crystal Enterprise system. If you configure a Job Server to
process report objects, it becomes a Report Job Server.
The Report Job Server processes scheduled reports, as requested by the CMS, and
generates report instances (instances are versions of a report object that contain
saved data). To generate a report instance, the Report Job Server communicates
with the database to retrieve the current data.
Program Job Server
A Job Server processes scheduled actions on objects at the request of the CMS. You
can configure a Job Server to process either report objects or program objects when
you add it to your Crystal Enterprise system. If you configure a Job Server to
process program objects, it becomes a Program Job Server.
Program objects allow you to write, publish, and schedule custom applications,
including scripts or Java programs that run against, and perform maintenance
work on, Crystal Enterprise.
The Program Job Server processes scheduled program objects, as requested by the
CMS. To run a program, the Program Job Server first retrieves the files from storage
Crystal Enterprise Administrator’s Guide
37
Processing tier
on the Input File Repository Server, and then runs the program. By definition,
program objects are custom applications. Therefore the outcome of running a
program will be dependent upon the particular program object that is run.
Unlike report instances, which can be viewed in their completed format, program
instances exist as records in the object history. Crystal Enterprise stores the
program’s standard out and standard error in a text output file. This file appears
when you click a program instance in the object History.
Page Server
The Page Server is primarily responsible for responding to page requests by
processing reports and generating Encapsulated Page Format (EPF) pages. The
EPF pages contain formatting information that defines the layout of the report. The
Page Server retrieves data for the report from an instance or directly from the
database (depending on the user’s request and the rights he or she has to the report
object). When retrieving data from the database, the Page Server automatically
disconnects from the database after it fulfills its initial request and reconnects if
necessary to retrieve additional data. (This behavior conserves database licenses.)
The Cache Server and Page Server work closely together. Specifically, the Page
Server responds to page requests made by the Cache Server. The Page Server and
Cache Server also interact to ensure cached EPF pages are reused as frequently as
possible, and new pages are generated as soon as they are required. Crystal
Enterprise takes advantage of this behavior by ensuring that the majority of reportviewing requests are made to the Cache Server and Page Server. (However, if a
user’s default viewer is the Advanced DHTML viewer, the report is processed by
the Report Application Server.)
The Page Server also supports COM, ASP.NET, and Java viewer Software
Development Kits (SDKs).
Report Application Server
The Report Application Server (RAS) processes reports that users view with the
Advanced DHTML viewer. The RAS also provides the ad hoc reporting
capabilities that allow users to create and modify reports over the Web.
The RAS is very similar to the Page Server: it too is primarily responsible for
responding to page requests by processing reports and generating EPF pages.
However, the RAS uses an internal caching mechanism that involves no
interaction with the Cache Server.
As with the Page Server, the RAS supports COM, ASP.NET, and Java viewer
SDKs. The Report Application Server also includes an SDK for report-creation and
modification, providing you with tools for building custom report interaction
interfaces.
38
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
Data tier
The data tier is made up of the databases that contain the data used in the reports.
Crystal Enterprise supports a wide range of corporate databases.
See the Platforms.txt file included with your product distribution for a complete
list of tested database software and version requirements.
Report viewers
Crystal Enterprise includes report viewers that support different platforms and
different browsers in the client tier, and which have different report viewing
functionality. (For more information on the specific functionality or platform
support provided by each report viewer, see the Crystal Enterprise User’s Guide or
the Crystal Reports Developer’s Guide.)
All of the viewers fall into two categories: client-side viewers, and zero client
viewers. Client-side viewers are downloaded and installed in the users’ web
browser while the code to support zero client viewers resides in the application tier.
client-side viewers
zero client viewers
Active X viewer
Java viewer
DHTML viewer
Advanced DHTML viewer
All report viewers help process requests for reports, and present report pages that
appear in the user’s browser.
Zero client viewers reside on the application server. When a user requests a report,
the application server processes the request, and then retrieves the report pages in
.epf format from the Crystal Enterprise framework. The SDK creates a viewer
object on the application server which processes the .epf and creates DHTML
pages that represent both the viewer controls and the report itself. The viewer
object then sends these pages through the web server to the user’s web browser.
Client-side viewers are downloaded and installed in the user’s browser. When a
user requests a report, the application server processes the request, and retrieves
the report pages in .epf format from the Crystal Enterprise framework. The
application server then passes the .epf file to the client-side viewer, which
processes the .epf files and displays them directly in the browser.
Crystal Enterprise Administrator’s Guide
39
Information Flow
If they haven’t already done so, users are prompted to download and install the
appropriate viewer software before the report is displayed in the browser. The
Active X viewer is downloaded the first time a user requests a report, and then
remains installed on the user’s machine. You will be prompted to reinstall the
ActiveX viewer only when a new version becomes available on the server.
Information Flow
This section describes the interaction of the server components in order to
demonstrate how report-processing is performed. This section covers two
different scenarios:
• “What happens when you view a report?” on page 40
• “What happens when you schedule a report?” on page 42
What happens when you view a report?
This section describes the viewing mechanisms that are implemented in the Crystal
Enterprise web desktop. The description of processing flow covers both the case
where the web desktop is implemented with Crystal Server Pages and uses the Web
Component Server (WCS) as its application server, and the case where the web
desktop is implemented in Java Server Pages and runs in a generic application server.
The processing flow for custom ASP, JSP, and ASP.NET applications may differ.
When you view a Crystal report (.rpt file) through Crystal Enterprise, the
processing flow varies depending upon your default report viewer, the type of
report, and the rights you have to the report. In all cases, however, the request that
begins at the web server must be forwarded to the application server.
The actual request is constructed as a URL that includes the report’s unique ID.
This ID is passed as a parameter to a server-side script that, when evaluated by the
application server, verifies the user’s session and retrieves the logon token from
the browser. The script then checks the user’s Crystal Enterprise web desktop
preferences and redirects the request to the viewing mechanism that corresponds
to the user’s default viewer.
Different report viewers require different viewing mechanisms:
• The zero-client DHTML viewer is implemented through viewreport.csp or
viewreport.jsp.
When evaluated by the application server, this script communicates with the
framework (through the published SDK interfaces) in order to create a viewer
object and retrieve a report source from the Cache Server and Page Server.
• The zero-client Advanced DHTML viewer is implemented through
viewreport_ia.csp or viewreport_ia.jsp.
When evaluated by the application server, this script communicates with the
framework (through the published SDK interfaces) in order to create a viewer
object and retrieve a report source from the Report Application Server.
40
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
• The client-side report viewers (the ActiveX and Java viewers) are implemented
through viewrpt.cwr, hosted by the WCA or WCS.
The Crystal Web Request is executed internally through viewer code on the
application server. The viewer code communicates with the framework in order
to retrieve a report page in .epf format from the Cache Server and Page Server.
If they haven’t already done so, users are prompted to download and install the
appropriate viewer software.
Report viewing with the Cache Server and Page Server
Upon receiving a report-viewing request, the Cache Server checks to see if it has
the requested pages cached. Cached pages are stored as Encapsulated Page Format
(.epf) files. If a cached version of the .epf file is available, the Cache Server checks
with the Crystal Management Server (CMS) to see if the user has rights to view the
report. If the user is granted the right to view the report, the Cache Server sends
the .epf file to the application server.
If a cached version of the .epf file is unavailable, the Cache Server requests new .epf
files from the Page Server. The Page Server retrieves the report from the Input File
Repository Server, first checking with the CMS to see if the user has rights to view
the report.
If the report is an instance, and the user only has View rights, the Page Server will
generate pages of the report instance using the data stored in the report object. That
is, the Page Server will not retrieve the latest data from the database. If the report
is an object, the user must have View On Demand rights to view the report
successfully (because the Page Server needs to retrieve data from the database).
If the user has sufficient rights, the Page Server generates the .epf pages and
forwards them to the Cache Server. The Cache Server then caches the .epf files and
sends them to the application server.
If the initial request was made through a Crystal Server Page (viewreport.csp), the
viewer SDK (residing on the application server) is used to generate HTML that
represents both the DHTML viewer and the report itself. The HTML pages are then
returned through the web server to the user’s web browser. If the initial request
was made through a Crystal Web Request (viewrpt.cwr), the application server
forwards the .epf pages through the web server to the report viewer software in the
user’s web browser.
Report viewing with the Report Application Server
Upon receiving a report-viewing request, the RAS checks to see if it has the
requested report data in cache. (The RAS has its own caching mechanism, which is
separate from the Cache Server.) If cached report data is available, the RAS checks
with the CMS to see if the user has rights to view the report. If the user is granted
the right to view the report, the RAS returns .epf pages to the application server.
Crystal Enterprise Administrator’s Guide
41
Information Flow
If a cached version of the page is unavailable, the RAS retrieves the report from the
Input File Repository Server, first checking with the CMS to see if the user has
rights to view the report. The RAS then processes the report and returns the .epf
pages to the application server.
If the user is granted View rights to the report object, then the RAS will only ever
generate pages of the latest report instance. That is, the RAS will not retrieve the
latest data from the database. If, however, the user is granted View On Demand
rights to the report object, then the RAS will refresh the report against the database.
Note: The interactive search and filter features provided by the Advanced
DHTML viewer are available only if the user has View On Demand rights (or
greater) to the report object.
When the application server receives the .epf pages from the RAS, the viewer SDK
is used to generate HTML that represents both the Advanced DHTML viewer and
the report itself. The HTML pages are then returned through the web server to the
user’s web browser.
What happens when you schedule a report?
When you schedule a report, you instruct Crystal Enterprise to process a report
object at a particular point in time, or on a recurring schedule. For example, if you
have a report based off of your web server logs, you can schedule the report to run
every night on a recurring basis.
Tip: Crystal Enterprise also allows you to schedule jobs that are dependent upon
other events. For details, see “Managing events overview” on page 262.
When a user schedules a report using the Crystal Enterprise web desktop, the web
desktop sends the request to the application tier.
• In a Crystal Enterprise system that uses the COM SDK, the web server passes
the web desktop request to the Web Connector. The Web Connector then
passes the request to the Web Component Server (WCS), which communicates
with the rest of Crystal Enterprise. Since the request was to schedule a report,
the WCS passes the request to the Crystal Management Server.
• In a Crystal Enterprise system that uses the Java SDK, the web server passes
the web desktop request directly to the application server. The request is
evaluated by the Java SDK. Since the request was to schedule a report, the SDK
passes the request to the Crystal Management Server.
When the CMS gets the request, it checks to see if the user has sufficient rights to
schedule the report. If the user has sufficient rights, the CMS schedules the report
to run at the specified time(s). When the time occurs, the CMS passes the job to the
Report Job Server. The Report Job Server retrieves the report from the Input File
Repository Server and runs the report against the database, thereby creating an
instance of the report. The Report Job Server then saves the report instance to the
42
Crystal Enterprise Administrator’s Guide
4: Crystal Enterprise Architecture
Output File Repository Server, and tells the CMS that it has completed the job
successfully.
Tip: For details about multiple time zones, see “Supporting users in multiple time
zones” on page 405.
Note:
• The Cache Server and the Page Server do not participate in scheduling reports
or in creating instances of scheduled reports. This can be an important
consideration when deciding how to configure Crystal Enterprise, especially
in large installations. See “Scaling Your System” on page 355.
• When you schedule program objects or object packages, the interaction
between servers follows the same pattern as it does for reports. However,
program objects are processed by the Program Job Server.
• Users without schedule rights on an object will not see the schedule option in
Crystal Enterprise.
Choosing between live and saved data
When 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.
Crystal Enterprise Administrator’s Guide
43
Choosing between live and saved data
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 are not hitting the database every time they open a report.
Tip: Users require only View access to display report instances.
Related topics
• “Scaling Your System” on page 355
44
Crystal Enterprise Administrator’s Guide
Crystal Enterprise Security Concepts
5
This chapter details the ways in which Crystal Enterprise
addresses enterprise security concerns, thereby providing
administrators and system architects with answers to
typical questions regarding security.
Crystal Enterprise Administrator’s Guide
45
Security overview
Security overview
The Crystal Enterprise architecture addresses the many security concerns that affect
today’s businesses and organizations. The current release supports features such as
distributed security, Single Sign On (SSO), resource access security, granular object
rights, and third-party Windows NT, LDAP, and Windows AD authentication in
order to protect against unauthorized access. To allow for further customization of
security, Crystal Enterprise supports dynamically loaded processing extensions.
And, for monitoring and auditing purposes, Crystal Enterprise allows you to log
various web statistics, thus enabling you to detect potential security concerns.
Because Crystal Enterprise provides the framework for an increasing number of
components from the Enterprise family of Crystal products, this chapter details the
security features and related functionality to show how the framework itself
enforces and maintains security. As such, this chapter does not provide explicit
procedural details; instead, it focuses on conceptual information and provides
links to key procedures.
Related topics
• For key procedures that show how to modify the default accounts, passwords,
and other security settings, see “Making initial security settings” on page 24.
• For procedures that show how to set up authentication, users, and groups, see
“Managing User Accounts and Groups” on page 63.
• For procedures that show how to set object rights for your Crystal Enterprise
content, see “Controlling User Access” on page 141.
How Crystal Enterprise authenticates and authorizes
Authentication is the process of verifying the identity of a user who attempts to
access the system, and authorization is the process of verifying that the user has
been granted sufficient rights to perform the requested action upon the specified
object. This section describes the authentication and authorization processes in
order to provide a general idea of how system security works within Crystal
Enterprise. Each of the components and key terms is discussed in greater detail
later in this chapter.
Because Crystal Enterprise is fully customizable, the authentication and
authorization processes may vary from system to system. This section uses the
Crystal Enterprise web desktop as a model and describes its default behavior. If
you are developing your own Crystal Enterprise end-user or administrative
applications using the Crystal Enterprise Software Development Kit (SDK), you
can customize the system’s behavior to meet your needs. For complete details, see
the Crystal Enterprise Web Developer's Guide.
For procedures that show how to set up the different authentication types, see
“Available authentication types” on page 66.
46
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
Primary authentication
Primary authentication occurs when a user first attempts to access the system. The
user provides a user name and password and specifies an authentication type. The
authentication type may be Enterprise, Windows NT, LDAP, or Windows AD
authentication, depending upon which type(s) you have enabled and set up in the
Authorization management area of the Crystal Management Console (CMC). The
user’s web browser sends the information by HTTP to your web server, which routes
the information through the Web Connector to the Web Component Server (WCS).
Note:
• All communication between the user’s web browser and the WCS is similarly
routed through the web server and the Web Connector. For clarity, the web
server and the Web Connector are explicitly discussed only when necessary.
• In a UNIX installation of Crystal Enterprise (or in a Windows installation that
uses the Crystal Enterprise Java SDK), there is no Web Connector, and no Web
Component Server. All communication between the user’s web browser and
the rest of Crystal Enterprise is handled by the Java application server and
Crystal Enterprise Java SDK.
The WCS passes the user’s information to logon.csp and runs the script. Internally,
this script communicates with the SDK and, ultimately, the appropriate security
plug-in to authenticate the user against the user database.
For instance, if the user specifies Enterprise Authentication, the SDK ensures that
the Crystal Enterprise security plug-in performs the authentication. The Crystal
Management Server (CMS) uses the Crystal Enterprise security plug-in component
to verify the user name and password against the system database. Alternatively,
if the user specifies Windows NT, LDAP, or Windows AD Authentication, the SDK
uses the corresponding security plug-in to authenticate the user.
If the security plug-in reports a successful match of credentials (including a match
to an appropriate group membership for Windows NT, Windows AD, or LDAP
authentication), the CMS grants the user an active identity on the system and the
system performs several actions:
• The CMS stores the user’s information in memory in a CMS session variable.
While active, this session consumes one user license on the system.
• The CMS generates and encodes a logon token and sends it to the WCS.
• The WCS stores the user’s information in memory in a WCS session variable.
While active, this session stores information that allows Crystal Enterprise to
respond to the user’s requests.
Note:
• If you are familiar with the SDK, you should note that the WCS here
instantiates the InfoStore object and stores it in the WCS session variable.
• The session variable does not contain the user’s password.
Crystal Enterprise Administrator’s Guide
47
How Crystal Enterprise authenticates and authorizes
• The WCS sends the logon token to the user’s web browser, and the web
browser caches the token in a cookie. Until the logon token expires, its
encoded information serves as the user’s valid ticket for the system.
Each of these steps contributes to the distributed security of Crystal Enterprise,
because each step consists of storing information that is used for secondary
identification and authorization purposes. This is the model used in the Crystal
Enterprise web desktop. However, if you are developing your own client
application and you prefer not to store session state on the WCS, you can design
your application such that it avoids using WCS session variables.
Note:
• The third-party Windows NT, LDAP, and Windows AD security plug-ins
work only once you have mapped groups from the external user database to
Crystal Enterprise. For details, see “Available authentication types” on
page 66.
• In a Single Sign On situation, Crystal Enterprise retrieves users’ credentials
and group information directly from the Windows NT or Windows AD
system. Hence, users are not prompted for their credentials.
Secondary authentication and authorization
Secondary authentication is the process of double-checking the identity of each
user who attempts to view, run, schedule, or otherwise act upon an object that is
managed by Crystal Enterprise. Authorization is the process of verifying that the
user has been granted sufficient rights to perform the requested action upon the
specified object.
When a user attempts to access an object on the system, the web browser sends the
request by HTTP to the WCS. Before fulfilling the user’s request, the WCS
performs a series of security-related steps.
First, the WCS ensures that the user has a valid logon token:
• If there is a valid logon token, the WCS proceeds to its next task.
• If there is no valid logon token, the primary authentication process is repeated.
For more information about logon tokens, see “Logon tokens” on page 57.
Second, the WCS checks internally for an active WCS session that matches the
user’s logon token:
• If the corresponding WCS session variable remains in memory, the WCS
proceeds to its next task.
• If the WCS session variable has timed out, the user is logged back on with the
logon token. The SDK authenticates the user against the appropriate user
database, and the CMS and the WCS recreate the required session variables. In
this case, Crystal Enterprise does not have to prompt the user for credentials,
because the encoded logon token contains the required information.
48
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
Third, the WCS ensures that the appropriate server component actually processes
the user’s request:
• If the WCS can process the request itself, it queries the CMS database for the
rights associated with the object that the user requested.
For instance, if the user requests a list of reports in a specific folder, the WCS
queries the CMS database for a list of the reports that the user is authorized to
see. The WCS then dynamically lists the reports in an HTML page, and sends
the page to the user’s browser.
• If a different server component must process the request, the WCS sends the
request and the user’s logon token to the appropriate server component. That
server component then queries the CMS database for the rights associated
with the object that the user requested.
For instance, if the user attempts to refresh a report’s data, the WCS passes the
request along to the Page Server. The Page Server passes the logon token to the
CMS to ensure that the user is authorized to refresh the report.
For details about how the CMS calculates a user’s effective rights to an object,
see “Calculating a user’s effective rights” on page 152.
This secondary authentication and authorization process begins similarly to initial
identification; here, however, the authentication algorithm followed by the WCS
maintains system security in the fewest number of steps, thereby providing the
most efficient response to the user’s initial request.
Note: If the user does not have the right to perform the requested action, the WCS
displays an appropriate message. For details about setting object rights, see
“Controlling User Access” on page 141.
Security management components
System security within Crystal Enterprise is distributed across most components,
but it is managed primarily by the WCS, the CMS, and the security plug-ins. These
components work together to authenticate and to authorize users who access
Crystal Enterprise, its folders, and its other objects.
This section discusses the key components as they relate to system security.
Because they are responsible for additional tasks, several of the components
discussed in this section are described in additional detail in “Crystal Enterprise
Architecture” on page 27.
Web Component Server
The WCS is the gateway between the web server/Web Connector machine and the
remaining Crystal Enterprise components. As such, the WCS receives all HTTP
requests that are sent to Crystal Enterprise from users’ web browsers.
Crystal Enterprise Administrator’s Guide
49
Security management components
The WCS ensures that each user has a valid logon token for the system. If the logon
token is missing, or if it has expired, the WCS initiates the primary authentication
process. For details, see “Primary authentication” on page 47.
The WCS is also responsible for maintaining the user’s session state in the WCS
session variable. This session variable contains information that Crystal Enterprise
uses when fulfilling user’s requests. For details, see “Sessions and session
tracking” on page 59.
Crystal Management Server
In relation to system security, the CMS performs a number of important tasks. The
majority of these tasks rely upon the database that the CMS uses to keep track of
Crystal Enterprise system data. This data includes security information, such as
user accounts, group memberships, and object rights that define user and group
privileges.
When you first set up your system, the CMS allows you to create user accounts and
groups within Crystal Enterprise. And, with its third-party security plug-ins, the
CMS allows you to reuse existing user accounts and groups that are stored in a
third-party system (a Windows NT user database, an LDAP directory server, or a
Windows AD server). The CMS supports third-party authentication, so users can
log on to Crystal Enterprise with their current Windows NT, LDAP, or Windows
AD credentials.
When users log on, the CMS coordinates the authentication process with its
security plug-ins; the CMS then grants the user a logon token and an active session
on the system. The CMS also responds to authorization requests made by the rest
of the system. When a user requests a list of reports in a particular folder, the CMS
authorizes the request only when it has verified that the user’s account or group
membership provides sufficient privileges.
For details about the CMS and how it calculates a user’s effective rights to an
object, see “Calculating a user’s effective rights” on page 152.
For more information about the CMS and the CMS database, see “Crystal
Management Server” on page 34.
Security plug-ins
Security plug-ins expand and customize the ways in which Crystal Enterprise
authenticates users. Crystal Enterprise currently ships with the system default
Crystal Enterprise security plug-in and with the Windows NT, LDAP, or Windows
AD security plug-ins. Each security plug-in offers several key benefits.
Security plug-ins facilitate account creation and management by allowing you to
map user accounts and groups from third-party systems into Crystal Enterprise.
You can map third-party user accounts or groups to existing Crystal Enterprise
50
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
user accounts or groups, or you can create new Enterprise user accounts or groups
that corresponds to each mapped entry in the external system.
The security plug-ins dynamically maintain third-party user and group listings.
So, once you map a Windows NT, LDAP, or Windows AD group into Crystal
Enterprise, all users who belong to that group can log on to Crystal Enterprise.
When you make subsequent changes to the third-party group membership, you
need not update or refresh the listing in Crystal Enterprise. For instance, if you
map a Windows NT group to Crystal Enterprise, and then you add a new NT user
to the NT group, the security plug-in dynamically creates an alias for that new user
when he or she first logs on to Crystal Enterprise with valid NT credentials.
Moreover, security plug-ins enable you to assign rights to users and groups in a
consistent manner, because the mapped users and groups are treated as if they
were Enterprise accounts. For example, you might map some user accounts or
groups from Windows NT, and some from an LDAP directory server. Then, when
you need to assign rights or create new, custom groups within Crystal Enterprise,
you make all of your settings in the CMC.
Each security plug-in acts as an authentication provider that verifies user credentials
against the appropriate user database. When users log on to Crystal Enterprise,
they choose from the available authentication types that you have enabled and set
up in the Authorization management area of the CMC: Enterprise (the system
default), Windows NT, LDAP, or Windows AD.
Note: The Windows NT and Windows AD security plug-ins cannot authenticate
users if the Crystal Enterprise server components are running on UNIX.
Crystal Enterprise security plug-in
The Crystal Enterprise security plug-in (secEnterprise.dll) is installed and
enabled by default when you install Crystal Enterprise. This plug-in allows you to
create and maintain user accounts and groups within Crystal Enterprise; it also
enables the system to verify all logon requests that specify Enterprise
Authentication. In this case, user names and passwords are authenticated against
the Crystal Enterprise user list, and users are allowed or disallowed access to the
system based solely on that information. For details on setting up Enterprise users
and groups, see “Managing Enterprise and general accounts” on page 67.
Default accounts
When you first install Crystal Enterprise, this plug-in sets up two default Enterprise
accounts: Administrator and Guest. Neither account has a default password. For
details on setting these passwords, see “Making initial security settings” on page 24.
Crystal Enterprise Administrator’s Guide
51
Security management components
Single Sign On
The Crystal Enterprise authentication provider supports anonymous Single Sign On
for the Guest account. Thus, when users connect to Crystal Enterprise without
specifying a user name and password, the system logs them on automatically under
the Guest account. If you assign a secure password to the Guest account, or if you
disable the Guest account entirely, you disable this default behavior. For details, see
“Disabling the Guest account” on page 25.
Sign Up
By default, users who are logged on under the Guest account also have the ability
to sign up and create their own, new accounts on the system. To disable this default
behavior, see “Disabling the Sign Up feature” on page 24.
Windows NT security plug-in
The Windows NT security plug-in (secWindowsNT.dll) allows you to map user
accounts and groups from your Windows NT user database to Crystal Enterprise;
it also enables Crystal Enterprise to verify all logon requests that specify Windows
NT Authentication. Users are authenticated against the Windows NT user
database, and have their membership in a mapped NT group verified before the
CMS grants them an active Crystal Enterprise session.
This plug-in is compatible with NT 4 and Windows 2000 Active Directory user
databases (when Windows 2000 Active Directory is configured in non-native
mode only). If a Windows 2000 Active Directory user database is configured in
native mode and contains universal groups that span several domains, you must
use the Windows AD security plug-in. For information on mapping Windows NT
users and groups to Crystal Enterprise, see “Managing NT accounts” on page 74.
For information on the Windows AD security plug-in, see “Windows AD security
plug-in” on page 55.
Once you have mapped your NT users and groups, all of the Crystal Enterprise client
tools support NT authentication, except for the Crystal Import Wizard. You can also
create your own applications that support NT authentication. For more information,
see the developer documentation available on your product CD.
Note: The Windows NT and Windows AD security plug-ins cannot authenticate
users if the Crystal Enterprise server components are running on UNIX.
Default account
If you install Crystal Enterprise on Windows NT/2000 as an Administrator of the
local machine, then this plug-in is enabled by default. A new NT group (called
Crystal NT Users) is created on the local machine, and your NT user account is
added to the group. The Crystal NT Users group is then mapped to Crystal
Enterprise. The result is that you can log on to Crystal Enterprise with your usual
NT user credentials.
52
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
Single Sign On
The Windows NT security plug-in supports Single Sign On, thereby allowing
authenticated NT users to log on to Crystal Enterprise without explicitly entering
their credentials. The Single Sign On requirements depend upon the way in which
users access Crystal Enterprise: either via a thick client, or over the Web. In both
scenarios, the security plug-in obtains the security context for the user from the
authentication provider, and grants the user an active Crystal Enterprise session if
the user is a member of a mapped NT group:
• To obtain NT Single Sign On functionality from a thick-client application (such
as the Crystal Publishing Wizard), the user must be running a Windows
operating system, and the application must use the Crystal Enterprise SDK.
In this scenario, the Windows NT security plug-in queries the operating system
for the current user’s credentials when the client is launched.
• To obtain Single Sign On functionality over the Web, the system must use
Microsoft components only. Specifically, the user must be running Internet
Explorer on a Windows operating system, and the web server must be running
Internet Information Server (IIS).
In this scenario, Internet Explorer and IIS engage in Windows NT Challenge/
Response authentication before IIS forwards the user’s credentials to Crystal
Enterprise.
Note: IIS performs the Challenge/Response authentication for every web page
viewed. This can result in severe performance degradation.
For details on configuring IIS for Single Sign On, see “Setting up NT Single Sign
On” on page 83.
Note: The Crystal Enterprise web desktop provides its own form of “anonymous
Single Sign On,” which uses Enterprise authentication, as opposed to Windows
NT authentication. Design your own web applications accordingly (or modify the
Crystal Enterprise web desktop) if you want to use NT Single Sign On. For
information on NT Single Sign On, see “Setting up NT Single Sign On” on page 83.
LDAP security plug-in
The LDAP security plug-in (secLDAP.dll) allows you to map user accounts and
groups from your LDAP directory server to Crystal Enterprise; it also enables the
system to verify all logon requests that specify LDAP Authentication. Users are
authenticated against the LDAP directory server, and have their membership in a
mapped LDAP group verified before the CMS grants them an active Crystal
Enterprise session. User lists and group memberships are dynamically maintained by
Crystal Enterprise. You can specify that Crystal Enterprise use a Secure Sockets Layer
(SSL) connection to communicate to the LDAP directory server for additional security.
LDAP authentication for Crystal Enterprise is similar to NT and AD authentication
in that you can map groups and set up authentication, authorization, and alias
creation. Also as with NT or AD authentication, you can create new Enterprise
Crystal Enterprise Administrator’s Guide
53
Security management components
accounts for existing LDAP users, and can assign LDAP aliases to existing users if
the user names match the Enterprise user names. In addition, you can do the
following:
• Implement LDAP authentication when Crystal Enterprise is running on
Windows or on UNIX.
• Map users and groups from the LDAP directory service.
• Specify multiple host names and their ports.
For information on mapping your LDAP users and groups to Crystal Enterprise,
see “Managing LDAP accounts” on page 84.
Once you have mapped your LDAP users and groups, all of the Crystal Enterprise
client tools support LDAP authentication, except for the Crystal Import Wizard.
You can also create your own applications that support LDAP authentication. For
more information, see the developer documentation available from the Crystal
Enterprise Launchpad.
More about LDAP
Lightweight Directory Access Protocol (LDAP), a common, application-independent
directory, enables users to share information among various applications. Based on
an open standard, LDAP provides a means for accessing and updating information
in a directory.
LDAP is based on the X.500 standard, which uses a directory access protocol
(DAP) to communicate between a directory client and a directory server. LDAP is
an alternative to DAP because it uses fewer resources and simplifies and omits
some X.500 operations and features.
The directory structure within LDAP has entries arranged in a specific schema.
Each entry is identified by its corresponding distinguished name (DN) or common
name (CN). Other common attributes include the organizational unit name (OU),
and the organization name (O). For example, a member group may be located in a
directory tree as follows: cn=Crystal Enterprise Users, ou=Enterprise Users A,
o=Research. Refer to your LDAP documentation for more information.
Because LDAP is application-independent, any client with the proper
authorization can access its directories. LDAP offers you the ability to set up users
to log on to Crystal Enterprise through LDAP authentication. It also enables users
to be authorized when attempting to access objects in Crystal Enterprise. As long
as you have an LDAP server (or servers) running, and use LDAP in your existing
networked computer systems, you can use LDAP authentication (along with
Enterprise, NT, and Windows AD authentication).
If desired, the LDAP security plug-in provided with Crystal Enterprise can
communicate with your LDAP server using an SSL connection established using
either server authentication or mutual authentication. With server authentication,
the LDAP server has a security certificate which Crystal Enterprise uses to verify
that it trusts the server, while the LDAP server allows connections from
54
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
anonymous clients. With mutual authentication, both the LDAP server and Crystal
Enterprise have security certificates, and the LDAP server must also verify the
client certificate before a connection can be established.
Note: The LDAP security plug-in provided with Crystal Enterprise can be
configured to communicate with your LDAP server via SSL, but always performs
basic authentication when verifying users’ credentials. Before deploying LDAP
authentication in conjunction with Crystal Enterprise, ensure that you are familiar
with the differences between these LDAP types. For details, see RFC2251, which
is currently available at http://www.faqs.org/rfcs/rfc2251.html
Windows AD security plug-in
Windows AD security plug-in enables you to map user accounts and groups from
your Windows 2000 Active Directory (AD) user database to Crystal Enterprise; it
also enables Crystal Enterprise to verify all logon requests that specify Windows AD
Authentication. Users are authenticated against the Windows AD user database,
and have their membership in a mapped AD group verified before the Crystal
Management Server (CMS) grants them an active Crystal Enterprise session.
This plug-in is compatible with Windows 2000 Active Directory domains running
in either native mode or mixed mode. Note that in order to use the Windows AD
security plug-in, the CMS needs to run under a user account that has the “Act as
Part of the Operating System” right. See your Windows 2000 documentation for
more information.For information on mapping Windows AD users and groups to
Crystal Enterprise, see “Managing AD accounts” on page 95.
Once you have mapped your AD users and groups, all of the Crystal Enterprise
client tools support AD authentication, except for the Crystal Import Wizard. You
can also create your own applications that support AD authentication. For more
information, see the developer documentation available on your product CD. For
information on mapping Windows AD users and groups to Crystal Enterprise, see
“Managing AD accounts” on page 95.
Note:
• AD authentication only works for servers running on Windows systems.
• AD authentication and aggregation is not functional without a network
connection.
• AD authentication and aggregation may not continue to function if the
administration credentials become invalid (for example, if the administrator
changes his or her password or if the account becomes disabled).
Single Sign On
The Windows AD security plug-in supports Single Sign On, thereby allowing
authenticated AD users to log on to Crystal Enterprise without explicitly entering
their credentials. The Single Sign On requirements depend upon the way in which
users access Crystal Enterprise: either via a thick client, or over the Web. In both
Crystal Enterprise Administrator’s Guide
55
Security management components
scenarios, the security plug-in obtains the security context for the user from the
authentication provider, and grants the user an active Crystal Enterprise session if
the user is a member of a mapped AD group:
• To obtain AD Single Sign On functionality from a thick-client application
(such as the Crystal Publishing Wizard), the user must be running a Windows
operating system, and the application must use the Crystal Enterprise SDK.
In this scenario, the Windows AD security plug-in queries the operating system
for the current user’s credentials when the client is launched.
• To obtain Single Sign On functionality over the Web, the system must use
Microsoft components only. Specifically, the user must be running Internet
Explorer on a Windows operating system, and the web server must be running
Internet Information Server (IIS).
Note: Crystal Enterprise provides its own form of “anonymous Single Sign On,”
which uses Enterprise authentication, as opposed to Windows AD authentication.
Design your own web applications accordingly (or modify the Crystal Enterprise
web desktop) if you want to use AD Single Sign On. For information on AD
Single Sign On, see “Using AD Single Sign On” on page 102.
Processing extensions
Crystal Enterprise offers you the ability to further secure your reporting environment
through the use of customized processing extensions. A processing extension is a
dynamically loaded library of code that applies business logic to particular Crystal
Enterprise view or schedule requests before they are processed by the system.
Note: On Windows systems, dynamically loaded libraries are referred to as
dynamic-link libraries (.dll file extension). On UNIX systems, dynamically loaded
libraries are often referred to as shared libraries (.so file extension). You must
include the file extension when you name your processing extensions.
Through its support for processing extensions, the Crystal Enterprise
administration SDK essentially exposes a “handle” that allows developers to
intercept the request. Developers can then append selection formulas to the
request before the report is processed.
A typical example is a report-processing extension that enforces row-level
security. This type of security restricts data access by row within one or more
database tables. The developer writes a dynamically loaded library that intercepts
view or schedule requests for a report (before the requests are processed by the Job
Server, Page Server, or Report Application Server). The developer’s code first
determines the user who owns the processing job; then it looks up the user’s dataaccess privileges in a third-party system. The code then generates and appends a
record selection formula to the report in order to limit the data returned from the
database. In this case, the processing extension serves as a way to incorporate
customized row-level security into the Crystal Enterprise environment.
Tip: In Crystal Enterprise 10, you can also set and enforce row-level security
56
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
through the use of Business Views. For more information, see the Business Views
Administrator's Guide.
The CMC provides methods for registering your processing extensions with
Crystal Enterprise and for applying processing extensions to particular object. For
details, see “Applying processing extensions to reports” on page 189.
By enabling processing extensions, you configure the appropriate Crystal
Enterprise server components to dynamically load your processing extensions at
runtime. Included in the SDK is a fully documented API that developers can use
to write processing extensions. For more information, see the developer
documentation available on your product CD.
Note: In the current release, processing extensions can be applied only to Crystal
report (.rpt) objects.
Active trust relationship
In a networked environment, a trust relationship between two domains is generally
a connection that allows one domain accurately to recognize users who have been
authenticated by the other domain. While maintaining security, the trust
relationship allows users to access resources in multiple domains without
repeatedly having to provide their credentials.
Within the Crystal Enterprise environment, the active trust relationship works
similarly to provide each user with seamless access to resources across the system.
Once the user has been authenticated and granted an active session, all other
Crystal Enterprise components can process the user’s requests and actions without
prompting for credentials. As such, the active trust relationship provides the basis
for Crystal Enterprise’s distributed security.
Tip: When combined with Single Sign On functionality, the active trust
relationship allows users to access their Crystal Enterprise resources without ever
having to explicitly provide credentials to Crystal Enterprise.
Logon tokens
A logon token is an encoded string that defines its own usage attributes and
contains a user’s session information. The logon token’s usage attributes are
specified when the logon token is generated. These attributes allow restrictions to
be placed upon the logon token to reduce the chance of the logon token being used
by malicious users. The current logon token usage attributes are:
• Number of minutes
This attribute restricts the lifetime of the logon token.
• Number of logons
This attribute restricts the number of times that the logon token can be used to
log on to Crystal Enterprise.
Crystal Enterprise Administrator’s Guide
57
Active trust relationship
Both attributes hinder malicious users from gaining unauthorized access to Crystal
Enterprise with logon tokens retrieved from legitimate users.
Ticket mechanism for distributed security
Enterprise systems dedicated to serving a large number of users typically require some
form of distributed security. An enterprise system may require distributed security,
for instance, to support features such as load balancing, stateless environments, or
transfer of trust (the ability to allow another component to act on behalf of the user).
Crystal Enterprise addresses distributed security by implementing a ticket
mechanism (one that is similar to the Kerberos ticket mechanism). The CMS grants
tickets that authorize components to perform actions on behalf of a particular user.
In Crystal Enterprise, the ticket is referred to as the logon token.
This logon token is most commonly used over the Web. When a user is first
authenticated by Crystal Enterprise, he or she receives a logon token from the
CMS. The user’s web browser caches this logon token. When the user makes a new
request, other Crystal Enterprise components can read the logon token from the
user’s web browser.
This use of the logon token provides the distributed security that is required for
load balancing to be implemented in conjunction with effective fault-protection. For
instance, suppose that you are running one web server and two Web Component
Servers, and each of the three components is running on a separate machine. The
Web Connector is installed on the web server, so as to direct all Crystal Enterprise
requests to the Web Component Servers. By default, the Web Connector balances
all Crystal Enterprise traffic across the two Web Component Servers: when a user
first connects to Crystal Enterprise, the Web Connector passes the logon request to
whichever Web Component Server has the most resources available. If the log on is
successful, the user is granted a logon token and an active identity on the system.
The user’s active identity is stored as a session variable on the Web Component
Server that processed the request; consequently, the user’s active identity is not
immediately accessible by the other Web Component Server. For this reason, the
Web Connector uses the user’s logon token to route all of the user’s requests to the
Web Component Server that is storing the user’s session. By doing so, the Web
Connector maintains security while providing optimal performance: the user’s
identity is verified, but the system does not have to repeatedly prompt the user for
his or her credentials; in addition, the user is prevented from unnecessarily
consuming resources on both Web Component Servers.
If the Web Component Server that is storing the user’s active session is taken
offline, the logon token again serves a critical purpose. If one Web Component
Server ceases to respond to a user’s requests, the Crystal Enterprise web desktop
and the CMC are designed such that the Web Connector is instructed to redirect
the request to the remaining Web Component Server. The client application logs
the user on with the valid logon token, and the remaining Web Component Server
58
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
is able to authenticate the user and create a new, active session without prompting
the user for his or her credentials. The remaining Web Component Server can then
authorize and carry out the user’s request. In this way, the logon token enables the
system’s load-balancing and fault-tolerance mechanisms to maintain a secure
environment without affecting the user’s experience.
In this scenario, when the original Web Component Server is brought back online,
the Web Connector automatically resumes its load-balancing responsibilities by
routing each subsequent request to the least used Web Component Server.
Sessions and session tracking
In general, a session is a client-server connection that enables the exchange of
information between the two computers. A session’s state is a set of data that
describes the session’s attributes, its configuration, or its content. When you
establish a client-server connection over the Web, the nature of HTTP limits the
duration of each session to a single page of information; thus, your web browser
retains the state of each session in memory only for as long as any single Web page
is displayed. As soon as you move from one web page to another, the state of the
first session is discarded and replaced with the state of the next session.
Consequently, Web sites and Web applications must somehow store the state of
one session if they need to reuse its information in another.
Crystal Enterprise uses two common methods to store session state: cookies and
session variables. A cookie is a small text file that stores session state on the client
side: the user’s web browser caches the cookie for later use. The Crystal Enterprise
logon token is an example of this method. A session variable is a portion of memory
that stores session state on the server side. When Crystal Enterprise grants a user
an active identity on the system, information such as the user’s authentication type
is stored in a session variable. So long as the session is maintained, the system
neither has to prompt the user for the information a second time nor has to repeat
any task that is necessary for the completion of the next request.
Ideally, the system should preserve the session variable while the user is active on the
system. And, to ensure security and to minimize resource usage, the system should
destroy the session variable as soon as the user has finished working on the system.
However, because the interaction between a web browser and a web server can be
stateless, it can be difficult to know when users leave the system, if they do not log
off explicitly. To address this issue, Crystal Enterprise implements session tracking.
WCS session tracking
The WCS implements session tracking similarly to most web servers. The serverside script pages (Crystal Server Pages) programmatically save variables to the
WCS session. By default, the WCS retains the session until the user explicitly logs
off, or until 20 minutes after the user’s last request (whichever occurs first).
Crystal Enterprise Administrator’s Guide
59
Environment protection
Note:
• If you are familiar with the SDK, you should note that a WCS session is an
instance of an InfoStore object.
• The WCS session timeout can be programmatically configured in the serverside .csp pages to timeout earlier if the default of 20 minutes is not desired.
CMS session tracking
The CMS implements a simple tracking algorithm. When a user logs on, he or she
is granted a CMS session, which the CMS preserves until the user logs off, or until
the WCS session variable is released.
The WCS session is designed to notify the CMS on a recurring basis that it is still
active, so the CMS session is retained so long as the WCS session exists. If the WCS
session fails to communicate with the CMS for a ten-minute time period, the CMS
destroys the CMS session. This handles scenarios where client-side components
shut down irregularly.
Note: If you are familiar with the SDK, you should note that a CMS session is an
instance of an EnterpriseSession object.
Environment protection
Environment protection refers to the security of the overall environment in which
client and server components communicate. Although the Internet and web-based
systems are increasingly popular due to their flexibility and range of functionality, they
operate in an environment that can be difficult to secure. When you deploy Crystal
Enterprise, environment protection is divided into two areas of communication:
• Web browser to web server
• Web server to Crystal Enterprise
Web browser to web server
When sensitive data is transmitted between the web browser and the web server,
some degree of security is usually required. Relevant security measures usually
involve two general tasks:
• Ensuring that the communication of data is secure.
• Ensuring that only valid users retrieve information from the web server.
These tasks are typically handled by web servers through various security
mechanisms, including the Secure Sockets Layer (SSL) protocol, Windows NT
Challenge/Response authentication, and other such mechanisms.
You must secure communication between the web browser and the web server
independently of Crystal Enterprise. For details on securing client connections,
refer to your web server documentation.
60
Crystal Enterprise Administrator’s Guide
5: Crystal Enterprise Security Concepts
Web server to Crystal Enterprise
Firewalls are commonly used to secure the area of communication between the
web server and the rest of the corporate intranet (including Crystal Enterprise).
Crystal Enterprise supports firewalls that use IP filtering, static network address
translation (NAT), or SOCKS proxy servers, and it supports a multitude of
configurations. Supported environments can involve multiple firewalls, web
servers, or Web Component Servers.
For complete details on Crystal Enterprise and firewall interaction, see “Working
with Firewalls” on page 367.
Auditing web activity
Crystal Enterprise provides insight into your system by recording web activity and
allowing you to inspect and to monitor the details. The WCS allows you to select
the web attributes—such as time, date, IP address, port number, and so on—that
you want to record. The auditing data is logged to disk and stored in commadelimited text files, so you can easily report off the data or import it into other
applications. For more information, see “Configuring properties for the Web
Component Server” on page 279.
Protection against malicious logon attempts
No matter how secure a system is, there is often at least one location that is
vulnerable to attack: the location where users connect to the system. It is nearly
impossible to protect this location completely, because the process of simply
guessing a valid user name and password remains a viable way to attempt to
“crack” the system.
Crystal Enterprise implements several techniques to reduce the probability of a
malicious user achieving access to the system. The various restrictions listed below
apply only to Enterprise accounts—that is, the restrictions do not apply to accounts
that you have mapped to an external user database (Windows NT, LDAP, or
Windows AD). Generally, however, your external system will enable you to place
similar restrictions on the external accounts.
Password restrictions
Password restrictions ensure that Enterprise users create passwords that are
relatively complex. You can enable the following options:
• Enforce mixed-case passwords
This option ensures that passwords contain at least two of the following
character classes: upper case letters, lower case letters, numbers, or punctuation.
Crystal Enterprise Administrator’s Guide
61
Protection against malicious logon attempts
• Must contain at least N characters
By enforcing a minimum complexity for passwords, you decrease a malicious
user’s chances of simply guessing a valid user’s password.
Logon restrictions
Logon restrictions serve primarily to prevent dictionary attacks (a method
whereby a malicious user obtains a valid user name and attempts to learn the
corresponding password by trying every word in a dictionary). With the speed of
modern hardware, malicious programs can guess millions of passwords per
minute. To prevent dictionary attacks, Crystal Enterprise has an internal
mechanism that enforces a time delay (0.5–1.0 second) between logon attempts. In
addition, Crystal Enterprise provides several customizable options that you can
use to reduce the risk of a dictionary attack:
• Disable accounts after N failed attempts to log on
• Reset failed logon count after N minute(s)
• Re-enable account after N minute(s)
User restrictions
User restrictions ensure that Enterprise users create new passwords on a regular
basis. You can enable the following options:
• Must change password every N day(s)
• Cannot reuse the N most recent password(s)
• Must wait N minute(s) to change password
These options are useful in a number of ways. Firstly, any malicious user
attempting a dictionary attack will have to recommence every time passwords
change. And, because password changes are based on each user’s first logon time,
the malicious user cannot easily determine when any particular password will
change. Additionally, even if a malicious user does guess or otherwise obtain
another user’s credentials, they are valid only for a limited time.
Guest account restrictions
By default, users who are logged on under the Guest account also have the ability
to sign up and create their own, new accounts on the system. The Guest account
restrictions allow you to disable this default behavior. For details, see “Disabling
the Sign Up feature” on page 24.
The Crystal Enterprise authentication provider supports anonymous Single Sign
On for the Guest account. Thus, when users connect to Crystal Enterprise without
specifying a user name and password, the system logs them on automatically
under the Guest account. If you assign a secure password to the Guest account, or
if you disable the Guest account entirely, you disable this default behavior. For
details, see “Disabling the Guest account” on page 25.
62
Crystal Enterprise Administrator’s Guide
Managing User Accounts and Groups
6
This chapter describes the tasks related to account
management for users and groups. It includes instructions
that describe how to add, modify, and remove accounts
within Crystal Enterprise. It also details how to use and
integrate NT, LDAP, and AD authentication with Crystal
Enterprise.
Crystal Enterprise Administrator’s Guide
63
What is account management?
What is account management?
Account management can be thought of as all of the tasks related to creating,
mapping, changing, and organizing user and group information. The Users and
Groups management areas of the Crystal Management Console (CMC) provide
you with a central place to perform all of these tasks.
In the Users area, you can specify everything required for a user to access Crystal
Enterprise. To create user accounts, specify the following:
• Account name (required)
• Full name
• Email
• Description
• Password settings
• Connection type
• Group membership
In the Groups area, you can create groups that give a number of people access to
the report or folder. This enables you to make changes in one place instead of
modifying each user account individually. To create groups, specify the following:
• Group name (required)
• Description
• Users who belong to the group
• Subgroups that belong to the group
• Group membership
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 “Controlling users’ access to objects” on page 142.
Crystal Enterprise default users and groups
This section lists and describes the different types of default users and groups that
are found within Crystal Enterprise. 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).
Default users
There are two default users included with Crystal Enterprise: Administrator and
Guest. These users and any new users (created or mapped users) are members of
a group or groups. For procedures on managing users, see “Managing Enterprise
and general accounts” on page 67.
64
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Administrator
The Administrator user belongs to the Administrators and Everyone groups. This
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). By default,
the administrator is not assigned a password. To assign a password, see “Setting
the Administrator password” on page 24.
Guest
The Guest user is a member of the Everyone group. This user can view reports that are
found within the Report Samples folder. Generally, the Guest user accesses reports
through the Crystal Enterprise web desktop. This account is enabled by default. To
disable this default setting, see “Disabling the Guest account” on page 74.
Note: If users in multiple time zones use the Guest account, see “Supporting users
in multiple time zones” on page 405.
Default groups
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. For procedures on managing groups, see “Managing Enterprise
and general accounts” on page 67.
Administrators
Users who belong to the Administrators group are able to perform all tasks in all
of the Crystal Enterprise applications (Crystal Management Console, Crystal
Configuration Manager, Crystal Publishing Wizard, and the Crystal Enterprise
web desktop).
Note: To use the Crystal Configuration Manager, you may be required to have
additional rights on the local machine. For more information, see “Working with
the Crystal Configuration Manager” on page 22.
Everyone
Each user is a member of the Everyone group by default. Users are able to access
all of the Crystal Enterprise applications. By default, the Everyone group allows
access to all the reports that are found in the Report Samples folder.
Crystal Enterprise Administrator’s Guide
65
Available authentication types
New Sign-Up Accounts
Users who belong to the New Sign-up Accounts group have created their own
accounts through the sign-up feature in the Crystal Enterprise web desktop. See
“Disabling the Sign Up feature” on page 73 if you would like to disable this signup feature.
By default, members of this group are able to view reports specified by the
administrator and perform report and folder tasks. The purpose of this group is to
enable automatic tracking of users who have signed themselves up through the
sign-up feature in the Crystal Enterprise web desktop.
Note: Members of the New Sign-Up Accounts group also belong to the Everyone
group. If you restrict access to the New Sign-Up accounts group, ensure that the
change is also made for the Everyone group. You can also restrict access by
specifying the Advanced rights for the New Sign-Up Accounts group. For more
information on rights, see “Setting advanced object rights” on page 146.
Default Windows NT group
When you install Crystal Enterprise on Windows NT/2000, by default, Crystal
Enterprise creates a Crystal NT Users group—this group is also added to Windows
NT/2000.
Crystal NT Users
When NT authentication is enabled, Crystal NT Users can use their NT accounts to
log on to Crystal Enterprise. By default, members of this group are able to view
folders and reports.
Available authentication types
Before setting up user accounts and groups within Crystal Enterprise, decide
which of the three 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 “Managing Enterprise and
general accounts” on page 67.
• Windows NT authentication
If 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
66
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
the need to recreate individual user and group accounts within Crystal
Enterprise. For more information, see “Managing NT accounts” on page 74.
• LDAP authentication
If 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 “Managing LDAP accounts” on page 84.
• Windows AD authentication
If 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 “Managing AD accounts” on page 95.
Note: You can use Enterprise Authentication in conjunction with either NT,
LDAP, or AD authentication, or with all of the three authentication plug-ins.
Managing Enterprise and general accounts
Since Enterprise authentication is the default authentication method for Crystal
Enterprise, it is automatically enabled when you first install Crystal Enterprise.
When you add and manage users and groups, Crystal Enterprise maintains the
user and group information within its database.
This section focuses on the following account management tasks:
• “Creating an Enterprise user account” on page 68
• “Modifying a user account” on page 69
• “Deleting a user account” on page 69
• “Changing password settings” on page 70
• “Creating a group” on page 71
• “Modifying a group” on page 72
• “Viewing group members” on page 73
• “Deleting a group” on page 73
• “Disabling the Sign Up feature” on page 73
• “Disabling the Guest account” on page 74
• “Granting access to users and groups” on page 74
Note: In many cases, these procedures also apply to NT, LDAP, and AD account
management. For specific information on NT authentication, see “Managing NT
accounts” on page 74. For specific information on LDAP authentication, see
“Managing LDAP accounts” on page 84. For specific information on AD
authentication, see “Managing AD accounts” on page 95.
Crystal Enterprise Administrator’s Guide
67
Managing Enterprise and general accounts
Creating an Enterprise user account
When you create a new user, you specify the user’s properties and select the group
or groups for the user. For information on setting rights for the user, see “Granting
access to users and groups” on page 74.
To create a user account
Creating a user account is made up of two processes: defining the property
information, and adding the user to a group or groups.
Defining the property information
1 Go to the Users management area of the CMC.
2 Click New User.
3 Select the Enterprise authentication type.
4 Type the account name, full name, email, and description information.
Use the description area to include extra information about the user or account.
5 Specify the password information and settings. Options include:
• Password
Enter the password and confirm. This is the initial password that you
assign to the user. The maximum password length is 64 characters.
• Password never expires
Select the check box.
• User must change password at next logon
This check box is selected by default. If you do not want to force users to
change the password the first time they log on, clear the check box.
• User cannot change password
Select the check box.
6 Select the connection type.
• Concurrent User
Choose Concurrent user if this user belongs to a license agreement that
states the number of users allowed to be connected at one time.
• Named User
Choose Named user if this user belongs to a license agreement that
associates a specific user with a license. Named user licenses are useful for
people who require access to Crystal Enterprise regardless of the number of
other people who are currently connected.
7 Click OK.
The “Member of” and “Rights” tabs appear for the user. (For more information
on setting Rights, see “Controlling User Access” on page 141.)
68
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Adding the user to groups
1 Click the Member of tab to specify the group or groups the user should belong to.
Note: By default, all Crystal Enterprise users of the system are part of the
Everyone group.
2 Click the Member of button to view the available groups.
3 In the Available groups area, select the group(s) that the new user should be a
member of.
Use SHIFT+click or CTRL+click to select multiple groups.
4 Click the > arrow to add the group(s); click the < arrow to remove the group(s).
5 Click OK.
The “Member of” tab appears and lists the groups in which the user is a member.
Modifying a user account
Use this procedure to modify a user’s properties or group membership.
Note: The user will be affected if he or she is logged on when you are making the
change.
To modify a user account
1 Go to the Users management area of the CMC.
2 Under Account Name, click the link to the user whose properties you want to
change.
3 Make the required changes, as necessary, in the available fields.
In addition to all of the options that were available when you initially created
the account, you now can disable the account by selecting the “Account is
disabled” check box. You can also assign aliases—for more information, see
“Using account aliases for NT” on page 80, “Using account aliases for LDAP”
on page 92, or “Using account aliases for AD” on page 99.
4 Click Update.
Deleting a user account
Use this procedure to delete a user’s account. The user might receive an error if
they are logged on when their account is deleted.
Tip: You can also delete users with the User Administrative Tool. You can also use
this tool to reassign a user’s objects to another user. The User Administrative Tool
is available from the Administrative Tools area in the Crystal Enterprise Admin
Launchpad.
Crystal Enterprise Administrator’s Guide
69
Managing Enterprise and general accounts
To delete a user account
Use the delete function to remove the account permanently. If you think the user
might require access to the account again in the future, select the “Account is
disabled” check box in the Properties page of the selected user. For procedural
information, see “Modifying a user account” on page 69.
1 Go to the Users management area of the CMC.
2 Select the check box associated with the user you want to delete.
3 Click Delete.
The delete confirmation dialog box appears.
4 Click OK.
The user account is deleted.
Note: If your implementation supports the sign-up feature, users who have had
their accounts deleted are able to create a new account for themselves in the
Crystal Enterprise web desktop.
Changing password settings
Within the Crystal Management Console, you can change the password settings
for a specific user or for all users in the system. For information, see “Protection
against malicious logon attempts” on page 61.
The various restrictions listed below apply only to Enterprise accounts—that is, the
restrictions do not apply to accounts that you have mapped to an external user
database (Windows NT, LDAP, or Windows AD). Generally, however, your
external system will enable you to place similar restrictions on the external accounts.
To change user password settings
1 Go to the Users management area of the CMC.
2 Click the user whose password settings you want to change.
The Properties tab appears.
3 Select or clear the check box associated with the password setting you wish to
change.
The available options are:
• Password never expires
• User must change password at next logon
• User cannot change password
4 Click Update.
To change password settings
1 Go to the Authentication management area of the CMC.
2 Click the Enterprise tab.
70
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
3 Select the check box and enter the value related to the password setting.
The table below identifies the minimum and maximum values for each of the
settings you can configure:
Password Setting
Minimum
Recommended
Maximum
Must contain at least N characters
0 characters
64 characters
Must change password every N days
1 day
100 days
Cannot reuse the N most recent passwords
1 password
100 passwords
Must wait N minutes to change password
0 minutes
100 minutes
Disable account after N failed attempts to log on 1 failed
100 failed
Reset failed logon count after N minutes
1 minute
100 minutes
Re-enable account after N minutes
0 minutes
100 minutes
4 Click Update.
Creating a group
Groups are collections of users who share the same account privileges. For instance,
you may create groups that are based on department, role, or location. Groups
enable you to make changes in one place (a group) instead of modifying each user
account individually. Also, you can assign object rights to a group or groups. For
information on object rights, see “Managing objects overview” on page 178. For
information on granting users and groups administrative rights to other groups,
see “Granting access to users and groups” on page 74.
After creating a new group, you can add users, add subgroups, or specify group
membership so that the new group is actually a subgroup. Because subgroups
provide you with additional levels of organization, they are useful when you set
object rights to control users’ access to your Crystal Enterprise content.
To create a new group
1 Go to the Groups management area of the CMC.
2 Click New Group.
3 On the Properties tab, enter the group name and description.
4 Click OK.
Adding users
1 Click the Users tab.
2 Click Add Users.
Crystal Enterprise Administrator’s Guide
71
Managing Enterprise and general accounts
3 Select the users to add to the group; then click the > arrow.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
4 Click OK.
The Users tab appears. It lists all of the users who belong to this group.
Adding subgroups
1 Click the Subgroups tab.
2 Click Add/Remove Subgroups.
3 Select the groups that should be members of this new group; then click the > arrow.
4 Click OK.
Specifying group membership
1 Click the Member of tab.
2 Click the Member of button.
3 Select the parent groups that this new group will be a member of; then click
the > arrow.
Any rights associated with the parent group will be inherited by the new group
you have created.
4 Click OK.
Modifying a group
You can modify a group by making changes to any of the settings.
Note: The users who belong to the group will be affected by the modification if
they are logged on when you are making changes.
To modify a group
1 Go to the Groups management area of the CMC.
2 Under the Group Name column, click the link to the group whose configuration
you want to change.
3 Make the necessary changes in one of the four tabs:
• Properties
• Users
• Subgroups
• Member of
72
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
4 Depending on which tab you have selected, click OK or Update after you have
made your changes.
Viewing group members
You can use this procedure to view the users who belong to a specific group.
To view group members
1 Go to the Groups management area of the CMC.
2 Under Group Name, click the desired group.
3 Click Users.
4 Click Refresh.
Note: It may take a few minutes for your list to refresh if you have a large
number of users in the group or if your group is mapped to an NT user
database, LDAP user directory, or AD user directory.
Deleting a group
You can delete a group when that group is no longer required.
Note: The users who belong to the group will be affected by the change if they are
logged on when the group is deleted.
To delete a group
1 Go to the Groups management area of the CMC.
2 Select the check box associated with the group you want to delete.
3 Click Delete.
The delete confirmation dialog box appears.
4 Click OK.
Disabling the Sign Up feature
When users connect to the Crystal Enterprise web desktop without specifying a
user name and password, the system logs them on automatically under the Guest
account. By default, each user then can sign up and create a new account on the
system. You have the option to change this default behavior and to prevent guest
users from creating their own accounts.
To disable the Sign Up feature
1 Go to the Authentication management area of the CMC.
2 Click the Enterprise tab.
Crystal Enterprise Administrator’s Guide
73
Managing NT accounts
3 In the “Guest Account Restrictions” area, clear the “Guest” users can create
their own Enterprise accounts check box.
4 Click Update.
Disabling the Guest account
By disabling the Guest account, you ensure that no one can log on to Crystal
Enterprise with this account. By disabling the Guest account, you also disable the
anonymous Single Sign On functionality of Crystal Enterprise, so users will be
unable to access the Crystal Enterprise web desktop without providing a valid user
name and password.
To disable the Guest account
1 Go to the Users management area of the CMC.
2 In the Account Name column, click Guest.
3 On the Properties tab, select the Account is disabled check box.
4 Click Update.
5 If you are prompted for confirmation, click OK.
Granting access to users and groups
You can grant users and groups administrative access to other users and groups.
Administrative rights include: viewing, editing, and deleting objects; viewing and
deleting object instances; and pausing object instances. For example, for
troubleshooting and system maintenance, you may want to grant your IT
department access to edit and delete objects.
For more information about granting rights to users and groups, see “Controlling
access to users and groups” on page 175.
Managing NT accounts
This section provides an overview of NT authentication and the tasks related to
managing it. For information on how NT authentication works in conjunction with
Crystal Enterprise, see “Windows NT security plug-in” on page 52.
Note:
• NT authentication only works for servers running on Windows systems. If you
install Crystal Enterprise on a Windows NT/2000 machine, NT authentication
is installed and enabled by default.
• NT accounts refer to both Windows NT and 2000 accounts.
74
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Mapping NT accounts
To simplify administration, Crystal Enterprise supports user and group accounts
that are created using Windows NT/2000. However, before users can use their NT
user name and password to log on to Crystal Enterprise, their NT user account
needs to be mapped to Crystal Enterprise. When you map an NT account, you can
choose to create a new Crystal Enterprise account or link to an existing Crystal
Enterprise account.
There are two ways to map NT accounts to Crystal Enterprise: you can use either
the User Manager in Windows NT or Computer Management in Windows 2000,
or you can use the Crystal Management Console in Crystal Enterprise.
To map NT users and groups using Windows NT
1 From the Windows Administrative Tools program group, click User Manager.
Note: Ensure that you have selected the domain that contains the Crystal NT
Users group.
2 Select the Crystal NT Users group.
Note: The Crystal NT Users group is created automatically in Windows NT/
2000 when you install Crystal Enterprise on Windows NT/2000.
3 From the User menu, click Properties.
4 Click Add.
5 Select the group(s) and/or user(s); then click Add.
6 Click OK to add the group(s) and/or user(s).
7 Click OK to complete the process.
Tip: Users will now be able to log on to the Crystal Enterprise web desktop
using their NT account if they use the following format:
\\NTDomainName\NTusername or
\\NTMachineName\LocalUserName
Users do not have to specify the NT Domain Name if it is specified in the
“Default NT Domain” field on the Windows NT tab.
To map NT users and groups using Windows 2000
1 From the Windows Administrative Tools program group, click Computer
Management.
2 Under System Tools, select Local Users and Groups.
3 Click the Groups folder.
4 Select the Crystal NT Users and from the Action menu, select Properties.
5 Click Add.
6 Select the group(s) and/or user(s); then click Add.
Crystal Enterprise Administrator’s Guide
75
Managing NT accounts
7 Click OK to add the group(s) and/or user(s).
8 Click OK or Apply (and then Close) to complete the process.
Tip: Users will now be able to log on to the Crystal Enterprise web desktop
using their NT account if they use the following format:
\\NTDomainName\NTusername or
\\NTMachineName\LocalUserName
Users do not have to specify the NT Domain Name if it is specified in the
“Default NT Domain” field on the Windows NT tab.
To map NT users and groups using Crystal Enterprise
Before starting this procedure, ensure you have the NT domain and group
information.
1 Go to the Authentication management area of the CMC.
2 Click the Windows NT tab.
3 Ensure that the NT Authentication is enabled check box is selected.
4 To change the Default NT domain, click the domain name. Complete the
Default NT Domain field.
76
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Note: By typing the default NT Domain Name, users do not have to specify the
NT Domain Name when they log on to Crystal Enterprise via NT authentication.
5 In the Mapped NT Member Groups area, enter the NT domain\group in the
Add NT Group (NT Domain\Group) field.
Note: If you want to map a local NT group, you must type
\\NTmachinename\groupname.
6 Click Add.
The group is added to the list.
7 New Alias Options allow you to specify how NT aliases are mapped to Enterprise
accounts. Select either:
• Assign each added NT alias to an account with the same name
Use this option when you know users have an existing Enterprise account
with the same name; that is, NT aliases will be assigned to existing users
(auto alias creation is turned on). Users who do not have an existing
Enterprise account, or who do not have the same name in their Enterprise
and NT account, are added as new NT users.
or
• Create a new account for every added NT alias
Use this option when you want to create a new account for each user. If the
user has already created an account through the sign-up feature in the
Crystal Enterprise web desktop, the user will have separate NT and
Enterprise accounts.
8 Update Options allow you to specify if NT aliases are automatically created for
all new users. Select either:
• New aliases will be added and new users will be created
Use this option to automatically create a new alias for every NT user
mapped to Crystal Enterprise. New NT accounts are added for users
without Crystal Enterprise accounts, or for all users if you selected the
“Create a new account for every added NT alias” option.
or
• No new aliases will be added and new users will not be created
Use this option when the NT directory you are mapping contains many
users, but only a few of them will use Crystal Enterprise. Crystal Enterprise
does not automatically create aliases and Enterprise accounts for all users.
Instead, it creates aliases (and accounts, if required) only for users who log
on to Crystal Enterprise.
9 New User Options allow you to specify properties of the new Enterprise
accounts that are created to map to NT accounts. Select either:
• New users are created as named users
New user accounts are configured to use named user licenses. Named user
licenses are associated with specific users and allow people to access the
system based on their user name and password. This provides named users
Crystal Enterprise Administrator’s Guide
77
Managing NT accounts
with access to the system regardless of how many other people are
connected. You must have a named user license available for each user
account created using this option.
• New users are created as concurrent users
New user accounts are configured to use concurrent user licenses.
Concurrent licenses specify the number of people who can connect to
Crystal Enterprise at the same time. This type of licensing is very flexible
because a small concurrent license can support a large user base. For
example, depending on how often and how long users access Crystal
Enterprise, a 100 user concurrent license could support 250, 500, or 700 users.
10 Click Update.
A message appears stating that it will take several seconds to update the
member groups.
11 Click OK.
Unmapping NT users and groups
Similar to mapping, it is possible to unmap users and groups using the administrative
tool in Windows NT/2000, or Crystal Enterprise.
To unmap NT users and groups using Windows NT
1 From the Administrative Tools program group, click User Manager.
2 Select Crystal NT Users.
3 From the User menu, click Properties.
4 Select the user(s) or group(s); then click Remove.
5 Click OK.
The user or group will no longer be able to access Crystal Enterprise.
Note: The only exceptions to this occur when a user has an alias to an
Enterprise account, or if your implementation allows users to create their own
accounts through the sign-up feature. To restrict access, disable or delete the
user’s Enterprise account and disable the ability for guests to add users
anonymously. For more information, see “Managing Enterprise and general
accounts” on page 67.
To unmap NT users and groups using Windows 2000
1 From the Administrative Tools program group, click Computer Management.
2 Under System Tools, select Local Users and Groups.
3 Click the Groups folder.
78
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
4 Select Crystal NT Users.
5 From the Action menu, click Properties.
6 Select the user(s) or group(s); then click Remove.
7 Click OK or Apply (and then Close) to complete the process.
The user or group will no longer be able to access Crystal Enterprise.
Note: The only exceptions to this occur when a user has an alias to an
Enterprise account, or if your implementation allows users to create their own
accounts through the sign-up feature. To restrict access, disable or delete the
user’s Enterprise account and disable the ability for guests to add users
anonymously. For more information, see “Managing Enterprise and general
accounts” on page 67.
To unmap NT groups using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the Windows NT tab.
3 In the Mapped NT Member Groups area, select the NT group you would like
to remove.
4 Click Delete.
5 Click Update.
The users in this group will not be able to access Crystal Enterprise.
Tip: To deny NT Authentication for all groups, clear the “NT Authentication is
enabled” check box and click Update.
Note: The only exceptions to this occur when a user has an alias to an
Enterprise account, or if your implementation allows users to create their own
accounts through the sign-up feature. To restrict access, disable or delete the
user’s Enterprise account and disable the ability for guests to add users
anonymously. For more information, see “Managing Enterprise and general
accounts” on page 67.
To unmap NT users using Crystal Enterprise
1 Go to the Users management area of the CMC.
2 Click the name of the user whose account you want to unmap.
3 On the Properties tab, for the user’s NT alias clear the Enabled check box.
4 Click Update.
This user can no longer log on using NT authentication. To further restrict
access, disable or delete the user’s other aliases, their Enterprise account, and
disable the ability for guests to add users anonymously. For more information,
see “Managing Enterprise and general accounts” on page 67.
Crystal Enterprise Administrator’s Guide
79
Managing NT accounts
Viewing mapped NT users and groups in Crystal Enterprise
There are two methods to view mapped users and groups in Crystal Enterprise.
The method you use depends on the way the groups and users have been mapped.
To view users and groups that have been added using Windows NT/2000
or Crystal Enterprise
1 Go to the Groups management area of the CMC.
2 If you added users and groups through Windows NT/2000, then click Crystal
NT Users.
If you added users and groups through the CMC, then select the appropriate
group.
3 Click the Users tab.
4 Click OK to the message which states that accessing the user list may take
several seconds.
5 Click Refresh.
6 Click OK.
To view users and groups that have been added using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the Windows NT tab.
The “Mapped NT Member Groups” area displays the groups that have been
mapped to Crystal Enterprise.
Note: You can view the groups and users by selecting the appropriate group
from the Groups management area and then clicking the Users tab.
Using account aliases for NT
If a user has multiple accounts in Crystal Enterprise, you can link them using the
assign alias feature. This is useful when you are aware of a user who has an NT
account mapped to Enterprise and an Enterprise account. By using an alias, the
user is able to use either an NT user name and password or an Enterprise user
name and password to log on. Thus, an alias enables a user to log on via more than
one authentication type.
You can also reassign an alias in Crystal Enterprise. For example, when you map
your NT accounts to Crystal Enterprise, if an alias is auto-mapped incorrectly, you
can use the Reassign Alias feature to update the mapped account information. This
occurs when the NT user name is different from the Enterprise account user name;
that is, if a user has the name “Test User 1” in NT and the name “1234 User Test” in
Crystal Enterprise, the auto-mapping feature (when you map your NT account to
Crystal Enterprise) will not assign “Test User 1” the “1234 User Test” alias. This
scenario only occurs when you choose the “Assign each added NT alias to an account
with the same name” option when you map your NT accounts to Crystal Enterprise.
80
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
This section describes how to assign an NT alias, reassign an NT alias, and view
alias information.
To assign an NT alias
1 Go to the Users management area of the CMC.
2 Select the user you want to create an alias for.
3 Click the Assign Alias button.
4 Select the appropriate NT alias or aliases.
5 Click the > arrow.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
6 Click OK.
Note: If the user you choose from the Available aliases list has only one
assigned alias, you will receive a message asking you to confirm that you wish
to continue. By continuing, the user’s account will be deleted.
The Properties tab appears with the new alias listed. By default, NT, LDAP, AD,
and Enterprise authentication methods are available.
To reassign an NT alias
1 Go to the Users management area of the CMC.
2 Select the user whose alias you would like to change.
3 Click the Reassign Alias button.
Note: If there is only one alias for the user, you will receive a message asking
you to confirm that you wish to continue.
4 Click either Assign the Alias to a new user or select an existing user.
Note:
• If you choose to assign the alias to a different user, and the original user has
only one NT alias and does not have other aliases, the user’s account and
original favorites folder will be deleted. As a result, the user will not be able
to access any reports that used to be in the original favorites folder.
• When you assign an alias, you are moving an alias to the current user; when
you reassign an alias, you are moving the alias away from the current user.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
Crystal Enterprise Administrator’s Guide
81
Managing NT accounts
5 Click OK.
To view alias information
1 In the Account Management area, click Users.
2 Select the user whose alias information you would like to view.
The bottom portion of the properties page contains the alias information. A user
can have any combination of Crystal Enterprise aliases, NT aliases, LDAP
aliases, or AD aliases. A Crystal Enterprise alias is generated when a new
account is created. An NT alias is created when users are mapped from NT to
Crystal Enterprise. Users will have both a Crystal Enterprise alias and an NT
alias when their NT accounts have been assigned to a Crystal Enterprise user.
Troubleshooting NT accounts
Creating a new NT user account
• If you create a new NT user account, and the account does not belong to a
group account that is mapped to Crystal Enterprise, add it to Crystal
Enterprise. For more information, see “Mapping NT accounts” on page 75.
• If you create a new NT user account, and the account belongs to a group account
that is mapped to Crystal Enterprise, refresh the user list. For more information,
see “Viewing mapped NT users and groups in Crystal Enterprise” on page 80.
Creating a new NT group account
• If you create a new NT group account, and the group account does not belong
to a group account that is mapped to Crystal Enterprise, add it to Crystal
Enterprise. For more information, see “Mapping NT accounts” on page 75.
• If you create a new NT group account, and the account belongs to a group account
that is mapped to Crystal Enterprise, refresh the group list. For more information,
see “Viewing mapped NT users and groups in Crystal Enterprise” on page 80.
Disabling an NT user account
• If you disable an NT user account (using Windows Administrative Tools), the
user will not be able to log on to Crystal Enterprise using the mapped NT
account. However, if the user also has an account that uses Enterprise
authentication, the user can still access Crystal Enterprise using that account.
Disabling an NT group account
• If you disable an NT group account (using Windows Administrative Tools),
the users who belong to that group will not be able to log on to Crystal
Enterprise using their mapped NT accounts. However, those users who also
have an account that uses Enterprise authentication will still be able to log on
to Crystal Enterprise.
82
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Setting up NT Single Sign On
You can configure Crystal Enterprise to allow users to use various Crystal
Enterprise applications without being prompted to log on. Users need only to enter
their NT user name and password information once at the beginning of the NT
session. For instance, if you have set up NT Single Sign On, when you launch the
CMC, NT authentication occurs in the background. You are not required to enter
any additional information.
Note: This feature is available if you are using a Microsoft Internet Information
Server (IIS) web server and users are using Internet Explorer as their web
browser. See the Platforms.txt file included with your product distribution for a
complete list of version requirements.
Crystal Enterprise provides its own form of “anonymous Single Sign On,” which
uses Enterprise authentication, as opposed to Windows NT authentication. Design
your own web applications accordingly (or modify the Crystal Enterprise web
desktop) if you want to use NT Single Sign On. By default, when a user launches
Crystal Enterprise, he or she will be automatically logged on using the Guest
account (Enterprise authentication). You can disable this feature—for more
information, see “Disabling the Sign Up feature” on page 73. However, even when
you disable the Sign Up feature, Crystal Enterprise is designed to display a logon
page. With Single Sign On enabled, the user can select Windows NT from the
Authentication list and click Log On without entering his or her user name or
password. In the developer documentation, refer to the tutorial for an example on
creating a web application that uses Single Sign On.
Setting up NT Single Sign On involves two processes:
• Configuring the IIS web server
Using the documentation included with your IIS server, change the access and
authentication settings for the Enterprise virtual directory. Disable the settings
for allowing “Anonymous access” and “Basic authentication” options. Ensure
that the setting for Windows NT Challenge/Response (also referred to as
Integrated Windows authentication) is enabled.
Note: Crystal Enterprise does not support the Kerberos protocol.
• Configuring the Web Component Server
Use the Crystal Configuration Manager (CCM) to configure the Web
Component Server.
To configure the Web Component Server using the CCM
1 From the Crystal Enterprise program group, click Crystal Configuration
Manager.
Note: To use the CCM, you must have NT administrator rights on the local
machine. If you are managing servers on a remote machine, you must also
have NT administrator rights on the machine you are connecting to.
Crystal Enterprise Administrator’s Guide
83
Managing LDAP accounts
Depending on the configuration of your network, you might be prompted to
enter a user name and password.
2 Select the Crystal Web Component Server; then click the Stop button.
3 Either double-click the Crystal Web Component Server or right-click the
Crystal Web Component Server and select Properties.
4 Click the Configuration tab.
5 Select the Use Windows NT Integrated security check box.
6 Click OK.
7 Restart the Web Component Server by selecting the Crystal Web Component
Server and then clicking the Start button.
Managing LDAP accounts
Since Enterprise authentication is the default authentication method for Crystal
Enterprise, it is automatically enabled when you first install Crystal Enterprise.
When you add and manage users and groups, Crystal Enterprise maintains the user
and group information within its database. To use LDAP authentication, you need
to first ensure that you have your respective LDAP directory set up. For more
information about LDAP, refer to your LDAP documentation. For more information
on the LDAP security plug-in, see “LDAP security plug-in” on page 53.
Note: When you install Crystal Enterprise, the LDAP authentication plug-in is
installed automatically, but not enabled by default.
84
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Configuring LDAP authentication and mapping LDAP accounts
To simplify administration, Crystal Enterprise supports LDAP authentication for
user and group accounts. Before users can use their LDAP user name and
password to log on to Crystal Enterprise, you need to map their LDAP account to
Crystal Enterprise. When you map an LDAP account, you can choose to create a
new Crystal Enterprise account or link to an existing Crystal Enterprise account.
Before setting up and enabling LDAP authentication, ensure that you have your
LDAP directory set up. For more information, refer to your LDAP documentation.
To set up LDAP authentication using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the LDAP tab, and then click “Start LDAP Configuration Wizard”.
The LDAP Configuration Wizard will lead you through the setup of LDAP
authentication, step by step.
3 The first screen of the wizard asks for information about your LDAP host.
Type your LDAP host and port information in the Add LDAP host
(hostname:port) field (for example, “myserver:123”); then click Add.
Repeat this step to add more than one LDAP host of the same server type if you
want to add hosts that can act as failover servers. If you want to remove a host,
highlight the host name and click Delete. For more information on multiple
hosts, refer to “Managing multiple LDAP hosts” on page 92.
4 Click Next.
5 Select your server type from the LDAP Server Type list. Click Show Attribute
Mappings if you want to view or change any of the LDAP Server Attribute
Mappings or the LDAP Default Search Attributes.
By default, each supported server type’s server attribute mappings and search
attributes are already set.
6 Click Next.
7 In the Base LDAP Distinguished Name field, type the distinguished name
(for example, o=SomeBase).
8 Click Next.
9 Enter the credentials required by the LDAP hosts.
• In the “LDAP Server Administration Credentials” area, type the distinguished
name and password for a user account that is authorized to administer your
LDAP server.
If your LDAP Server allows anonymous binding, leave this area blank—Crystal
Enterprise servers and clients will bind to the primary host via anonymous logon.
• Enter another distinguished name and password in the “LDAP Referral
Credentials” area if all of the following apply:
• The primary host has been configured to refer to another directory server
that handles queries for entries under a specified base.
Crystal Enterprise Administrator’s Guide
85
Managing LDAP accounts
• The host being referred to has been configured to not allow anonymous
binding.
• A group from the host being referred to will be mapped to Crystal Enterprise.
Although groups can be mapped from multiple hosts, only one set of referral
credentials can be set. Therefore if you have multiple referral hosts, you must
create a user account on each host that uses the same distinguished name and
password.
10 Enter the number of referral hops in the Maximum Referral Hops field.
If this field is set to zero, no referrals will be followed.
11 Click Next.
12 Select the type of SSL authentication (none, Server Authentication, or Mutual
Authentication) your LDAP hosts uses to establish a connection with Crystal
Enterprise. Click Next.
13 If you selected Server Authentication or Mutual Authentication, choose one of
the following options:
• Always accept server certificate
This is the lowest security option. Before Crystal Enterprise can establish an
SSL connection with the LDAP host (to authenticate LDAP users and
groups), it must receive a security certificate from the LDAP host. Crystal
Enterprise does not verify the certificate it receives.
• Accept server certificate if it comes from a trusted Certificate Authority
This is a medium security option. Before Crystal Enterprise can establish an
SSL connection with the LDAP host (to authenticate LDAP users and
groups), it must receive and verify a security certificate sent to it by the
LDAP host. To verify the certificate, Crystal Enterprise must find the
Certificate Authority that issued the certificate in its certificate database.
Tip: Java applications (such as the Java version of the Crystal Enterprise web
desktop) always use this option, regardless of the setting you choose.
• Accept server certificate if it comes from a trusted Certificate Authority and
the CN attribute of the certificate matches the DNS hostname of the server
This is the highest security option. Before Crystal Enterprise can establish
an SSL connection with the LDAP host (to authenticate LDAP users and
groups), it must receive and verify a security certificate sent to it by the
LDAP host. To verify the certificate, Crystal Enterprise must find the
Certificate Authority that issued the certificate in its certificate database. It
must also be able to confirm that the CN attribute on the server certificate
exactly matches the host name of the LDAP host as you typed it in the
“Add LDAP host” field in the first step of the wizard. That is, if you entered
the LDAP host name as ABALONE.rd.crystald.net:389, using CN
=ABALONE:389 in the certificate would not work.
Tip: The host name on the server security certificate is the name of the primary
LDAP host. Therefore if you select this option you cannot use a failover LDAP host.
86
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
14 In the SSL host box, you must next add the host name of each machine in your
Crystal Enterprise system that uses the Crystal Enterprise SDK. (This includes
the machine running your Crystal Management Server and the machine
running your Web Component Server or your Web Component Adapter.)
Type the host name of each machine in the SSL Host box, and then click Add.
15 Now configure the SSL settings for each SSL host in the list, starting with the
default host.
• To select settings for the default host, first clear the Use default value boxes.
Then type your values for the path to the certificate and key database files, the
password for the key database. Type a nickname for the client certificate in the
cert7.db if you selected mutual authentication.
The settings for the default host are used:
• for any setting (for any host) where you leave the “Use default value” box
checked.
• for any machine whose name you do not explicitly add to the list of SSL hosts.
• To select settings for another host, select its name in the list on the left. Then
type the appropriate values in the boxes on the right.
16 Click Next.
17 The next screen of the wizard controls how Crystal Enterprise maps LDAP
users to Crystal Enterprise users.
New Alias Options allow you to specify how LDAP aliases are mapped to
Enterprise accounts. Select either:
• Assign each added LDAP alias to an account with the same name
Use this option when you know users have an existing Enterprise account
with the same name; that is, LDAP aliases will be assigned to existing users
Crystal Enterprise Administrator’s Guide
87
Managing LDAP accounts
(auto alias creation is turned on). Users who do not have an existing
Enterprise account, or who do not have the same name in their Enterprise
and LDAP account, are added as new LDAP users.
or
• Create a new account for every added LDAP alias
Use this option when you want to create a new account for each user. If the
user has already created an account through the sign-up feature in Crystal
Enterprise, the user will have separate LDAP and Enterprise accounts.
18 Update Options allow you to specify if LDAP aliases are automatically created
for all new users. Select either:
• New aliases will be added and new users will be created
Use this option to automatically create a new alias for every LDAP user
mapped to Crystal Enterprise. New LDAP accounts are added for users
without Crystal Enterprise accounts, or for all users if you selected the
“Create a new account for every added LDAP alias” option.
or
• No new aliases will be added and new users will not be created
Use this option when the LDAP directory you are mapping contains many
users, but only a few of them will use Crystal Enterprise. Crystal Enterprise
does not automatically create aliases and Enterprise accounts for all users.
Instead, it creates aliases (and accounts, if required) only for users who log
on to Crystal Enterprise.
19 New User Options allow you to specify properties of the new Enterprise
accounts that are created to map to LDAP accounts. Select either:
• New users are created as named users
New user accounts are configured to use named user licenses. Named user
licenses are associated with specific users and allow people to access the
system based on their user name and password. This provides named users
with access to the system regardless of how many other people are
connected. You must have a named user license available for each user
account created using this option.
• New users are created as concurrent users
New user accounts are configured to use concurrent user licenses. Concurrent
licenses specify the number of people who can connect to Crystal Enterprise
at the same time. This type of licensing is very flexible because a small
concurrent license can support a large user base. For example, depending on
how often and how long users access Crystal Enterprise, a 100 user
concurrent license could support 250, 500, or 700 users.
20 Click Finish to save your LDAP settings.
The LDAP Server Summary page appears.
88
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Mapping LDAP groups
Once you have configured LDAP authentication using the LDAP configuration
wizard, you can map LDAP groups to Enterprise groups.
To map LDAP groups using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the LDAP tab.
If LDAP authorization is configured, the LDAP summary page appears.
3 In the “Mapped LDAP Member Groups” area, specify your LDAP group
(either by common name or distinguished name) in the Add LDAP group (by
cn or dn) field; click Add.
You can add more than one LDAP group by repeating this step. To remove a
group, highlight the LDAP group and click Delete.
4 Click Update.
Unmapping LDAP users and groups
Similar to mapping, it is possible to unmap users and groups using Crystal
Enterprise.
Crystal Enterprise Administrator’s Guide
89
Managing LDAP accounts
To unmap LDAP groups using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the LDAP tab.
If LDAP authorization is configured, the LDAP summary page will appear.
3 In the “Mapped LDAP Member Groups” area, select the LDAP group you
would like to remove.
4 Click Delete.
5 Click Update.
The users in this group will not be able to access Crystal Enterprise.
Tip: To deny LDAP Authentication for all groups, clear the “LDAP
Authentication is enabled” check box and click Update.
Note: The only exceptions to this occur when a user has an alias to an
Enterprise account, or if your implementation allows users to create their own
accounts through the sign-up feature. To restrict access, disable or delete the
user’s Enterprise account and disable the ability for guests to add users
anonymously. For more information, see “Managing Enterprise and general
accounts” on page 67.
To unmap LDAP users using Crystal Enterprise
1 Go to the Users management area of the CMC.
2 Click the name of the user whose account you want to unmap.
3 On the Properties tab, for the user’s LDAP alias clear the Enabled check box.
4 Click Update.
This user can no longer log on using LDAP authentication. To further restrict
access, disable or delete the user’s other aliases, their Enterprise account, and
disable the ability for guests to add users anonymously. For more information,
see “Managing Enterprise and general accounts” on page 67. To restrict access
for this user
Viewing mapped LDAP users and groups in Crystal Enterprise
You can view your LDAP mapped groups in Crystal Enterprise by clicking the
LDAP tab (located in the Authentication management area). If LDAP
authorization is configured, the Mapped LDAP Member Groups area displays the
LDAP groups that have been mapped to Crystal Enterprise.
90
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Changing LDAP connection parameters and member groups
After you have configured LDAP authentication using the LDAP configuration
wizard, you can change LDAP connection parameters and member groups using
the LDAP Server Configuration Summary Page. To access this page, go to the
Authentication area of the Crystal Management Console and then click the LDAP
tab. (For information on configuring LDAP authentication using the LDAP
configuration wizard, see “Configuring LDAP authentication and mapping LDAP
accounts” on page 85.)
On the LDAP Server Configuration Summary page, you can change any of the
connection parameter areas or fields:
• LDAP Hosts
• LDAP Server Type
• Base LDAP Distinguished Name
• LDAP Server Administration Credentials
• LDAP Referral Credentials
• Maximum Referral Hops
• SSL Type
• New Alias options
• Update Alias options
• New User options.
You can also modify the Mapped LDAP Member Groups area.
To change connection settings
1 Delete currently mapped groups that will no longer be accessible under the
new connection settings.
2 Click Update.
3 Change your connection settings.
4 Click Update.
5 Change your Alias and New User options.
6 Click Update.
7 Map your new LDAP member groups.
8 Click Update.
Crystal Enterprise Administrator’s Guide
91
Managing LDAP accounts
Managing multiple LDAP hosts
Using LDAP and Crystal Enterprise, you can add fault tolerance to your system by
adding multiple LDAP hosts. Crystal Enterprise uses the first host that you add as
the primary LDAP host. Subsequent hosts are treated as failover hosts.
The primary LDAP host and all failover hosts must be configured in exactly the
same way, and each LDAP host must refer to all additional hosts from which you
wish to map groups. For more information about LDAP hosts and referrals, see
your LDAP documentation.
To add multiple LDAP Hosts, enter all hosts when you configure LDAP using the
LDAP configuration wizard (see “Configuring LDAP authentication and mapping
LDAP accounts” on page 85 for details.) Or if you have already configured LDAP,
go to the Authentication management area of the Crystal Management Console
and click the LDAP tab. In the LDAP Server Configuration Summary area, click the
name of the LDAP host to open the page that enables you to add or delete hosts.
Note:
• The order in which the hosts are communicated with matters, so ensure that
you add the primary host first, followed by the remaining failover hosts.
• If you use failover LDAP hosts, you cannot use the highest level of SSL
security (that is, you cannot select “Accept server certificate if it comes from a
trusted Certificate Authority and the CN attribute of the certificate matches the
DNS hostname of the server.”) For more information, see “Configuring LDAP
authentication and mapping LDAP accounts” on page 85.
Using account aliases for LDAP
If a user has multiple accounts in Crystal Enterprise, you can link them using the
assign alias feature. This is useful when you are aware of a user who has an LDAP
account mapped to Enterprise and an Enterprise account. The user is able to use
either an LDAP user name and password or an Enterprise user name and
password to log on. Thus, an alias enables a user to log on via more than one
authentication type.
You can also reassign an alias in Crystal Enterprise. For example, when you map
your LDAP accounts to Crystal Enterprise, if an alias is auto-mapped incorrectly,
you can use the Reassign Alias feature to update the mapped account information.
This occurs when the LDAP user name is different from the Enterprise account
user name; that is, if a user has the name “Test User 1” in LDAP and the name
“1234 User Test” in Crystal Enterprise, the auto-mapping feature (when you map
your LDAP account to Crystal Enterprise) will not assign “Test User 1” the “1234
User Test” alias. This scenario only occurs when you choose the “Assign each
added LDAP alias to an account with the same name” option when you map your
LDAP accounts to Crystal Enterprise.
92
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
This section describes how to assign an LDAP alias, reassign an LDAP alias, and
view alias information.
To assign an LDAP alias
1 Go to the Users management area of the CMC.
2 Select the user you want to create an alias for.
3 Click Assign Alias.
4 Select the appropriate LDAP alias or aliases.
5 Click the > arrow.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
6 Click OK.
Note: If the user you choose from the Available aliases list has only one
assigned alias, you will receive a message asking you to confirm that you wish
to continue. By continuing, the user’s account will be deleted.
The Properties tab appears with the new alias listed.By default, NT, LDAP, AD,
and Enterprise authentication methods are available.
To reassign an LDAP alias
1 Go to the Users management area of the CMC.
2 Select the user whose alias you would like to change.
3 Click Reassign Alias.
Note: If there is only one alias for the user, you will receive a message asking
you to confirm that you wish to continue.
4 Click either Assign the Alias to a new user or select an existing user.
Note:
• If you choose to assign the alias to a different user, and the original user has
only one LDAP alias and does not have other aliases, the user’s original
favorites folder will be deleted. As a result, the user will not be able to
access any reports that used to be in the original favorites folder.
• When you assign an alias, you are moving an alias to the current user; when
you reassign an alias, you are moving the alias away from the current user.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+Click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
Crystal Enterprise Administrator’s Guide
93
Managing LDAP accounts
5 Click OK.
To view alias information
1 In the Account Management area, click Users.
2 Select the user whose alias information you would like to view.
The bottom portion of the properties page contains the alias information. A user
can have any combination of Crystal Enterprise aliases, LDAP aliases, AD
aliases, or NT aliases. A Crystal Enterprise alias is generated when a new account
is created. An LDAP alias is created when users are mapped from LDAP to
Crystal Enterprise. Users will have both a Crystal Enterprise alias and an LDAP
alias when their LDAP accounts have been assigned to a Crystal Enterprise user.
Troubleshooting LDAP accounts
Creating a new LDAP user account
• If you create a new LDAP user account, and the account does not belong to a
group account that is mapped to Crystal Enterprise, add it to Crystal
Enterprise. For more information, see “Configuring LDAP authentication and
mapping LDAP accounts” on page 85.
• If you create a new LDAP user account, and the account belongs to a group
account that is mapped to Crystal Enterprise, refresh the user list. For more
information, see “Viewing mapped LDAP users and groups in Crystal
Enterprise” on page 90.
Creating a new LDAP group account
• If you create a new LDAP group account, and the group account does not
belong to a group account that is mapped to Crystal Enterprise, add it to
Crystal Enterprise. For more information, see “Configuring LDAP
authentication and mapping LDAP accounts” on page 85.
• If you create a new LDAP group account, and the account belongs to a group
account that is mapped to Crystal Enterprise, refresh the group list. For more
information, see “Viewing mapped LDAP users and groups in Crystal
Enterprise” on page 90.
Disabling an LDAP user account
• If you disable an LDAP user account, and that LDAP user account is mapped
to Crystal Enterprise, the user will not be able to log on to Crystal Enterprise.
However, if the user also has an account that uses Enterprise authentication,
the user can still access Crystal Enterprise using that account.
94
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Disabling an LDAP group account
• If you disable an LDAP group account, and that LDAP group account is
mapped to Crystal Enterprise, the users who belong to that group will not be
able to log on to Crystal Enterprise. However, if the user also has an account
that uses Enterprise authentication, the user can still access Crystal Enterprise
using that account.
Managing AD accounts
This section provides an overview of AD authentication and the tasks related to
managing it. For information on how AD authentication works in conjunction with
Crystal Enterprise, see “Windows AD security plug-in” on page 55.
Once you have mapped your AD users and groups, all of the Crystal Enterprise client
tools support AD authentication, except for the Crystal Import Wizard. You can also
create your own applications that support AD authentication. For more information,
see the developer documentation available on your product CD.
Note:
• AD authentication only works for servers running on Windows systems.
• AD authentication and aggregation is not functional without a network
connection.
• Users cannot log on to Crystal Enterprise using AD authentication via the Java
SDK.
• AD authentication and aggregation may not continue to function if the
administration credentials become invalid (for example, if the administrator
changes his or her password or if the account becomes disabled).
Mapping AD accounts
To simplify administration, Crystal Enterprise supports AD authentication for user
and group accounts. However, before users can use their AD user name and
password to log on to Crystal Enterprise, their AD user account needs to be mapped
to Crystal Enterprise. When you map an AD account, you can choose to create a
new Crystal Enterprise account or link to an existing Crystal Enterprise account.
To map AD accounts to Crystal Enterprise, use the Crystal Management Console
(CMC) in Crystal Enterprise.
To map AD users and groups
Before starting this procedure, ensure that you have the appropriate AD domain and
group information. As well, you must have created a domain user account on your
AD server for Crystal Enterprise to use when authenticating AD users and groups.
1 Go to the Authentication management area of the CMC.
Crystal Enterprise Administrator’s Guide
95
Managing AD accounts
2 Click the Windows AD tab.
3 Ensure that the Windows Active Directory Authentication is enabled check
box is selected.
4 In the “AD Administration Credentials” area, enter the name and password of
the domain user account you’ve set up on your AD server for Crystal
Enterprise to use when authenticating AD users and groups.
Administration credentials can use one of the following formats:
• NT name (DomainName\UserName)
• UPN (user@DNS_domain_name)
Administration credentials must be entered to enable AD authentication, map
groups, check rights, and so on.
5 Complete the Default AD Domain field.
A default domain must be entered to enable AD authentication and map groups.
96
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
Note:
• Groups from the default domain can be mapped without specifying the
domain name prefix.
• By entering the Default AD Domain name, users do not have to specify the AD
domain name when they log on to Crystal Enterprise via AD authentication.
6 In the “Mapped AD Member Groups” area, enter the AD domain\group in
the Add AD Group (Domain\Group) field.
Groups can be mapped using one of the following formats:
• NT name (DomainName\GroupName)
• DN (cn=GroupName, ......, dc=DomainName, dc=com)
Note: If you want to map a local group, you can use only the NT name format
(\\ServerName\GroupName).
7 Click Add.
The group is added to the list.
8 New Alias Options allow you to specify how AD aliases are mapped to
Enterprise accounts. Select either:
• Assign each added AD alias to an account with the same name
Use this option when you know users have an existing Enterprise account
with the same name; that is, AD aliases will be assigned to existing users
(auto alias creation is turned on). Users who do not have an existing
Enterprise account, or who do not have the same name in their Enterprise
and AD account, are added as new AD users.
or
• Create a new account for every added AD alias
Use this option when you want to create a new account for each user. If the
user has already created an account through the sign-up feature in Crystal
Enterprise, the user will have separate AD and Enterprise accounts.
9 Update Options allow you to specify if AD aliases are automatically created
for all new users. Select either:
• New aliases will be added and new users will be created
Use this option to automatically create a new alias for every AD user
mapped to Crystal Enterprise. New AD accounts are added for users
without Crystal Enterprise accounts, or for all users if you selected the
“Create a new account for every added AD alias” option.
or
• No new aliases will be added and new users will not be created
Use this option when the AD directory you are mapping contains many
users, but only a few of them will use Crystal Enterprise. Crystal Enterprise
does not automatically create aliases and Enterprise accounts for all users.
Instead, it creates aliases (and accounts, if required) only for users who log
on to Crystal Enterprise.
Crystal Enterprise Administrator’s Guide
97
Managing AD accounts
10 New User Options allow you to specify properties of the new Enterprise
accounts that are created to map to AD accounts. Select either:
• New users are created as named users
New user accounts are configured to use named user licenses. Named user
licenses are associated with specific users and allow people to access the
system based on their user name and password. This provides named users
with access to the system regardless of how many other people are
connected. You must have a named user license available for each user
account created using this option.
• New users are created as concurrent users
New user accounts are configured to use concurrent user licenses.
Concurrent licenses specify the number of people who can connect to
Crystal Enterprise at the same time. This type of licensing is very flexible
because a small concurrent license can support a large user base. For
example, depending on how often and how long users access Crystal
Enterprise, a 100 user concurrent license could support 250, 500, or 700 users.
11 Click Update.
A message appears stating that it will take several seconds to update the
member groups.
12 Click OK.
Unmapping AD users and groups
Similar to mapping, it is possible to unmap users and groups using Crystal Enterprise.
To unmap AD groups using Crystal Enterprise
1 Go to the Authentication management area of the CMC.
2 Click the Windows AD tab.
3 In the “Mapped AD Member Groups” area, select the AD group you would
like to remove.
4 Click Delete.
5 Click Update.
The users in the deleted group will no longer be able to access Crystal
Enterprise.
Tip: To deny AD authentication for all users, clear the “Windows Active
Directory Authentication is enabled” check box and click Update.
Note: The only exceptions to this occur when a user has an alias other than the
one assigned for AD authentication, or if your implementation allows users to
create their own accounts through the sign-up feature. To restrict access,
disable or delete the user’s Enterprise account and disable the ability for guests
to add users anonymously. For more information, see “Managing Enterprise
and general accounts” on page 67.
98
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
To unmap AD users using Crystal Enterprise
1 Go to the Users management area of the CMC.
2 Click the name of the user whose account you want to unmap.
3 On the Properties tab, for the user’s AD alias clear the Enabled check box.
4 Click Update.
This user can no longer log on using AD authentication. To further restrict
access, disable or delete the user’s other aliases, their Enterprise account, and
disable the ability for guests to add users anonymously. For more information,
see “Managing Enterprise and general accounts” on page 67.To restrict access
for this user
Viewing mapped AD users and groups in Crystal Enterprise
1 Go to the Groups management area of the CMC.
2 Under Group Name, click the hyperlink to a Windows AD group
3 Click the Users tab.
Note: You can view the groups by clicking the Windows AD tab from the
Authentication management area and then viewing the “Mapped AD Member
Groups” area; users cannot be viewed from the Windows AD tab.
Using account aliases for AD
If a user has multiple accounts in Crystal Enterprise, you can link the user's multiple
aliases using the assign alias feature (that is, have one user with multiple aliases).
This is useful when you are aware of a user who has an AD account mapped to
Enterprise and an Enterprise account. By using an alias, the user is able to use either
an AD user name and password or an Enterprise user name and password to log
on. Thus, an alias enables a user to log on via more than one authentication type.
You can also reassign an alias in Crystal Enterprise. For example, after you map
your AD accounts to Crystal Enterprise, you can use the Reassign Alias feature to
assign a different alias for a user.
This section describes how to assign an AD alias, reassign an AD alias, and view
alias information.
To assign an AD alias
1 Go to the Users management area of the CMC.
2 Select the user you want to assign an alias for.
3 Click the Assign Alias button.
4 Select the appropriate AD alias or aliases.
5 Click the > arrow.
Crystal Enterprise Administrator’s Guide
99
Managing AD accounts
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
6 Click OK.
Note: If the user you choose from the Available aliases list has only one
assigned alias, you will receive a message asking you to confirm that you wish
to continue. By continuing, the user’s account and original favorites folder will
be deleted. As a result, the user will not be able to access any reports that used
to be in the original favorites folder. If the user has another alias, such as an
LDAP alias, the user’s account and original favorites folder will not be deleted.
The Properties tab appears with the new alias listed. By default, NT, LDAP, AD,
and Enterprise authentication methods are available.
To reassign an AD alias
1 Go to the Users management area of the CMC.
2 Select the user whose alias you would like to reassign.
3 Click the Reassign Alias button.
Note:
• If there is only one alias for the user, you will receive a message asking you
to confirm that you wish to continue.
• If you choose to assign the alias to a different user, and the original user has
only one AD alias and does not have other aliases, the user’s account and
original favorites folder will be deleted. As a result, the user will not be able
to access any reports that used to be in the original favorites folder. If the
user has another alias, such as an LDAP alias, the user’s account and
original favorites folder will not be deleted.
4 Click either Assign the Alias to a new user or select an existing user.
Note: When you assign an alias, you are moving an alias to the current user;
when you reassign an alias, you are moving the alias away from the current
user.
Tip:
• To select multiple users, use the SHIFT+click or CTRL+click combination.
• To search for a specific user, use the Look For field.
• If there are many users on your system, click the Previous and Next buttons
to navigate through the list of users.
5 Click OK.
100
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
To view alias information
1 In the Account Management area, click Users.
2 Select the user whose alias information you would like to view.
The bottom portion of the properties page contains the alias information. A user
can have any combination of Crystal Enterprise aliases, NT aliases, LDAP
aliases, or AD aliases. A Crystal Enterprise alias is generated when a new
Enterprise account is created. An AD alias is created when users are mapped
from AD to Crystal Enterprise (or when the AD Alias Generator tool is run).
Users will have both a Crystal Enterprise alias and an AD alias when their AD
accounts have been assigned to a Crystal Enterprise user.
Troubleshooting AD accounts
Creating a new AD user account
• If you create a new AD user account, and the account belongs to a group
account that is mapped to Crystal Enterprise, ensure that you update the user
list by clicking Update in the Windows AD tab found in the Authentication
management area. Note that you must click Update to ensure that new users
are imported properly. For information on viewing AD users and groups, see
“Viewing mapped AD users and groups in Crystal Enterprise” on page 99.
• User accounts are automatically created for AD users who are added to an AD
group when these users successfully log on to Crystal Enterprise.
Adding an AD group account to a mapped AD group
• When you add an AD group account to an AD group that was previously
mapped to Crystal Enterprise, and you would like the users of this nested
group to get imported into Crystal Enterprise, you need to click Update in the
Windows AD tab (found in the Authentication management area).
Note: The nested AD group will not get mapped to Crystal Enterprise by this
operation.
Disabling an AD user account
• If you disable an AD user account (using Windows Administrative Tools), and
that AD user account is mapped to Crystal Enterprise, the user will not be able
to log on to Crystal Enterprise. However, if the user has any other valid alias or
aliases, the user can log on using the respective authentication method (for
example, Enterprise authentication).
Crystal Enterprise Administrator’s Guide
101
Managing AD accounts
Using AD Single Sign On
Installation of Active Directory Plug-in for Crystal Enterprise 10 updates your
WCS and enables you with the option of using AD Single Sign On (SSO). However,
for AD SSO to work, the IIS Crystal virtual directory needs to be configured, along
with the Web Component Server.
Note:
• AD SSO is not supported on client machines running on Windows 98.
• By default, AD SSO is not enabled.
Setting up AD Single Sign On involves two processes:
• Configuring the IIS web server
Using the documentation included with your IIS server, change the access and
authentication settings for the Enterprise virtual directory. Disable the settings
for allowing “Anonymous access” and “Basic authentication” options. Ensure
that the setting for Integrated Windows authentication is enabled, and then
restart your IIS server.
Note: Crystal Enterprise does not support the Kerberos protocol.
• Configuring the Web Component Server
Use the Crystal Configuration Manager (CCM) to configure the Web
Component Server.
To configure the Web Component Server using the CCM
1 From the Crystal Enterprise program group, click Crystal Configuration
Manager.
Note: To use the CCM, you must have NT administrator rights on the local
machine. If you are managing servers on a remote machine, you must also
have NT administrator rights on the machine you are connecting to.
Depending on the configuration of your network, you might be prompted to
enter a user name and password.
2 Select the Crystal Web Component Server; then click the Stop button.
3 Either double-click the Crystal Web Component Server or right-click the
Crystal Web Component Server and select Properties.
4 Click the Configuration tab.
102
Crystal Enterprise Administrator’s Guide
6: Managing User Accounts and Groups
5 Select the Use Windows Active Directory Integrated security check box.
6 Click OK.
7 Restart the Web Component Server by selecting the Crystal Web Component
Server and then click the Start button.
Crystal Enterprise Administrator’s Guide
103
Managing AD accounts
104
Crystal Enterprise Administrator’s Guide
Managing Folder Objects
7
This chapter describes basic folder administration tasks and
shows how to add folders and how to change settings, such
as object rights and limits, for new folders. Cross-references
are provided to other sections in this guide where
particular topics are covered in greater detail.
Crystal Enterprise Administrator’s Guide
105
Folders overview
Folders overview
Folders 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.
Creating and deleting folders
There are several ways to create new folders in Crystal Enterprise. In the Crystal
Management Console (CMC), go to the Folders management area to create new
folders and to add subfolders to the existing hierarchy of folder objects.
Tip: When you publish local directories and subdirectories of reports with the
Crystal Publishing Wizard, you can duplicate your local directory structure on the
Crystal Enterprise system. This method provides you with an efficient way of
creating multiple folders and subfolders at the same time. For details, see
“Publishing with the Crystal Publishing Wizard” on page 117.
Creating a new folder
This procedure shows how to create a new folder at the top of your folder
hierarchy. Folders created in this way are, in effect, subfolders of the top-level (or
root) Crystal Enterprise folder.
1 Go to the Folders management area of the CMC.
2 Click New Folder.
3 On the Properties tab, type the name and description of the new folder.
This example creates a new Marketing folder:
106
Crystal Enterprise Administrator’s Guide
7: Managing Folder Objects
4 Click OK.
The new folder is added to the system, and its Properties tab is refreshed. You
can now use the Objects, Subfolders, Limits, and Rights tabs to add objects and
to change settings for this folder.
Creating a new subfolder at any level
1 Go to the Folders management area of the CMC.
The initial level of folders is displayed.
2 In the Title column, click the link to the folder where you want to add a subfolder.
3 Click the Subfolders tab.
Tip: You can browse through existing subfolders to add a new folder elsewhere
in the folder hierarchy. When you have found the right parent folder, go to its
Subfolders tab.
The Subfolders tab appears.
4 Click New Folder.
5 On the Properties tab, type the name and description of the new folder.
6 Click OK.
The new folder is added to the system, and its Properties tab is refreshed. You
can now use the Objects, Subfolders, Limits, and Rights tabs to add objects and
to change settings for this folder.
Crystal Enterprise Administrator’s Guide
107
Copying and moving folders
Deleting folders
When you delete a folder, all subfolders, reports, and other objects contained
within it are removed entirely from the system.
To delete folders
1 Go to the Folders management area of the CMC.
2 Select the check box associated with the folder you want to delete.
If the folder you want to delete is not at the top level, locate its parent folder.
Then make your selection on the parent folder’s Subfolders tab.
Tip: Select multiple check boxes to delete several folders from their parent folder.
3 Click Delete, and click OK to confirm.
Copying and moving folders
When you copy or move a folder, the objects contained within it are also copied or
moved. Crystal Enterprise treats the folder’s object rights differently, depending
upon whether you copy or move the folder:
• When you copy a folder, the newly created folder does not retain the object
rights of the original. Instead, the copy inherits the object rights that are set on
its new parent folder. For instance, if you copy a private Sales folder into a
Public folder, the contents of the new Sales folder will be accessible to all users
who have rights to the Public folder.
• When you move a folder, all of the folder’s object rights are retained. For
instance, if you move a private Sales folder into a publicly accessible folder, the
Sales folder will remain inaccessible to most users.
To copy or move a folder
1 Go to the Folders management area of the CMC.
2 Select the check box associated with the folder that you want to copy or move.
If the folder you want to copy or move is not at the top level, locate its parent
folder. Then make your selection on the parent folder’s Subfolders tab.
Tip: Select multiple check boxes to copy or move several folders from their
parent folder to a different folder.
3 Click Copy/Move.
The Copy/Move Folder page appears.
108
Crystal Enterprise Administrator’s Guide
7: Managing Folder Objects
4 Select the action to perform:
• Copy to: Makes a copy of the folder.
• Move to: Moves the folder.
5 Select the Destination folder from the list.
Tip: If there are many folders on your system, use the “Look for” field to search,
or click Previous, Next, and Show Subfolders to browse the folder hierarchy.
6 Click OK.
The folder you selected is copied or moved, as requested, to the new destination.
Adding a report to a new folder
You can add objects individually to any folder in a number of ways. Follow this
procedure to add a report to a new folder that you have just created. For complete
information on publishing reports and other objects, see “Publishing overview” on
page 116.
To add a report to a new folder
1 Once you’ve created the new folder, click its Objects tab.
2 Click New Object.
Crystal Enterprise Administrator’s Guide
109
Adding a report to a new folder
The New Object page appears.
3 On the Report tab, in the File name field, type the full path to the report.
If you do not know the path, click Browse to perform a search.
4 If you do not want the user to see a thumbnail preview of the report in Crystal
Enterprise, clear the Generate thumbnail for the report check box.
Tip: To display thumbnails for a report, open the report in Crystal Reports and
click Summary Info on the File menu. Select the “Save preview picture” check
box and click OK. Preview the first page of the report and save your changes.
5 If the report references objects in your Crystal Repository, select the Use
Object Repository when refreshing report check box to update these objects
now.
For details about setting up the Crystal Repository, see “Crystal Repository
overview” on page 254.
6 Ensure that the correct folder name appears in the Destination field.
Tip: If there are many folders on your system, use the “Look for” field to search,
or click Previous, Next, and Show Subfolders to browse the folder hierarchy.
7 Click OK.
The report is published to Crystal Enterprise.
110
Crystal Enterprise Administrator’s Guide
7: Managing Folder Objects
Specifying folder rights
Follow this procedure to change the object rights for a new folder that you have
just created. By default, new objects that you add to a folder inherit the object rights
that are specified for the folder. For complete information on object rights, see
“Controlling users’ access to objects” on page 142.
To specify rights for a new folder
1 Once you’ve created the new folder, click its Rights tab.
2 Click Add/Remove to add groups or users to this folder.
The Add/Remove page appears.
3 In the Select Operation list, select Add/Remove Groups, Add Users, or
Remove Users.
The page is refreshed and displays options that depend upon whether you are
working with users or with groups. The example above shows the options that
are available when you are working with groups.
4 Select the user/group whose rights you want to specify and click the arrows to
specify whether the user/group does or does not have access to the folder.
Tip: If you have many users on your system, select the Add Users operation;
then use the “Look for” field to search for a particular account.
5 Click OK.
Crystal Enterprise Administrator’s Guide
111
Setting limits for folders, users, and groups
You are returned to the Rights tab.
6 Change the Access Level for each user or group, as required.
Note: For complete details on the predefined access levels and advanced
rights, see “Controlling users’ access to objects” on page 142.
7 Click Update.
Setting limits for folders, users, and groups
Limits allow you to delete report instances on a regular basis. You set limits to
automate regular clean-ups of old Crystal Enterprise content. Limits that you set
on a folder affect all objects that are contained within the folder. At the folder level,
you can limit the number of instances that remain on the system for each object or
for each user or group; you can also limit the number of days that an instance
remains on the system for a user or group.
Follow this procedure to enforce default limits on a folder that you have just
created. For more information on limits, see “Setting instance limits for an object”
on page 246.
To limit instances at the folder level
1 Once you’ve created the new folder, click its Limits tab.
112
Crystal Enterprise Administrator’s Guide
7: Managing Folder Objects
2 Modify the available settings according to the types of instance limits that you
want to implement, and click Update after each change.
The available settings are:
• Delete excess instances when there are more than N instances of an object
To limit the number of instances per object, select this check box. Then type
the maximum number of instances that you want to remain on the system.
(The default value is 100.)
• Delete excess instances for the following users/groups
To limit the number of instances per user or group, click Add/Remove in
this area. Select from the available users and groups and click OK. Then
type the maximum number of instances in the Instance Limit column. (The
default value is 100.)
• Delete instances after N days for the following users/groups
To limit the age of instances per user or group, click Add/Remove in this
area. Select from the available users and groups and click OK. Then type
the maximum age of instances in the Maximum Days column. (The default
value is 100.)
In this example, two settings have been combined to keep a maximum of 50
instances of any object in the folder, and to keep a maximum of 25 instances that
belong to any member of the Administrators group.
Managing User Folders
Crystal Enterprise creates a folder for each user on the system. These folders are
organized within the CMC as User Folders. By default, there are User Folders for
the Administrator and Guest accounts. When you log on to the CMC and view the
list of User Folders, you will see only those folders to which you have View access
(or greater).
Crystal Enterprise Administrator’s Guide
113
Managing User Folders
Within the Crystal Enterprise web desktop, these folders are referred to as the
Favorites folders. When a user logs on to Crystal Enterprise, he or she is redirected
immediately to his or her Favorites folder. (Users can change this default behavior
my modifying their Preferences.)
To view the User Folders
1 Go to the Folders management area of the CMC.
2 Click the User Folders link.
3 If it is not already displayed, click the Subfolders tab.
A list of subfolders appears. Each subfolder corresponds to a user account on
the system. Unless you have View access (or greater) to a subfolder, it will not
appear in the list.
114
Crystal Enterprise Administrator’s Guide
Publishing Objects to Crystal Enterprise
8
This chapter focuses on the publishing process: it
introduces the Crystal Publishing Wizard and tells you
how you can use it to add Crystal reports (RPT and CAR
files) and other objects to the Crystal Enterprise web
desktop or to your custom web desktop; it also describes
alternative ways of adding objects to the Crystal Enterprise
environment.
Crystal Enterprise Administrator’s Guide
115
Publishing overview
Publishing overview
Publishing 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 (RPT and
CAR files), 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.
When you publish an object to Crystal Enterprise, an entry is made in the Crystal
Management Server (CMS) database. The Input File Repository Server stores the new
object below the \Enterprise\FileStore\Input\data\ directory. When a user
schedules an instance of any object, Crystal Enterprise queries the CMS for the location
of the object file; the appropriate server component then retrieves and processes the
object file from the Input File Repository. The processed instance is stored by the
Output File Repository Server below the \Enterprise\FileStore\Output\data\
directory.
Note: Only reports, programs, and object packages can be scheduled. Thus, only
these three types of objects have instances.
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 “Publishing with the Crystal Publishing Wizard” on page 117.
• 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 “Publishing with the Crystal Management Console” on
page 125.
• Save directly to your Enterprise folders when you are:
• Designing reports with Crystal Reports.
• Using the Crystal Analysis Application Designer.
• Creating other objects with Crystal Enterprise plug-in components.
For details, see “Saving objects directly to the CMS” on page 127.
Note: Crystal Enterprise supports reports created in versions 6 through 10 of
Crystal Reports. Once published to Crystal Enterprise, reports are saved,
processed, and displayed in version 10 format.
116
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
Publishing options
During the publishing process, you specify how often an object is run. You can
choose to set a schedule (recurring), or you can choose to let users set the schedule
themselves (on demand).
For RPT report files, this affects when data is refreshed and what data users see
(you cannot schedule Crystal Analysis reports (CAR files)):
• Specifying the data that users see (recurring)
This option is recommended for objects that are accessed by a large number of
people and that do not require separate database logon credentials.
Benefits
• Users view the same instance of the report, reducing the number of times
the database is hit (and thus system resources are used more effectively).
• The report instance is static (contains saved data) and is stored on the
Cache Server, allowing multiple users to access the report at the same time.
Drawbacks
• The report instance the users see is based on the selection criteria (parameters
and record selection formulas) and schedule set by the administrator.
• Allowing users to update the data in the report (on demand)
This option is recommended for smaller reports that use parameters and
selection formulas, require separate database logon credentials, or have
frequent data changes.
Benefits
• Users are able to determine the frequency in which the data in the report is
updated.
Drawbacks
• Multiple users generating reports at the same time increases the load on the
system and the number of times the database is hit.
• Each unique report page is cached separately. It’s possible that the Cache
Server can contain many copies of the cached report, each of them being
generated by hitting the Page Server and database.
Publishing with the Crystal Publishing Wizard
The Crystal Publishing Wizard is a locally installed, 32-bit Windows application.
The wizard is made up of a series of screens. Only the screens applicable to the
objects or folders you are publishing appear. For example, the settings for
parameters and schedule format do not appear when you publish Crystal Analysis
applications. This section of the guide features a series of procedures to help you
through the Crystal Publishing Wizard.
Crystal Enterprise Administrator’s Guide
117
Publishing with the Crystal Publishing Wizard
Once the object has been published, it will appear in the folder you specified in the
Crystal Enterprise web desktop (or other web desktop) and in the Objects
management area of the CMC.
Note: Depending on the rights assigned by your Crystal Enterprise administrator,
you may not be able to publish objects using the Crystal Publishing Wizard.
Logging on to Crystal Enterprise
1 From the Crystal Enterprise 10 program group, click Crystal Publishing
Wizard.
2 Click Next.
3 In the System field, type the name of the CMS to which you want to add
objects.
4 In the User Name and Password fields, type your Crystal Enterprise
credentials.
5 From the Authentication list, select the appropriate authentication type.
6 Click Next.
The Select A File dialog box appears.
Adding objects
1 Depending on the type of object you are adding, click either Add Files or Add
Folders.
2 Navigate to and select the object you want to add.
If you are adding a folder, you can choose to also add its subfolders by selecting
the Include Subfolders check box.
Tip: Ensure the appropriate file type is listed in the Files of type field; by default
this value is set to Report (*.rpt).
3 Repeat steps 1and 2 for each of the objects you want to add.
4 Click Next.
The Folder Hierarchy dialog box appears if it is needed.
Duplicating the folder structure
If you are adding multiple objects from a directory and its subdirectories, you are
asked if you want to duplicate the existing folder hierarchy on the CMS.
1 Click Yes or No.
Click the Yes button to have all of the folders and subfolders recreated on the
CMS as they appear on your hard drive.
118
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
Click the No button to have all of the objects placed in a single folder.
2 Click Next.
The Specify Location dialog box appears.
Creating and selecting a folder on the CMS
To add the selected objects, you must create or select a folder on the host CMS.
Only the folders that you have full control access to will appear.
1 Click the folder you want to add the objects to. Click + to the left of the folder
to view the subfolders.
To add a new folder to the CMS, select a parent folder and then click the New
Folder button. The new folder appears and can be renamed.
To add a new object package to the CMS, select a parent folder and then click
the New Object Package button. The new object package appears and can be
renamed.
To delete a folder or object package, select the item and click the Delete Folder
button.
Note: From the wizard, you can delete only new folders and object packages.
(New folders are green; existing folders are yellow.)
If you are adding multiple objects and want to place them in separate
directories, you can do so in the next section.
2 Click Next.
The Location Preview dialog box appears.
Crystal Enterprise Administrator’s Guide
119
Publishing with the Crystal Publishing Wizard
Moving objects between folders
1 Move objects to the desired folders by selecting each object and then clicking
Move Up or Move Down.
You can also add folders and object packages by selecting a parent folder and
clicking the New Folder or New Object Package button. To delete a folder or object
packages, select it and click the Delete button. You can drag-and-drop objects to
place them where you want. And you can right-click objects to rename them.
By default, objects are displayed using their titles. You can display the objects’
local file names by clicking the “Show file names” button.
2 Click Next when you are finished.
The Schedule Interval dialog box appears if it is needed.
Changing scheduling options
The Schedule Interval dialog box allows you to schedule each report, program,
and/or object package that you are publishing to run at specific intervals.
Note: This dialog box appears only for objects that can be scheduled.
1 Select the object you want to schedule.
2 Select one of three intervals:
• Run once only
Selecting the “Run once only” option provides two more sets of options:
• when finished this wizard
This option runs the object once when you’ve finished publishing it. The
object is not run again until you reschedule it.
120
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
• at the specified date and time
This option runs the object once at a date and time you specify. The object is
not run again until you reschedule it.
• Let users update the object
This option does not schedule the object. Instead, it leaves the task of
scheduling up to the user.
• Run on a recurring schedule
Once you have selected this option, click the Set Recurrence button to set
the scheduling options.
The “Pick a recurrence schedule” dialog box appears.
The options in this dialog box allow you to choose when and how often the
report runs. Select the appropriate options and click the OK button.
3 Click Next after you have set the schedule for each object you are publishing.
Enabling repository refresh
The Crystal Repository is a central location which stores shared report elements
such as text objects, bitmaps, custom functions, and custom SQL commands. You
can choose to refresh an object’s repository fields if the object references the
repository. To complete this task, the Crystal Publishing Wizard needs to connect
to your Crystal Repository database from the local machine. For details, see
“Crystal Repository overview” on page 254.
Note: This dialog box appears only when you publish report objects.
To enable repository refresh
1 Select a report, and then select the Use Object Repository when refreshing
report check box if you want to refresh it against the repository.
Tip: Click the “Enable All” button if you want to refresh all objects that
reference the repository; click the “Disable All” button if you want to refresh
none of the objects.
2 Click Next when you are finished.
Selecting a program type
1 In the Program Type dialog box, select a program.
2 Specify one of three program types:
• Binary/Batch
Binary/Batch programs are executables such as binary files, batch files, or
shell scripts. They generally have file extensions such as: .com, .exe, .bat,
.sh. You can publish any executable program that can be run from the
command line on the machine where the Program Job Server is running.
Crystal Enterprise Administrator’s Guide
121
Publishing with the Crystal Publishing Wizard
• Java
You can publish any Java program to Crystal Enterprise as a Java program
object. They generally have a .jar file extension.
• Script
Script program objects are JScript and VBScript scripts.
3 Once you have specified the type of each program you are adding, click Next.
The Program credentials dialog box appears.
Note: For details about program objects and program object types, see “What are
report objects and instances?” on page 184.
Specifying program credentials
1 In the Program Credentials dialog box, select a program.
2 In the User Name and Password fields, specify the user credentials for the
account for the program to run as.
The rights of the program are limited to those of the account that it runs as.
3 Once you have specified the user credentials for each program to run as, click Next.
The Change Default Values dialog box appears.
Changing default values
You can choose to publish objects without changing any of the default properties,
or you can go through the remaining screens and make changes.
Note: If you use the default values, your object may not schedule properly if the
database logon information is not correct, or if the parameter values are invalid.
If you want to publish objects without making modifications:
1 Select Publish without modifying properties.
2 Click Next through the wizard’s remaining dialog boxes.
If you want to review or modify objects before publishing:
1 Select Review or modify properties.
2 Click Next.
The Review Object Properties dialog box appears.
Changing object properties
1 In the Review Object Properties dialog box, select the object you want to modify.
2 Enter a new title or description.
122
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
3 Select the Generate thumbnail image check box if you want users to see a
thumbnail of a report object before they open it.
Tip: The “Generate thumbnail image” check box is available only if the object
is an RPT file and was saved appropriately. To display thumbnails for a report,
open the report in Crystal Reports and click Summary Info on the File menu.
Select the “Save preview picture” check box and click OK. Preview the first
page of the report and save your changes.
4 Click Next.
The Database Logon Information dialog box appears if it is needed.
Entering database logon information
Some objects use data sources that require logon information. If objects you are
adding are of this type, follow these steps.
1 Double-click the object, or click + to the left of the object to expose the
database.
2 Select the database and change the logon information in the appropriate fields.
If the database does not require a user name or password, leave the fields blank.
Note: Enter user name and password information carefully. If it is entered
incorrectly, the object cannot retrieve data from the database.
3 Once you have completed the logon information for each object using a
different database, click Next.
The Set Report Parameters dialog box appears if it is needed.
Crystal Enterprise Administrator’s Guide
123
Publishing with the Crystal Publishing Wizard
Setting parameters
Some objects contain parameters for data selection. Before such an object can be
scheduled, you must set the parameters in order to determine the default prompts.
1 Select the object whose prompts you want to change.
The object’s prompts and default values appear in a list on the right-hand side
of the screen.
2 Click Edit Prompt to change the value of a prompt.
Depending on the type of parameter you have chosen, different dialog boxes
appear.
3 If you want to set the prompts to contain a null value (where possible), then
click Set Prompts to NULL.
4 Click Next after you have finished editing the prompts for each object.
The Schedule Format dialog box appears.
Setting the schedule format
You can choose a schedule format for each report that you publish. For some of the
formats, you can customize the schedule format options.
1 Select the object whose schedule format you want to change.
2 Select a format from the list (Crystal Report, Excel, Word, and so on).
Where applicable, customize the schedule format options. For example, if you
select Paginated Text, enter the number of lines per page.
3 Click Next.
The Extra files for Program dialog box appears if it is needed.
Adding extra files for programs
Some programs require access to other files in order to run.
1 Select a program.
2 Click Add to navigate to and select the necessary file.
3 Once you have added all necessary extra files for each program, click Next.
The Command line for Program dialog box appears.
Specifying command line arguments
For each program, you can specify any command-line arguments supported by
your program’s command-line interface. They are passed directly to the
command-line interface, without parsing.
1 Select a program.
124
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
2 In the Command line area, type the command-line arguments for your
program, using the same format you would use at the command line itself.
3 Once you have specified all necessary command-line arguments for each
program, click Next.
The final dialog box appears.
Finalizing the objects to be added
1 After ensuring all the objects you want to publish have been added to the list,
click Next.
The objects are added to the CMS, scheduled, and run as specified. When the
processing is done, you are returned to the final screen of the Crystal Publishing
Wizard.
2 To view the details for an object, select it from the list.
3 Click Finish to close the wizard.
Publishing with the Crystal Management Console
If you have administrative rights to Crystal Enterprise, you can publish objects
over the Web from within the CMC.
To add an object with the CMC
1 Go to the Objects management area of the CMC.
2 Click New Object.
The New Object page appears, with the Report properties displayed.
Crystal Enterprise Administrator’s Guide
125
Publishing with the Crystal Management Console
3 On the left side of the page, click the type of object you want to add.
4 Enter the object’s properties.
The properties that appear vary according to the type of object you are adding:
Property
Object Types
Description
File name
Report, Program, Microsoft
Type the full path to the object, or click Browse to
Excel, Microsoft Word,
perform a search.
Microsoft PowerPoint, Adobe
Acrobat, Text, Rich Text
Title
Object Package, Hyperlink
Type the name of the object.
Description
Object Package, Hyperlink
Type a description of the object.
Generate
thumbnail for
the report
Report
If you do not want the user to see a thumbnail
preview of the report in Crystal Enterprise, clear
the “Generate thumbnail for the report” check
box.
Tip: To display thumbnails for a report, open the
report in Crystal Reports and click Summary Info
on the File menu. Select the “Save preview
picture” check box and click OK. Preview the
first page of the report and save your changes.
Use Object
Report
Repository when
refreshing report
Select this option to automatically refresh an
object's repository fields against the repository
each time the report runs.
Program Type
Select Executable, Java, or Script.
Program
Tip:
• Run Java programs as Java program objects.
• Run JScript and VBScript programs as Script
program objects.
• Run all other programs as Executable
program objects.
URL
Hyperlink
Type the URL address of the page you want the
hyperlink object to link to.
5 Ensure that the correct folder or object package name appears in the
Destination field.
Tip:
• To expand a folder, select it and click Show Subfolders.
• To search for a specific folder or object package, use the Look For field.
Note: Only report and program objects can be published to object packages.
6 Click OK.
126
Crystal Enterprise Administrator’s Guide
8: Publishing Objects to Crystal Enterprise
When the object has been added to the system, the CMC displays the Properties
screen. If necessary, you can now modify the object’s properties, such as its title
and description, the database logon information, scheduling information, user
rights, and so on.
Saving objects directly to the CMS
If you have installed one of the Crystal designer components, such as Crystal
Reports or Crystal Analysis, you can use the Save As command to add objects to
Crystal Enterprise from within the designer itself.
For instance, after designing a report in Crystal Analysis, click Save As on the File
menu. In the Save As dialog box, click Enterprise Folders; then, when prompted,
log on to the Crystal Management Server (CMS). Specify the folder where you
want to save the report and click Save.
Crystal Enterprise Administrator’s Guide
127
Saving objects directly to the CMS
128
Crystal Enterprise Administrator’s Guide
Importing Objects to Crystal Enterprise
9
The Crystal Import Wizard allows you to import
information from other Crystal Enterprise or Info systems
into your new Crystal Enterprise system. This chapter
provides a general overview of the Crystal Import Wizard
along with a series of procedures that lead you through the
process of importing information.
Crystal Enterprise Administrator’s Guide
129
Crystal Import Wizard overview
Crystal Import Wizard overview
The Crystal Import Wizard is a locally installed Windows application that allows
you to migrate existing user accounts, groups, folders, and reports to your new
Crystal Enterprise system. The Crystal Import Wizard runs on Windows, but you
can use it to import information to a new Crystal Enterprise system that is running
on Windows or on UNIX.
You can import information from any of these products:
• Info 7.5
• Crystal Enterprise 8
• Crystal Enterprise 8.5
• Crystal Enterprise 9
• Crystal Enterprise 10
The functionality provided by the Crystal Import Wizard varies, depending upon
the product from which you are importing information. In general, the Crystal
Import Wizard imports settings that are specific to each object, rather than global
system settings. For instance, a global “minimum number of characters” password
restriction is not imported. But a user-level “must change password at next log on”
restriction is imported with the user account. For details, see Importing information
from Crystal Enterprise or “Importing information from Info” on page 133.
For procedural details, see “Importing with the Crystal Import Wizard” on
page 135.
Importing information from Crystal Enterprise
If you have upgraded from an earlier version of Crystal Enterprise, use the Crystal
Import Wizard to import existing user accounts, groups, folders, report objects,
and report instances to Crystal Enterprise 10.
You can also use the Crystal Import Wizard to import information from an existing
version 10 installation to a new version 10 installation. When doing so, you have the
additional option of importing calendars, events, repository objects, and server groups.
Events and server groups can also be imported from a version 8.5 or 9 installation.
When using the Crystal Import Wizard, if any of an object’s dependencies are not
imported, the wizard makes appropriate modifications to the object (in most cases,
the dependency is removed). For example, if a user has Full Control rights on an
object, but the user is not imported, the Full Control right for that user is discarded
when the object is imported. In the case of objects brought across without their
owners, the Administrator becomes the new owner of the objects.
As another, more involved example, User A owns an object and has Full Control
rights while User C has View rights on the same object. If User D runs the Crystal
Import Wizard and brings the object across along with User C, but not User A, the
object becomes owned by the Administrator: User A loses Full Control rights, but
User C still has View rights on the object.
130
Crystal Enterprise Administrator’s Guide
9: Importing Objects to Crystal Enterprise
Note: Always import users if you want to bring across the associated rights for an
object, even if the user already exists in the destination system. If the user already
exists, the Crystal Import Wizard maps all rights for the user on the source system
to the existing user on the destination system. If the user is not brought across, all
rights information for that user is discarded.
The following sections describe what happens to the objects that are imported
from a Crystal Enterprise 8.x system. Generally, if the object will not overwrite an
object that is already in the Crystal Enterprise system, then the Crystal Import
Wizard imports the object.
Users and groups
The Crystal Import Wizard imports users and groups and their hierarchical
relationships. A user or group is imported only if it does not exist already by name.
If you import a group that already exists in the destination environment, the list of
group members is updated with any additional users who were members of the
group in the source environment. These additional users are added to Crystal
Enterprise if their accounts do not exist already.
User licensing can affect the behavior of the Crystal Import Wizard. If the source
environment uses Concurrent licensing, the wizard imports all users as Concurrent
Users. However, if the source environment uses Named User licensing, the wizard
first checks the number of Named User license keys in the destination environment.
If there are enough Named User licenses in the destination environment, the wizard
imports all users as Named Users. If there are not enough Named User licenses in
the destination environment, the wizard imports all users as Concurrent Users. For
more information about licensing, see “Licensing overview” on page 408.
Aliases
If a user in the destination system has an alias that is identical to a user who is being
imported, the destination user keeps all aliases, and the imported user loses that
particular alias.
Windows AD
When importing users that employ Windows Active Directory authentication,
ensure that the administrative credentials are the same on both the source and
destination systems. Active Directory authentication must also be enabled on the
destination system.
LDAP
When importing users that employ LDAP authentication, the Host list and Base
LDAP name need to be the same on both the source and destination systems.
LDAP authentication must also be enabled on the destination system.
Crystal Enterprise Administrator’s Guide
131
Crystal Import Wizard overview
Folders
Folders are imported, whether or not they exist already in the destination
environment. To ensure that existing folders are not overwritten, make sure you
choose the “Automatically rename top-level folders that match top-level folders on
the destination system.” option in the “Please choose an import scenario” dialog
box. When this option is selected, the Crystal Import Wizard appends a number to
the end of any duplicated folder names to indicate the number of copies. For
example, if you import a folder called Sales Reports when a folder called Sales
Reports already exists, then the imported folder is added to Crystal Enterprise
with the name Sales Reports(2).
Report objects
The Crystal Import Wizard can import Crystal report objects only if they are based
on native drivers, ODBC data sources, OLAP data sources, or Business Views. You
have the choice to import the report instances for each report object, and the
scheduling patterns that you have set up in the source environment are imported
automatically.
Supported reports are always imported with their parent folders, whether or not
they exist already in the destination environment. However, so as not to overwrite
existing folders, the Crystal Import Wizard appends a number to the end of any
duplicated folder names to indicate the number of copies.
When you import content from one deployment to another, you can ensure that a
particular user account retains ownership of its objects and scheduled instances by
importing the user along with the content. If you don’t import the user account, the
ownership properties of its objects and instances are reset to your current
administrative account. In the SDK, ownership is reflected by an object’s
SI_OWNERID property and by a scheduled instances’s SI_SUBMITTERID properties.
Rights
When you import folders and reports from one Crystal Enterprise system to
another, the associated object rights are imported for every user or group who is
imported at the same time. If the user or group is not imported at the same time,
the object rights are discarded. For instance, suppose that you import a report that
explicitly grants View On Demand rights to the Everyone group in the source
environment—but you do not import the Everyone group. In this case, the newly
imported report in the destination environment will not grant the same explicit
rights to the Everyone group. Instead, the report inherits any rights that have been
set on its parent folder.
If you do import the appropriate user or group, and it already exists by name in
the destination environment, then the corresponding object rights are imported
and applied to the existing user or group. For instance, modifying the example
above, suppose that you import the report and the Everyone group. In this case, the
132
Crystal Enterprise Administrator’s Guide
9: Importing Objects to Crystal Enterprise
Crystal Import Wizard imports the object rights along with the report. So the
newly imported report in the destination environment will explicitly grant the
View On Demand right to the Everyone group.
Events and server groups
When you use the Crystal Import Wizard to import information from a Crystal
Enterprise 8.5 or later system, you have the additional option to import events and
server groups from the source environment.
When importing server groups, the wizard does not bring across the servers that
belong to that group. You need to manually add servers to the imported group in
the Crystal Management Console (CMC). For more information about how to do
this, see “Adding and deleting servers” on page 364.
Note:
• When importing report objects associated with a server group, if the server
group exists on the destination system, the report objects are added to the
existing group and the source system’s server group is not imported.
• If you have jobs scheduled or pending on a server or server group that you are
importing, you might notice odd behavior on the destination system with the
individual jobs involved until they run or time out.
Objects that have server group restrictions lose the restrictions if the objects are
imported and the server group is not. For example, if a report is scheduled to run only
under server group A and that server group is not imported, the report loses that
restriction and will run under any server group. You need to import the server group
at the same time as the objects that use it to keep the relationship between them.
The same logic applies for events: if an object is set up to wait for an event or to
trigger an event, you need to import the event at the same time as the object.
Otherwise, the object is imported without the dependency and no longer waits for,
or triggers, the event.
Note:
• If Event A is being imported from the source system but there is already an
Event A on the destination system, and it is a different type (for example, a File
event instead of a Custom event), the wizard removes the dependency on
Event A from the object when it is imported.
• Events are based on Event Servers and, since servers are not imported, you
need to manually reset the event server and file name information on the event
in the destination system. Once this is set, the event should work as expected.
Importing information from Info
The following sections describe what happens to objects that have been imported
from Info to Crystal Enterprise. Generally, if the Info object is of a type that is
supported within Crystal Enterprise, and if the Info object will not overwrite an
Crystal Enterprise Administrator’s Guide
133
Crystal Import Wizard overview
object that is already in the Crystal Enterprise system, then the Crystal Import
Wizard imports the object.
Note: Users who are accessing your Info implementation when you are importing
objects to Crystal Enterprise might experience a delay.
Users and groups
The Crystal Import Wizard imports users and groups and their hierarchical
relationships as they exist in Info. A user or group is added to Crystal Enterprise
only if it does not exist already by name.
If you import a group that already exists in Crystal Enterprise, the list of group
members is updated with additional users who were members of the Info group. These
additional users are added to Crystal Enterprise if their accounts do not exist already.
User licensing can affect the behavior of the Crystal Import Wizard. If the source
environment uses Concurrent licensing, the wizard imports all users as Concurrent
Users. However, if the source environment uses Named User licensing, the wizard
first checks the number of Named User license keys in the destination environment.
If there are enough Named User licenses in the destination environment, the wizard
imports all users as Named Users. If there are not enough Named User licenses in
the destination environment, the wizard imports all users as Concurrent Users. For
more information about licensing, see “Licensing overview” on page 408.
Folders
Folders are imported, whether or not they exist already in Crystal Enterprise. To
ensure that existing folders are not overwritten, make sure you choose the
“Automatically rename top-level folders that match top-level folders on the
destination system” option in the “Please choose an import scenario” dialog box.
When this option is selected, the Crystal Import Wizard appends a number to the
end of any duplicated folder names to indicate the number of copies. For example,
if you import a folder called Sales Reports, when a folder called Sales Reports
already exists in Crystal Enterprise, then the imported folder is added to Crystal
Enterprise with the name Sales Reports(2).
Report objects
The Crystal Import Wizard can import Crystal report objects only if they are based
on native drivers, ODBC data sources, or OLAP data sources.
Supported reports are always imported with their parent folders, whether or not
they exist already in the destination environment. However, so as not to overwrite
existing folders, the Crystal Import Wizard appends a number to the end of any
duplicated folder names to indicate the number of copies.
The Crystal Import Wizard can import successful instances and some recurring
instances from Info systems. Recurrence patterns that cannot be automatically
134
Crystal Enterprise Administrator’s Guide
9: Importing Objects to Crystal Enterprise
recreated within Crystal Enterprise are written to the log file created by the Crystal
Import Wizard.
When you import reports based on a Crystal Info View, you are prompted to save
the report files. Choose a specific folder where you want to save these reports. You
can then run a conversion utility on all reports in that folder to convert them to use
metadata. After converting the reports, you can publish them to Crystal Enterprise
with the Crystal Publishing Wizard.
Rights
Crystal Enterprise enforces security through object rights, which differ from the
user rights used within Info. Consequently, the Crystal Import Wizard does not
import any of the folder security that is set up within the Info environment.
If you transfer reports from Info to Crystal Enterprise, the rights associated with
the report are not transferred, only the ownership. If the owner of a report is the
Administrators group, the Administrators group will have Full Control access to
it. If the owner of the report is not an administrator, the report will be transferred
and the View On Demand access mode will be associated with the report.
Other objects
The Crystal Import Wizard cannot import Info objects that are not supported by
Crystal Enterprise. Such objects include report packages, query objects, Info cubes,
Open OLAP cubes, Holos Applications, and Crystal reports based on query files.
Importing with the Crystal Import Wizard
The Crystal Import Wizard is made up of a series of screens that guide you through
the process of importing user accounts, groups, folders, and reports. The screens
that appear depend upon the types of information that you choose to import.
When you import information, you first connect to the Crystal Management Server
(CMS) of your existing installation (the source environment) and specify the CMS
of your new Crystal Enterprise system (the destination environment). You then
select the information that you want to import, and the Crystal Import Wizard
copies the requested information from the source to the destination.
You can choose to merge the contents of the source repository into the destination
repository, or you can update the destination with the contents of the source CMS.
Before starting this procedure, ensure you have the Administrator account
credentials for both the source and the destination environment.
The overall process is divided into these two procedures:
• “Specifying the source and destination environments” on page 136
• “Selecting information to import” on page 137
Crystal Enterprise Administrator’s Guide
135
Importing with the Crystal Import Wizard
Specifying the source and destination environments
This procedure shows how to specify a source environment and a destination
environment using the initial screens of the Crystal Import Wizard.
1 From the Crystal Enterprise program group, click Crystal Import Wizard.
2 Click Next.
The “Specify source environment” dialog box appears.
3 In the Source list, select the product from which you want to import information.
The available options are:
• Info 7.5
• Crystal Enterprise 8
• Crystal Enterprise 8.5
• Crystal Enterprise 9
• Crystal Enterprise 10
4 In the CMS Name field, type the name of the source environment’s CMS
(Crystal Management Server).
5 Type the User Name and Password that provide you with administrative
rights to the source environment.
This example imports information from Crystal Enterprise 10.
6 Click Next.
The “Specify destination environment” dialog box appears.
7 In the CMS Name field, type the name of the destination environment’s
Crystal Management Server.
136
Crystal Enterprise Administrator’s Guide
9: Importing Objects to Crystal Enterprise
8 Type the User Name and Password of an Enterprise account that provides you
with administrative rights to the Crystal Enterprise system; then click Next.
The “Choose objects to import” dialog box appears. Proceed to “Selecting
information to import” on page 137.
Selecting information to import
This procedure shows how to select the users, groups, folders, and reports that you
want to import. If you have not already started the Crystal Import Wizard, see
“Specifying the source and destination environments” on page 136.
1 In the “Choose objects to import” dialog box, select the check box (or boxes)
corresponding to the information you want to import:
• Import users and user groups
• Import favorite folders for selected users
• Import folders and objects
• Import events
• Import server groups
• Import repository objects
• Import calendars
Note: The options available depend on the version of the source environment.
Events and server groups can be imported from Crystal Enterprise 8.5 or later.
Repository objects and calendars can be imported from Crystal Enterprise 10.
2 Click Next.
Crystal Enterprise Administrator’s Guide
137
Importing with the Crystal Import Wizard
3 In the “Please choose an import scenario” dialog box, choose the type of
import you want, then click Next.
Merging systems
To merge the source and destination systems, choose “I want to merge the
source system into the destination system.” This option adds all objects from
the source CMS into the destination CMS without overwriting objects in the
destination.
Note: This is the safest import option. All of the objects in the destination
system are preserved. Also, at a minimum, all objects from the source system
with a unique title are copied to the destination system.
Updating the destination system
To add the source system’s information to the destination system without
merging, choose “I want to update the destination system by using the source
system as a reference.”
When you update the contents of the destination system using the source
system as a reference, you add all objects in the source CMS to the destination
CMS. If an object in the source system has the same unique identifier as an object
in the destination, the object in the destination is overwritten.
For more information about merging and updating systems, see “Copying data
from a Crystal Enterprise 10 CMS” on page 254.
4 Click Next.
5 If you chose to import users and user groups, the “Select Users and Groups”
dialog box appears. In the Groups list, select the groups that you want to
import. In the Subgroups and Users list, select specific members of any group.
Then click Next.
138
Crystal Enterprise Administrator’s Guide
9: Importing Objects to Crystal Enterprise
This example imports all but one of the users in the Administrators group.
6 If you chose to import folders and objects, the “Select Folders and Objects”
dialog box appears. Select the check boxes for the folders and reports that you
want to import. Then click Next.
Tip: You can also choose to “Import all instances of each selected report and
object package.”
This example imports the Report Samples folder and a subset of its contents.
Crystal Enterprise Administrator’s Guide
139
Importing with the Crystal Import Wizard
7 If you chose to import repository objects, the “Import repository objects
options” dialog box appears. Choose an importing option for repository
objects, then click Next.
8 When the “Information collection complete” dialog box appears, click Finish
to begin importing the information.
The Import Progress dialog box displays status information and creates an
Import Summary while the Crystal Import Wizard completes its tasks.
9 If the Import Summary shows that some information was not imported
successfully, click View Detail Log for a description of the problem.
Otherwise, click Done.
Note: The information that appears in the Detail Log is also written to a text
file called ImportWiz.log, which you will find in the directory from which the
Crystal Import Wizard was run. By default, this directory is:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\
The log file included a system-generated ID number, a title that describes the
imported information, and a field that describes the action taken and the reason
why.
140
Crystal Enterprise Administrator’s Guide
Controlling User Access
10
This chapter describes how to use rights to secure the
content that you publish to Crystal Enterprise, and to grant
users varying levels of access to Crystal Enterprise
components and administration. Predefined access levels,
advanced rights, and inherited rights are all discussed in
detail. Examples and procedures are provided in the form
of tutorials.
• “Controlling user access overview” on page 142
Crystal Enterprise Administrator’s Guide
141
Controlling user access overview
Controlling user access overview
Rights are the base units for controlling users’ access to objects, users, applications,
servers, and other features in Crystal Enterprise. When granted, each right
provides a user or group with permission to perform a particular action. Using
rights, you can set security levels that affect individual users and groups. Rights
allow you to control access to your Crystal Enterprise content, to delegate user and
group management to different departments, and to provide your IT people with
administrative access to servers and server groups.
To set rights within the Crystal Management Console (CMC), you first locate the
object, user, or server and then you specify the rights for different users and
groups. Each right can be Explicitly Granted, Explicitly Denied, or Inherited. The
Crystal Enterprise security model is designed such that, if a right is left “not
specified,” the right is denied by default. Additionally, if contradictory settings
result in a right being both granted and denied to a user or group, the right is
denied by default. This “denial based” design assists in ensuring that users and
groups do not automatically acquire rights that are not explicitly granted.
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 “Setting common access levels” on page 144.
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.
Users require specific licensing and rights to create or modify reports through the
Report Application Server (RAS). For details, see “Object rights for the Report
Application Server” on page 417.
Controlling users’ access to objects
To 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.
142
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
You can set rights for folders, report objects, program objects, and other Crystal
Enterprise objects.
Tip: For detailed tutorials that walk you through sample implementations of object
rights, see “Customizing a ‘top-down’ inheritance model” on page 154.
Viewing object rights settings
Use the CMC to view the object rights that a user or group has to any folder, report,
or other Crystal Enterprise object. This section shows how to locate the rights for
any object and briefly explains the information displayed on the Rights tab.
You can locate any given object in several ways. Go to the Folders management
area in the CMC to browse your folder hierarchy for an object, or go to the Objects
management area in the CMC to view a list of all the objects on the system.
Click the link that corresponds to the folder or other object whose rights you want
to see, then click the object’s Rights tab. A page similar to the following appears:
This example shows the rights for the Report Samples folder. The Name column
lists all users and groups who have been given rights to the object. The Object
column shows whether the entry is a User or a Group. In this case, users have not
been specified individually; instead, users have been divided into two groups—
Everyone and Administrators—which have been granted rights to the folder
object. Click Add/Remove to add or remove a user or group to this object.
The Access Level column shows how each user’s or group’s rights are determined.
In this example, both groups possess Inherited Rights. You can change the rights
for either group by selecting a predefined access level (or by selecting Advanced)
from the list in the Access Level column. When you change an entry in the Access
Level column, click Update to effect your changes. For more information, see
“Setting common access levels” on page 144.
The Net Access column displays the net effect of whatever is selected in the Access
Level column. That is, the Net Access column shows the effective rights that each
user or group has to the object. The Net Access column is particularly useful when
you are working with inheritance. In this example, the Everyone group inherits rights
from a parent folder—one that is not displayed on this screen. The Net Access
column shows that the rights inherited from the parent folder are equivalent to the
Schedule access level.
Crystal Enterprise Administrator’s Guide
143
Controlling users’ access to objects
Tip: If you want to view the individual object rights that make up a user’s (or
group’s) Net Access, click the corresponding Access Level list and select Advanced.
The Advanced Rights page displays the user’s full array of object rights that have
been specified explicitly and/or inherited. Click Cancel to exit without making
changes. For more information, see “Setting advanced object rights” on page 146.
For detailed tutorials that walk you through sample implementations of object
rights, see “Customizing a ‘top-down’ inheritance model” on page 154.
Setting common access levels
An access level is essentially a predefined set of object rights. Crystal Enterprise
provides a set of access levels that allow you to set common object security levels
quickly. The available predefined access levels are No Access, View, Schedule,
View On Demand, and Full Control. Access levels are based on a model of
increasing rights: beginning with No Access and ending with Full Control, each
access level builds upon the rights granted by the previous level. For example, the
Schedule access level includes and adds to the rights that are granted by the View
access level. For a complete listing of the object rights that make up each access
level, see “Access levels” on page 415.
Tip: By default, users or groups who have rights to a folder will inherit the same
rights for any object that you subsequently publish to that folder. Consequently,
the best strategy is to set the appropriate rights for users and groups at the folder
level first. Then publish objects to that folder.
Although access levels grant predefined sets of object rights, they do not explicitly
deny any object rights. Instead, each access level grants some rights and leaves the
other rights “not specified.” The system then denies the “not specified” rights by
default. This is important, because it allows users to inherit the greatest rights
when they belong to multiple groups:
• When you assign an access level to a group, each user in the group will have at
least that level of access to the object. If the user is a member of multiple
groups, then he or she inherits the combination of each group’s rights. Thus,
when a user is a member of multiple groups, he or she inherits the greatest
possible rights.
• When you assign an access level directly to a user, you ensure that the user has
only that level of access to the object. In other words, you prevent the user
from inheriting rights that he or she may have otherwise acquired by virtue of
group membership.
This list provides a brief description of each access level:
• No Access
The user or group is not able to access the object or folder. The Crystal
Enterprise web desktop, the Crystal Publishing Wizard, and the CMC enforce
this right by ensuring that the object is not visible to the user.
144
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
• View
If this access level is set at the folder level, the user or group is able to view the
folder, the objects contained within the folder, and all generated instances of
each object. If this access level is set at the object level, the user can view the
object, the history of the object, and all generated instances of the object. The
user cannot, however, schedule the object or refresh it against its data source.
• Schedule
The user or group is able to view the object or folder and its contents, and to
generate instances by scheduling the object to run against the specified data
source once or on a recurring basis. The user or group can view, delete, and pause
the scheduling of instances that they own. They can also schedule to different
formats and destinations, set parameters and database logon information, pick
servers to process jobs, add contents to the folder, and copy the object or folder.
• View On Demand
In addition to the rights provided by the Schedule access level, the user gains
the right to refresh data “on demand” against the data source.
• Full Control
This access level grants all of the available advanced rights. It is the only access
level that allows users to delete objects (folders, objects, and instances). This
access level also allows users to modify all of the object’s properties, including
the object rights that are set on the folder or object.
Basically, this access level is designed to provide a user or group with
administrative control over one or more folders or objects. Users can then log
on to the CMC and add, edit, and remove content as required, without being
members of the actual Administrators group.
• Advanced
This access level does not include a predefined set of object rights. Instead, it
allows you to customize a user’s or group’s access to an object by selecting from
the complete range of available object rights. For more information, see “Setting
advanced object rights” on page 146.
Note: There is no predefined access level to grant users the rights required to
create or modify reports through the Report Application Server (RAS). For
details, see “Object rights for the Report Application Server” on page 417.
For a detailed listing of the object rights that make up each access level, see “Rights
and Access Levels” on page 413.
Note: In the developer documentation, access levels are referred to as roles.
To set an access level for a user or group
1 Go to the Objects or Folders management area of the CMC.
2 Locate the object whose rights you want to modify.
3 Click the link to the object, and then click its Rights tab.
Crystal Enterprise Administrator’s Guide
145
Controlling users’ access to objects
4 In the Name column, locate the user or group whose rights you want to specify.
If the user or group is not listed, click Add/Remove. Add the appropriate user
or group and click OK. You are returned to the object’s Rights tab.
5 In the Access Level column, select the access level (No Access, View, Schedule,
View On Demand, or Full Control) that is appropriate for the user or group.
6 Click Update.
Tip: For detailed tutorials that walk you through sample implementations of object
rights, see “Customizing a ‘top-down’ inheritance model” on page 154.
Setting advanced object rights
To provide you with full control over object security, the CMC allows you to make
Advanced object rights settings for any user or group. These Advanced settings
enable you to choose from a complete set of granular object rights. The result is an
increased flexibility as you define security levels for objects that you have
published to Crystal Enterprise.
Use advanced rights, for instance, if you need to customize a user’s or group’s
rights to a particular object or set of objects, or if you want to customize the default
inheritance patterns. Most importantly, use advanced rights to explicitly deny a
user or group any right that should not be permitted to change when, in the future,
you make changes to group memberships or folder security levels.
Tip: By default, users or groups who have rights to a folder will inherit the same
rights for any object that you subsequently publish to that folder. Consequently,
the best strategy is to set the appropriate rights for users and groups at the folder
level first. Then publish objects to that folder.
Note: Because of the relative priorities assigned by Crystal Enterprise to granted
and denied rights, you must disable inheritance entirely when you need to explicitly
grant a right that has been denied elsewhere to the user or group. For complete
details, see “Priorities affecting advanced inheritance settings” on page 154.
To view or set advanced rights
1 Go to the Objects or Folders management area of the CMC.
2 Locate the object whose rights you want to modify.
3 Click the link to the object, and then click its Rights tab.
4 In the Name column, locate the user or group whose rights you want to specify.
If the user or group is not listed, click Add/Remove. Add the appropriate user
or group and click OK. You are returned to the object’s Rights tab.
5 The next step depends upon the entry that already appears in the Access Level
list for this user or group:
• If the Access Level is not already set to Advanced, click the list and select
Advanced.
146
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
• If the Access Level is already set to Advanced, click the Advanced link in
the Net Access column.
The available object rights are displayed in the Advanced Rights page. This
example shows advanced rights being applied to the Guest user for an
Employee Profile report.
Crystal Enterprise Administrator’s Guide
147
Controlling users’ access to objects
The first two options specify which types of inheritance affect the Guest user’s
rights to this object. In this example, the Guest user cannot inherit rights by virtue
of group membership. But, the Guest user may inherit any rights that he or she has
been granted to this report’s parent folder.
The remainder of the Advanced Rights page lists all available object rights and
shows how each right applies to the Guest user. To customize the overall security
levels, you can explicitly grant or deny any given right, or you can specify that you
want certain rights to be inherited.
The Inherited column serves as an indicator to show how inherited rights affect the
Guest user’s effective rights to this report object. A user or group can be granted or
denied a right by virtue of inheritance. In addition, some rights may remain “not
specified”—that is, they are neither granted nor denied. If an inherited right is
labelled as “Not Specified”, Crystal Enterprise treats it as having been denied.
(And if the right is later granted for a parent group or object, the user or group will
automatically inherit the right at this level.)
In this example, the Guest user has two inherited rights (the right to “View document
instances that the user owns” and to “Pause and Resume document instances that
the user owns”). Currently, these rights are not specified, so the rights are denied by
default. However, if the Guest user’s rights should change on the report’s parent
folder, the rights will also change for this report object. This demonstrates how
inheritance can facilitate future changes to the overall security model.
Tip: For scalability and manageability, it is recommended that you leave as many
rights as possible inherited, because the system automatically updates those rights
as you modify and update your security settings throughout the folder and group
hierarchies.
The Explicitly Granted column shows which actions the Guest user is allowed to
perform on this report. The Guest user is currently granted eleven rights to this
report (the right to “View objects,” “Schedule the document to run,” and so on).
Because group inheritance is disabled, the Guest user will retain these rights, even if
its group membership is modified or changed completely. This demonstrates how
you can use explicit rights to override a group’s rights for a particular group member.
The Explicitly Denied column works similarly to the Explicitly Granted column.
Regardless of any future changes to the user’s group membership, an explicitly
denied right always prevents a user from performing the associated action. In this
example, the Guest user has been explicitly denied eleven rights (the right to “Add
objects to the folder,” “Edit objects,” and so on). Again, this demonstrates how you
can use explicit rights to override a group’s rights for a particular group member.
When you have made your changes on the Advanced Rights page, click OK.
Tip: For detailed tutorials that walk you through sample implementations of object
rights, see “Customizing a ‘top-down’ inheritance model” on page 154.
148
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
Base rights and available rights
The Crystal Enterprise system defines a set of base rights that apply to all objects in
the system. For example, the “View objects” right is a base right: it applies equally
well to folders, to reports, and to other Crystal Enterprise objects. In addition to
these base rights, however, each type of object provides an additional set of rights
that apply only to that object type. For example, the “Refresh the report’s data”
right applies only to report objects.
The Crystal Management Server (CMS) is the component that keeps track of available
rights. The list of available rights includes the base rights and all other object-specific
rights that have been provided by particular object types, such as Crystal report objects.
On the Advanced Rights pages, you will find that all of the available rights are
displayed for every object on the system. For example, the rights displayed for a
folder object seem to correspond exactly to the rights displayed for a report object,
even though object-specific rights such as “Refresh the report’s data” do not apply
to folder objects.
Available rights are displayed for every object on the system for purposes of
inheritance, so that you can set object security at the folder level (rather than
repeating the same settings for every object in the folder). Although certain objectspecific rights do not strictly apply to the folder object itself, these rights may apply
to objects that inherit rights from the folder. In other words, the “Refresh the report’s
data” right is displayed for the folder object so that you can grant a user the right to
refresh the data in all reports for which the user inherits rights from this folder.
Note: This is only one type of object inheritance. For more information, see
“Group and folder inheritance” on page 150.
Using inheritance to your advantage
In regards to object rights, Crystal Enterprise recognizes two types of inheritance:
group inheritance and folder inheritance. By taking advantage of the ways in
which object rights are inherited, you can reduce the amount of time it takes to
secure the content that you have published to Crystal Enterprise. Additionally,
you can set up Crystal Enterprise such that you can integrate new users and new
content quickly and easily.
To facilitate administration, it is recommended that you enable and disable
inheritance with access levels whenever possible (instead of with advanced rights).
Additionally, it is recommended that you make your initial settings at the top-level
Crystal Enterprise folder and disable inheritance only when necessary. For
detailed tutorials that walk you through sample implementations of object rights,
see “Customizing a ‘top-down’ inheritance model” on page 154.
Tip: By default, users or groups who have rights to a folder will inherit the same
rights for any object that you subsequently publish to that folder. Consequently,
the best strategy is to set the appropriate rights for users and groups at the folder
level first. Then publish objects to that folder.
Crystal Enterprise Administrator’s Guide
149
Controlling users’ access to objects
Group and folder inheritance
Group inheritance allows users to inherit rights as the result of group membership.
Group inheritance proves especially powerful when you organize all of your users
into groups that coincide with your organization’s current security conventions.
For example, if you create a user called Sample User, and add it to an existing
group called Sales, then Sample User will automatically inherit the appropriate
rights for each of the reports and folders that the Sales group has been added to.
When group inheritance is enabled for a user who belongs to more than one group,
the rights of both groups are considered when the system checks credentials. The
user is denied any right that is explicitly denied in any group, and the user is
denied any right that remains completely “not specified”; thus, the user is granted
only those rights that are granted in one or more groups (explicitly or through
access levels) and never explicitly denied.
Folder inheritance allows users to inherit any rights that they have been granted on
an object’s parent folder. Folder inheritance proves especially powerful when you
organize Crystal Enterprise content into a folder hierarchy that reflects your
organization’s current security conventions. For example, suppose that you create a
folder called Sales Reports, and you provide your Sales group with View On Demand
access to this folder. By default, every user that has rights to the Sales Reports folder
will inherit the same rights to the reports that you subsequently publish to this folder.
Consequently, the Sales group will have View On Demand access to all of the reports,
and you need only set the object rights once, at the folder level.
Note: If you need to disable or modify inheritance patterns for a particular folder
or object within your folder hierarchy, you can do so with access levels or with
advanced rights.
Enabling and disabling inheritance with access levels
With access levels, you can enable or disable group inheritance, folder inheritance,
or both. You can alternatively enable one or both types of inheritance with Advanced
rights settings. For details, see “Inheritance with advanced rights” on page 151.
To enable inheritance with an access level
1 Go to the Objects or Folders management area of the CMC.
2 Locate the object whose rights you want to modify.
3 Click the link to the object, and then click its Rights tab.
4 In the Name column, locate the user or group whose rights you want to specify.
If the user or group is not listed, click Add/Remove. Add the appropriate user
or group and click OK. You are returned to the object’s Rights tab.
5 In the Access Level column, select Inherited Rights for the user or group.
6 Click Update.
150
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
The Net Access column now displays the effective rights that the user or group
has inherited for this object.
Note: If the entry displayed in the Net Access column is Advanced, ensure that
both types of inheritance are enabled in the parent folder’s advanced rights
settings. For details, see “Setting advanced object rights” on page 146.
To disable inheritance with an access level
Note: This procedure disables group and folder inheritance for a user account.
When applied to a group, this procedure does not prevent group members from
inheriting rights by virtue of membership in other groups.
1 Go to the Objects or Folders management area of the CMC.
2 Locate the object whose rights you want to modify.
3 Click the link to the object, and then click its Rights tab.
4 In the Name column, locate the user whose rights you want to specify.
If the user is not listed, click Add/Remove. Add the appropriate user and click
OK. You are returned to the object’s Rights tab.
5 In the Access Level column, select the access level (No Access, View, Schedule,
View On Demand, or Full Control) that is appropriate for the user.
6 Click Update.
The Net Access column now displays the effective rights that the user has to the
object. Because you have disabled all inheritance, the Net Access entry equals
the Access Level entry.
Inheritance with advanced rights
When you apply an Advanced set of object rights to a user or group for a particular
object, you can enable or disable group and folder inheritance together or
individually. On the Advanced Rights pages, the settings for inheriting rights from
parent folders or groups serve as powerful tools that allow you to customize
inheritance patterns in many ways.
Note: You see the “Username will inherit rights from its parent groups” option if
you are setting rights for a user; this option does not appear if you are setting
rights for a group.
Tip: When modifying inheritance patterns with Advanced rights settings, keep in
mind that you can always assign a user a specific set of rights, either by explicitly
applying a predefined access level, or by explicitly applying an Advanced setting
in which both types of inheritance are disabled.
To take full advantage of inheritance patterns and Advanced rights settings, it is
useful to understand not only the types of inheritance that are available, but also
the ways in which a user’s effective rights are calculated by the CMS.
For more information on the two types of inheritance, see “Group and folder
inheritance” on page 150.
Crystal Enterprise Administrator’s Guide
151
Controlling users’ access to objects
Calculating a user’s effective rights
When a user attempts to perform an action on a Crystal Enterprise object, the CMS
determines the user’s rights to that object. If the user possesses sufficient rights, the
CMS permits the user to perform the requested action.
Although the calculations performed by the CMS can become quite complex, there are
several ways to keep your object security model clear, consistent, and easy to maintain.
For complete details on setting up a system that makes sense for your Crystal
Enterprise system, see “Customizing a ‘top-down’ inheritance model” on page 154.
To calculate the user’s effective rights, the CMS follows a complex algorithm. This
sequence of steps, and its various possible outcomes, is provided for
administrators and/or system architects who prefer to know exactly how the CMS
calculates the rights a user has to any object. The algorithm is described here and
then illustrated in a different way using pseudocode:
1 The CMS checks the rights that have been directly granted or denied to the
user’s account. The CMS immediately denies any right that is explicitly denied.
Tip: If an individual user’s account has not been assigned any rights to the
object, then group inheritance is enabled by default. As the result, you can make
all your object rights settings at the group level to save administrative effort.
2 If folder inheritance is enabled for the user, the CMS determines the rights that
the user has to the object’s parent folder. The CMS determines these rights by
ascending the inheritance tree to the level at which the inherited rights begin
to take effect. The CMS denies any right that is explicitly denied (even if the
right had already been explicitly granted).
3 If group inheritance is enabled for the user, the CMS determines the rights
specified on the object for each of the groups that the user belongs to. The CMS
denies any right that is explicitly denied in any group (even if the right had
already been explicitly granted).
4 If group inheritance is enabled for the user, and folder inheritance is enabled
for a group that the user belongs to, then the CMS determines the rights that
the group has to the parent folder. The CMS denies any right that is explicitly
denied in any group (even if the right had already been explicitly granted).
5 The CMS completes the algorithm by denying any rights that remain “Not
Specified.”
As the result, when both types of inheritance are enabled, the CMS grants the user
only those rights that are explicitly granted in one or more locations and never
explicitly denied.
When you disable both types of inheritance for a user, you reduce this algorithm
to two steps (1 and 5). Thus, the CMS grants the user only those rights that he or
she has been explicitly granted. This provides you with the least complicated way
of ensuring that a user has only those rights that you have explicitly granted to him
or her for a particular object.
152
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
When you disable folder inheritance for a user, you reduce this algorithm to three
steps (1, 3, and 5). When you disable group inheritance for a user, you reduce this
algorithm to three different steps (1, 2, and 5). In both cases, the CMS grants the
user only those rights that are explicitly granted in one or more locations and never
explicitly denied.
This pseudocode is provided as another way to illustrate and describe the algorithm
that the CMS follows in order to determine whether a user is authorized to perform
an action on a particular object:
IF {
(User granted right to object = True)
OR [
(Inherit Parent Folder Rights = True) AND (User granted right to
parent folder = True)
]
OR [
(Inherit Group Rights = True) AND (Group granted right to object =
True)
]
OR [
(Inherit Group Rights = True) AND (Group granted right to parent
folder = True)
]
}
AND {
(User denied right to object = False)
AND [
(Inherit Parent Folder Rights = False)
OR ((Inherit Parent Folder Rights = True) AND (User denied right to
parent folder = False))
]
AND [
(Inherit Group Rights = False)
OR ((Inherit Group Rights = True) AND (Group denied right to object
= False))
]
AND [
(Inherit Group Rights = False)
OR ((Inherit Group Rights = True) AND (Group denied right to parent
folder = False))
]
}
THEN
{
User action authorized = True
}
ELSE
{
User action authorized = False
}
Crystal Enterprise Administrator’s Guide
153
Controlling users’ access to objects
Priorities affecting advanced inheritance settings
When you modify inheritance patterns with advanced rights, there are several
important considerations to keep in mind. Where relevant, these considerations
appear elsewhere in this chapter. They have been summarized here for reference.
Denied rights take precedence over granted rights. This can cause seemingly
contradictory results when inheritance is enabled. Suppose that the “View objects”
right is explicitly denied to a Sales group for a particular folder of reports. For the
same folder, the “View objects” right has been explicitly granted to a Manager
user, and the “Respect current security by inheriting rights from parent groups”
check box is selected. The Manager user is a member of the Sales group. In this
scenario, the Manager user is both granted and denied the “See object” right to the
folder. Because denied rights take precedence, the Manager user is effectively
denied the ability to see the folder, so long as the user account inherits rights from
its parent group (Sales). To remedy this situation, you could clear the “Respect
current security by inheriting rights from parent groups” check box on the
Advanced Rights page for the Manager user, or you could remove the Manager
user from the Sales group.
Rights that are not specified are denied by default. On the Advanced Rights page
for any object, the Inherited Rights column may label certain rights as “Not
Specified.” This entry denotes rights that are neither granted nor denied by
inheritance. To prevent possible security breaches, Crystal Enterprise
automatically denies rights that are not specified.
Customizing a ‘top-down’ inheritance model
With the flexibility offered by object rights, inheritance, and advanced rights, you
can customize your object-level security environment in many ways. However, as
the complexity of any security system increases, so too can that system become
more difficult and time-consuming to maintain. This section recommends two
general ways of setting up object security such that you achieve the desired
security levels without complicating future administrative tasks. To this purpose,
this section provides two tutorials that shows how to set up object security from
the top-level folder (the root folder) down:
• “Setting up an open system of decreasing rights” on page 158
This detailed tutorial creates an open security model. By default, all users and
groups are first granted rights to all objects on the system. As you add folders
and subfolders to the system, you decrease the rights of users and groups, as
required, in order to secure particular Crystal Enterprise content.
• “Setting up a closed system of increasing rights” on page 170
This shorter tutorial creates the basis for closed security model. By default,
users and groups cannot access any objects on the system. As you add folders
and subfolders to the system, you increase the rights of users and groups, as
required, in order to grant access to particular Crystal Enterprise content.
154
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
You can use your own Enterprise, NT, or LDAP groups when following along with
these tutorials, or you can create new groups that correspond to those used in the
tutorial. For details on setting up these groups and subgroups, see “Creating
groups for the tutorials” on page 155.
In each tutorial, you will specify the object rights that particular groups have to
certain folders on the system. By making all of your security settings at the group
and folder levels, you reduce the administrative efforts now and later. After
finishing each tutorial, you may decide to add users to each group and to publish
objects to each folder. If you do so, each user will inherit the appropriate rights for
every folder and object on the system.
Creating groups for the tutorials
The object security tutorials make use of eight Enterprise groups. The four primary
groups are named Administrators, Everyone, Sales, and Marketing. The Sales
group has four additional subgroups: Sales USA, Sales Japan, Sales Managers, and
Sales Report Designers. The Administrators and Everyone groups are created by
default when you install Crystal Enterprise, so these two procedures show only
how to create the remaining groups for the tutorials.
Note: For the shorter tutorial entitled “Setting up a closed system of increasing
rights”, you need only create the Sales group and its Sales USA, Sales Japan, and
Sales Managers subgroups.
To create the Sales and Marketing groups
1 Go to the Groups management area of the CMC.
2 Click New Group.
The new group’s Properties tab appears.
3 In the Group Name field, type Marketing
Crystal Enterprise Administrator’s Guide
155
Controlling users’ access to objects
4 In the Description field, type This group contains all users who work in
Marketing.
5 Click OK.
The Marketing group is added to the system and the page is refreshed.
Tip: Click the Users tab if you want to add your own users to this group.
6 Repeat steps 1 to 5 to create another group called Sales. Use this description
for the group: This group contains all users who work in Sales (worldwide).
To create the Sales subgroups
1 Go to the Groups management area of the CMC.
2 Click New Group.
3 In the Group Name field, type Sales USA
4 In the Description field, type This group contains all users who work in
Sales in the USA.
5 Click OK.
The Sales USA group is added to the system and the page is refreshed.
Tip: Click the Users tab if you want to add your own users to this group.
6 Click the Member of tab; then click the Member of button.
The Modify Member of page appears.
7 In the Available groups list, select Sales; then click the > arrow.
156
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
The Sales group is added to the “Sales USA is a member of” list, as displayed here:
8 Click OK.
You are returned to the “Member of” tab. The Sales USA group is now a
member (or subgroup) of the Sales group.
9 Repeat steps 1 to 8 to create the remaining Sales subgroups for the tutorials.
Use the following values for the Group Name and Description fields:
Group Name
Description
Sales Japan
This group contains all users who work in Sales in Japan.
Sales Managers
This group contains all users who manage a Sales team.
Sales Report
Designers
This group contains all users who design and publish
reports for the Sales teams.
If you now return to the Groups management area of the CMC, all of the new
groups are displayed as follows:
Crystal Enterprise Administrator’s Guide
157
Controlling users’ access to objects
You are now ready to proceed to either of the object security tutorials:
• “Setting up an open system of decreasing rights”.
• “Setting up a closed system of increasing rights” on page 170.
Setting up an open system of decreasing rights
This tutorial shows how to create an open security model, wherein groups of users
are first granted rights to all objects on the system by default. As you add folders
and subfolders to the system, you decrease the rights of users and groups, as
required, in order to secure particular Crystal Enterprise content.
In this scenario, you are creating folders for several groups within your organization.
You have some reports that you want to add to the system immediately. Because
some groups plan to add their own reports later, you also need to give some users
the ability to add subfolders and to publish reports. These are your security
requirements for each folder:
• Everyone must be able to view the majority of your reports.
• Administrators require Full Control access to all folders and objects on the system.
• Sales Managers are allowed to refresh most reports against the database to
view the most recent data.
• The Marketing group needs Full Control access to its own set of folders that no
other user can access (other than Administrators).
• The Sales groups need a hierarchy of folders containing worldwide reports,
regional reports, and management reports:
• All Sales staff can view worldwide reports.
• Sales staff can also view reports for their own regions. If the staff member is
also a Manager, he or she can view and refresh reports from all regions.
• Sales Managers require Full Control access to the management reports.
• Sales Report Designers require custom administrative privileges to all Sales
folders.
For a shorter, less detailed tutorial, see “Setting up a closed system of increasing
rights” on page 170.
Changing default rights on the top-level folder
The first step is to set object rights on the top-level Crystal Enterprise folder. This
folder serves as the root for all other folders and objects that you add to the system.
Each subfolder, report, or other object that you add to this top-level folder will by
default inherit rights from this folder. So, by setting rights here first, you minimize
the need to repeatedly customize object rights throughout your folder hierarchy.
158
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
With this procedure, you set security on the top-level folder in order to meet your
first three security requirements:
• Everyone must be able to view the majority of your reports.
• Administrators require Full Control access to all folders and objects on the system.
• Sales Managers are allowed to refresh most reports against the database to
view the most recent data.
To change the rights on the top-level folder
1 Go to the Settings management area of the CMC.
2 Click the Rights tab.
By default, the Everyone and the Administrators groups are granted access to
this folder. You now need to reduce the rights of the Everyone group and to
increase the rights of the Sales Managers.
3 Click the Access Level list that corresponds to the Everyone group, and select
View.
4 Click Update.
The rights for the Everyone group are reduced and the View access level is now
displayed in the Net Access column.
Now you will customize the top-level rights for the Sales Managers group.
Crystal Enterprise Administrator’s Guide
159
Controlling users’ access to objects
5 Click Add/Remove.
The Add/Remove page appears.
6 In the Select Operation list, click Add/Remove Groups.
7 In the Available groups list, select Sales Managers.
8 Click the > arrow; then click OK.
You are returned to the Rights tab on the Settings page. Ensure that you grant
the Sales Managers group View On Demand access. If necessary, change the
Access Level list and click Update. This provides the Sales Managers group
with sufficient rights to refresh reports.
Now, your system meets your first three security requirements. The Everyone,
Administrators, and Sales Managers groups will initially inherit these rights for any
folders, subfolders, or reports that you subsequently publish to Crystal Enterprise.
You might, for instance, create folders for all of your generally accessible inventory
reports, customer list reports, purchasing order reports, and so on.
Now that you have created an open basis for your object security model, you will
proceed to restricting access to certain folders within the system.
160
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
Decreasing rights to a private folder
Another security requirement for this tutorial is that the Marketing group needs
Full Control access to their own set of folders that no other user can access. To
accomplish this, you will create a private folder called Marketing Only and ensure
that only the appropriate group of users has access to its contents.
To decrease rights to a private folder
1 Go to the Folders management area of the CMC.
2 Click New Folder.
3 On the Properties tab, in the Folder Name field, type Marketing Only
4 In the Description field, type This folder is accessible only to Marketing.
5 Click OK.
6 Click the Rights tab.
7 In the Access Level column, select the following rights for each group:
• Administrators: (Inherited Rights)
• Everyone: No Access
• Sales Managers: No Access
8 Click Update.
The Net Access column shows that you have secured this folder from all users
other than Administrators.
Next, you will grant the Marketing group Full Control access to this folder.
9 Click Add/Remove.
The Add/Remove page appears.
10 In the Select Operation list, click Add/Remove Groups.
11 In the Available groups list, select Marketing.
12 Click the > arrow; then click OK.
You are returned to the Rights tab. The Marketing group is granted access to the
folder. You need to change the default setting to grant them Full Control access.
13 Click the Access Level list that corresponds to the Marketing group, and select
Full Control.
14 Click Update.
Crystal Enterprise Administrator’s Guide
161
Controlling users’ access to objects
The Net Access column shows that you have granted the Marketing group Full
Control access to this folder.
Members of this group now have the ability to perform all tasks in this folder. They
can add and delete reports, folders, and subfolders, and they can view, schedule,
and export reports to all available destinations and formats.
To complete this tutorial, you need to customize the rights that various Sales
groups have to a hierarchical set of Sales folders. Before setting the rights for each
group, you will see how to create multiple folders quickly when you publish a set
of reports to Crystal Enterprise.
Publishing a set of folders and reports
The final security requirements for this tutorial are related to the Sales group and
its subgroups. They require a hierarchy of folders containing worldwide reports,
regional reports, and management reports.
Because this tutorial sets up a system of decreasing rights, you will first create a set
of folders that places the most general content at the top of the directory tree. In
this case, all Sales staff can view the worldwide reports, so the folder for those
reports requires the lowest level of security. The regional reports will go in
subfolders that are accessible only to users who belong to the appropriate regional
Sales group. The management reports will be located in subfolders of each of the
regional folders.
You could create this set of folders using the CMC, as in the earlier sections of this
tutorial. However, if you already have a set of reports, the Crystal Publishing Wizard
provides the quickest way to add content and create folders at the same time.
162
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
To create a set of folders while publishing reports
1 On your local hard drive, create a set of folders that correspond to the folders
you want to add to Crystal Enterprise.
For this tutorial, the Sales folders are named and arranged hierarchically as
follows:
2 Arrange your reports (.rpt files) in the new folders on your local hard drive.
If you do not have any of your own reports, use some of the sample reports
included with Crystal Enterprise. The sample reports are typically installed to
C:\Program Files\Crystal Decisions\Enterprise 10\Samples\language\Reports
(replace language with en, de, fr, or jp, depending upon your version of Crystal
Enterprise).
Note: To complete this procedure, you must place at least one report file in
each of the folders that you have created on your local hard drive. Otherwise,
the Crystal Publishing Wizard will not create the appropriate directories on
the Crystal Enterprise system.
3 From the Crystal Enterprise 10 Programs group, start the Crystal Publishing
Wizard and, when it appears, click Next.
4 In the System field, type the name of the CMS to which you want to add
objects.
5 In the User Name and Password fields, type your Crystal Enterprise
credentials.
6 From the Authentication list, select the appropriate authentication type.
7 Click Next.
The Select A File dialog box appears.
Crystal Enterprise Administrator’s Guide
163
Controlling users’ access to objects
8 Click Add Folders.
9 Select the top level Worldwide Sales folder that you created on your local
hard drive.
10 Select the Include subfolders check box, and then click OK.
You are returned to the Select A File dialog box. All of the reports are added to
the list.
11 Click Next.
The Folder Hierarchy dialog box appears.
164
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
12 Select Yes to duplicate the local folder hierarchy on the Crystal Enterprise
system; then click Next.
13 In the Specify Location dialog box, click New Folder.
14 Name the folder Worldwide Sales and ensure that it is located at the top of the
directory tree, as shown here:
15 Click Next.
The Location Preview dialog box appears. You can see here that the Regional
Sales folders will be created below the Worldwide Sales folder, and the
Managers Only folders will be created as additional subfolders. The actual
report files are arranged in the appropriate folders.
Crystal Enterprise Administrator’s Guide
165
Controlling users’ access to objects
16 Click Next.
17 Proceed through the rest of the Crystal Publishing Wizard and make any
desired changes to your reports.
Tip: If you are publishing sample reports for the purpose of this tutorial, click
Next to accept all the default values. For more information on the rest of the
Crystal Publishing Wizard, see “Publishing with the Crystal Publishing
Wizard” on page 117.
When the Crystal Publishing Wizard has added the reports and folders to the
system, it displays a summary:
18 Click Finish to close the Crystal Publishing Wizard.
You are now ready to set each Sales group’s object rights for the new set of Sales
folders.
Setting the base rights on the Sales folders
Now that you have used the Crystal Publishing Wizard to add reports and create
the appropriate folders and subfolders, you are ready to set the object rights for
each level of reporting content.
The security requirements are as follows:
• All Sales staff can view worldwide reports.
• Sales staff can also view reports for their own regions. If the staff member is
also a Manager, he or she can view and refresh reports from all regions.
• Sales Managers require Full Control access to the management reports.
• Sales Report Designers require custom administrative privileges to all Sales
folders.
166
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
To set the base rights on the Worldwide Sales folder
1 Go to the Folders management area of the CMC.
2 Click the link to the Worldwide Sales folder.
3 On the folder’s Rights tab, click Add/Remove.
4 In the Select Operation list, click Add/Remove Groups.
5 In the Available groups list, select Sales and Sales Report Designers.
Tip: Use CTRL+click to select multiple groups.
6 Click the > arrow; then click OK.
You are returned to the Rights tab.
7 In the Access Level column, select the following rights for each group:
• Administrators: Inherited Rights
• Everyone: No Access
• Sales: View
• Sales Managers: Inherited Rights
• Sales Report Designers: This group requires additional rights to publish
content to this folder. You will use advanced rights to make these changes
in the next procedure. For now, leave the Access Level list with the default
settings.
8 Click Update.
The Net Access column is updated to show your new security settings.
You now need to grant the Sales Report Designers group a set of advanced rights,
so group members can administer all the Sales folders.
Creating a group of folder administrators
This section of the tutorial shows how to provide a particular group of users with
a customized level of administrative control over a set of folders. In general, you
can accomplish this with the Full Control access level. This example, however, uses
advanced rights to grant the Sales Report Designers group a particular set of
administrative privileges to all Sales folders.
To create a group of Sales folder administrators
1 If you are not already there, go to the Rights tab of the Worldwide Sales folder.
2 In the Access Level list for the Sales Report Designers group, select
Advanced.
The Advanced Rights page appears. You will use this page to grant group
members a high level of control over the folder and its contents. However, you
will not let any group member delete objects that have been added to a Sales
folder.
Crystal Enterprise Administrator’s Guide
167
Controlling users’ access to objects
3 To ensure that you completely break all inheritance patterns, clear the
“Worldwide Sales” will inherit rights from its parent folders check box.
4 Click Apply.
Now that you have disabled all rights inheritance, the advanced rights that you
specify will be the only rights that group members have to the folder.
5 In the Explicitly Denied column, select the following rights:
• Modify the rights users have to objects
• Delete objects
Tip: You may choose to explicitly deny additional rights to suit your needs. For
instance, to prevent these folder administrators from copying confidential
reports to public folders, you could deny the “Copy objects to another folder”
right. Or, if you prefer to retain all administrative control over report-processing
servers, you could deny the “Define server groups to process jobs” right.
6 In the Explicitly Granted column, select all remaining rights.
7 Click OK.
You are returned to the Rights tab for the Worldwide Sales folder. The Net
Access column now shows that the Sales Report Designers group has
Advanced rights to this folder.
Tip: Click the Advanced link in the Net Access column when you need to review or
modify a set of advanced rights that have already been applied to a user or group.
Now that you have set object rights on the uppermost Sales folder, you will
proceed to decrease rights as you descend the folder hierarchy.
Decreasing rights to the Sales subfolders
Recall that the security requirements for the regional sales reports are as follows:
• Sales staff can view reports for their own region and can refresh these reports
against the database to view the most recent data.
• If the staff member is also a Manager, he or she can view and refresh reports
from all regions.
You will use the various Sales groups to decrease rights appropriately for each
Regional Sales folder.
To decrease rights to the regional Sales folders
1 Go to the Regional Sales - JP folder and click its Rights tab.
2 Click Add/Remove.
3 In the Select Operation list, click Add/Remove Groups.
4 In the Available groups list, select Sales Japan.
5 Click the > arrow; then click OK.
You are returned to the Rights tab of the Regional Sales - JP folder.
168
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
6 In the Access Level column, select the following rights for each group:
• Administrators: Inherited Rights
• Everyone: Inherited Rights
• Sales: No Access
• Sales Japan: View On Demand
• Sales Managers: Inherited Rights
• Sales Report Designers: Inherited Rights
7 Click Update.
The Net Access column shows your new security settings. As required, the
Sales Japan and the Sales Managers groups have View On Demand access,
which allows them to refresh reports against the database to view the latest
data. The Sales Report Designers retain their advanced rights, and all other
users are prevented from accessing the folder (except for Administrators).
8 Repeat steps 1 to 6 for the Regional Sales - USA folder, but grant View On
Demand access to the Sales USA group (instead of to the Sales Japan group).
You are now ready to complete the tutorial by customizing security for the final
level of Sales folders—the Managers Only folders.
To decrease rights to the Managers Only folders
1 Go to the Regional Sales - JP folder and click its Subfolders tab.
2 Click the link to the Managers Only folder and click its Rights tab.
3 In the Access Level column, select the following rights for each group:
• Administrators: Inherited Rights
• Everyone: Inherited Rights
• Sales: Inherited Rights
• Sales Japan: No Access
• Sales Managers: Full Control
• Sales Report Designers: Inherited Rights
4 Click Update.
The Rights tab of this Managers Only folder now shows that the
Administrators, Sales Managers, and Sales Report Designers groups all have
Full Control access to the folder. Members who do not belong to one of these
groups are completely restricted from the folder.
5 Go to the Regional Sales - USA folder and click its Subfolders tab.
6 Click the link to the Managers Only folder and click its Rights tab.
7 In the Access Level column, select the following rights for each group:
• Administrators: Inherited Rights
• Everyone: Inherited Rights
• Sales: Inherited Rights
• Sales Managers: Full Control
Crystal Enterprise Administrator’s Guide
169
Controlling users’ access to objects
• Sales Report Designers: Inherited Rights
• Sales USA: No Access
8 Click Update. The Rights tab of this Managers Only folder shows again that
the Administrators, Sales Managers, and Sales Report Designers groups all
have Full Control access to the folder. Members who do not belong to one of
these groups are completely restricted from the folder.
You have now reached the end of this tutorial.
Setting up a closed system of increasing rights
This tutorial shows how to set up the basis for a closed security model, wherein
groups of users are first denied rights to all objects on the system by default. As
you add folders and subfolders to the system, you increase the rights of users and
groups, as required, so they can access their Crystal Enterprise content.
In this scenario, you are creating folders for several groups within your
organization. These are your security requirements for each folder:
• The majority of your reports should be inaccessible to most users.
• Administrators require Full Control access to all folders and objects on the system.
• The Sales groups need a hierarchy of folders containing management reports
and regional reports:
• Only the Sales Managers can view the management reports and all regional
reports.
• Sales staff can only view reports for their own region.
Because this scenario first completely restricts access to the top-level folders, and
then gradually increases access to subfolders further down the folder hierarchy, the
results are essentially incompatible with the design of the Crystal Enterprise web
desktop. The closed security model works best when you deploy a web desktop or
other application that provides users with a list of all reports and/or folders to
which they have access. The sample Report Thumbnail Client and the In-frame
Client applications provide examples that are compatible with a closed security
model. You can access these applications from the Client Samples area of the Crystal
Enterprise Launchpad.
The Crystal Enterprise web desktop, by contrast, adheres to a hierarchical view of
the system’s folder structure. Thus, if users cannot access a top-level folder, they
have no way of browsing its subfolders (even if they have Full Control over those
subfolders and their contents). If you implement this closed security model in
conjunction with the Crystal Enterprise web desktop, users will need to search for
specific reports by name or description.
For a lengthier, more detailed tutorial, see “Setting up an open system of
decreasing rights” on page 158.
170
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
Restricting access from the top-level folder
The first step is to set object rights on the top-level Crystal Enterprise folder. This
folder serves as the root for all other folders and objects that you add to the system.
Each subfolder, report, or other object that you add to this top-level folder will inherit
rights from this folder by default. So, by setting rights here first, you minimize the
need to repeatedly customize object rights throughout your folder hierarchy.
With this procedure, you set security on the top-level folder in order to meet your
first two security requirements:
• The majority of your reports should be inaccessible to most users.
• Administrators require Full Control access to all folders and objects on the system.
This procedure gives the Everyone group No Access to all published content. This
is how you set the basis for a closed security model. Do not use advanced rights to
explicitly deny rights to the Everyone group (or any other group) at the top-level
folder of your Crystal Enterprise system, because once a right has been explicitly
denied, you have to break all inheritance patterns in order to grant the same right
further down the folder hierarchy.
To change the rights on the top-level folder
1 Go to the Settings management area of the CMC.
2 Click the Rights tab.
You need only reduce the rights of the Everyone group.
3 Click the Access Level list that corresponds to the Everyone group, and select
No Access.
Note: If users access reports through Crystal Enterprise, they will be unable to
browse subfolders once you make this initial security setting. Users will,
however, be able to search for reports by name or description.
4 Click Update.
The rights for the Everyone group are reduced and No Access is displayed in
the Net Access column.
Now, your system meets your first two security requirements. The Everyone
group is prevented from seeing all subsequently published content, and the
Administrators group retains Full Control in order to maintain the system.
Now that you have created a closed basis for your object security model, you will
increase access to certain folders within the system.
Increasing access by descending the folder hierarchy
The remaining security requirements for this tutorial are related to the Sales group
and its subgroups. They require a hierarchy of folders containing management
reports and regional reports. Because this tutorial sets up a system of increasing
rights, the most secure content will be stored at the top of the directory tree.
Crystal Enterprise Administrator’s Guide
171
Controlling users’ access to objects
With these procedures, you create the folder hierarchy and set access levels in
order to meet the remaining security requirements:
• Only the Sales Managers can view the management reports and all regional
reports.
• Sales staff can only view reports for their own region.
To provide minimal access to the management reports
1 Go to the Folders management area of the CMC.
2 Click New Folder.
3 On the Properties tab, in the Folder Name field, type Management Reports
4 Click OK.
The new folder is created and the page is refreshed.
5 On the Rights tab, click Add/Remove.
6 In the Select Operation list, click Add/Remove Groups.
7 In the Available Groups list, select Sales Managers.
8 Click the > arrow; then click OK.
You are returned to the Rights tab of the Management Reports folder.
9 Click the Access Level list for the Sales Managers group, and select View.
10 Click Update.
The Rights tab now shows that the Sales Managers group has View access to
this folder and to any objects that you subsequently publish to it. As required,
the Everyone and Administrators groups have inherited the rights that you set
on the top-level Crystal Enterprise folder.
Now you need only create folders for the regional reports and grant access to the
appropriate regional Sales groups.
To provide selective access to the regional reports
1 If you are not already there, go to the Management Reports folder.
2 On the Subfolders tab, click New Folder.
3 On the Properties tab, in the Folder Name field, type Regional Reports - JP
4 Click OK.
The new folder is created and the page is refreshed.
5 On the Rights tab, click Add/Remove.
6 In the Select Operation list, click Add/Remove Groups.
7 In the Available Groups list, select Sales Japan.
8 Click the > arrow; then click OK.
You are returned to the Rights tab of the Management Reports folder.
172
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
9 In the Access Level list for the Sales Japan group, select View.
10 Click Update.
The Rights tab now shows that the Sales Japan group has View access to this
folder and to any objects that you subsequently publish to it. The
Administrators, Everyone, and Sales Managers groups automatically inherit
the appropriate rights for this folder.
11 Repeat this procedure to create a subfolder called Regional Reports - USA and
to provide the Sales USA group with View access to the folder.
When you finish, the Rights tab of the Regional Reports - USA folder shows that
you have set the rights as required for this tutorial.
You have now reached the end of this tutorial.
Controlling access to Crystal applications
You can use rights to control users’ access to certain features in Crystal Enterprise
applications. You can grant or deny users access to the Crystal Management
Console. For the Crystal Enterprise web desktop, you can grant users or groups the
ability to:
• change their preferences
• organize folders
• search
• filter object listings by object type
• view the Favorites folder
For example, if you have already created your users’ folders using a standard
naming convention, you may want to deny your users the ability to organize their
own folders.
Note: By default, all users have access to these features.
To grant access to a Crystal application’s features
1 Go to the Crystal Applications management area of the CMC.
2 To change access rights for the Crystal Enterprise web desktop, click Web
Desktop.
To change access rights for the CMC, click Crystal Management Console.
3 Click the Rights tab.
4 Click Add/Remove to add users or groups you want to give access to the features.
5 On the Add/Remove page, in the Select Operation list, select Add/Remove
Groups, Add Users, or Remove Users.
6 Select the user or group you want to grant access to the features.
Crystal Enterprise Administrator’s Guide
173
Controlling administrative access
Tip: If you have many users on your system, select the Add Users operation;
then use the “Look for” field to search for a particular account.
7 Click OK.
8 On the Rights tab, click Advanced.
9 For each feature, choose Inherited, Explicitly Granted, or Explicitly Denied
for the user or group.
10 Click OK.
Controlling administrative access
In addition to controlling access to objects and settings, you can use rights to divide
administrative tasks between functional groups within your organization. For
example, you may want people from different departments to manage their own
Crystal Enterprise users and groups. Or you may have one administrator who
handles high-level management of Crystal Enterprise, but you want all server
management to be handled by people in your IT department. With all of the tasks
facing a Crystal Enterprise administrator, it can be very helpful to delegate
responsibility to other managers and groups.
This section describes how to grant rights for managing users, groups, servers, and
server groups.
174
Crystal Enterprise Administrator’s Guide
10: Controlling User Access
Controlling access to users and groups
You can delegate user and group administration to the appropriate people in your
organization by granting specific access rights.
For example, you can grant people from different departments the rights to
manage their own users’ Crystal Enterprise content. If you have a SalesAdmin
group that includes managers from the sales department, and a SalesUser group
that contains all of the salespeople, you grant SalesAdmin the rights to view, edit,
and delete content created by members of the SalesUser group.
You can grant other users or groups administrative access to a user.
Administrative rights include: viewing, editing, and deleting the user’s objects;
viewing and deleting object instances; and pausing object instances.
Note: You cannot grant people the right to add or delete users and groups. Only
the Crystal Enterprise administrator can add or delete users and groups.
To grant access to a user or group
1 Go to the Users or Groups management area of the CMC.
2 Select the user or group you want to grant access to.
3 Click the Rights tab.
4 Click Add/Remove to add users or groups that you want to give access to the
selected user or group.
The Add/Remove page appears.
5 In the Select Operation list, select Add/Remove Groups, Add Users, or
Remove Users.
6 Select the user or group you want to grant access to the specified user or group.
In this example, the SalesAdmin group is granted access to the SalesUser group.
Tip: If you have many users on your system, select the Add Users operation;
then use the “Look for” field to search for a particular account.
Crystal Enterprise Administrator’s Guide
175
Controlling administrative access
7 Click OK.
8 On the Rights tab, change the Access Level for each user or group, as required.
9 To choose specific rights, choose Advanced.
Note: For complete details on the predefined access levels and advanced
rights, see “Rights and Access Levels” on page 413.
10 Click Update.
Controlling access to servers and server groups
You can use rights to grant people access to servers and server groups, allowing
them to perform tasks such as starting and stopping servers.
Depending on your system configuration and security concerns, you may want to
limit server management to the Crystal Enterprise administrator. However, you
may need to provide access to other people using those servers. Many
organizations have a group of IT professionals dedicated to server management. If
your server team needs to perform regular server maintenance tasks that require
them to shut down and start up servers, you need to grant them rights to the
servers. You may also want to delegate Crystal Enterprise server administration
tasks to other people. Or you may want different groups within your organization
to have control over their own server management.
To grant access to a server or server group
1 Go to the Servers or Server Groups management area of the CMC.
2 Select the server or server group you want to grant access to.
3 Click the Rights tab.
4 Click Add/Remove to add users or groups that you want to give access to the
selected server or server group.
The Add/Remove page appears.
5 In the Select Operation list, select Add/Remove Groups, Add Users, or
Remove Users.
6 Select the user or group you want to grant access to the specified server or
server group.
Tip: If you have many users on your system, select the Add Users operation;
then use the “Look for” field to search for a particular account.
7 Click OK.
8 On the Rights tab, change the Access Level for each user or group, as required.
9 To choose specific rights, choose Advanced.
Note: For complete details on the predefined access levels and advanced
rights, see “Rights and Access Levels” on page 413.
10 Click Update.
176
Crystal Enterprise Administrator’s Guide
Managing Objects
11
This chapter describes the management of objects using the
Crystal Management Console. It includes general
information that applies to all objects, and it includes
specific information about managing reports, programs,
and object packages.
Crystal Enterprise Administrator’s Guide
177
Managing objects overview
Managing objects overview
There are several types of objects that can exist in 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. After publishing
objects to Crystal Enterprise, you manage them through the Crystal Management
Console (CMC) by going to the Objects management area.
Tip:
• Go to the Object management area by clicking the Objects link on the CMC
Home page.
• Use folders to organize and facilitate object administration for you and your
users. For more information, see “Managing User Folders” on page 113.
This chapter is broken up into four sections:
• General object management
This section describes general object management concepts that apply to all
objects, such as moving, copying, and deleting objects. It also describes how to
search for objects, how to modify object properties, and how to set object rights
for users and groups. For details, see “General object management” on page 178.
• Report object management
This section explains report objects and instances, and how to manage them
through the Crystal Management Console (CMC). Managing report objects
includes applying processing extensions, specifying alert notification, changing
database information, updating parameters, using filters, and working with
hyperlinked reports. For details, see “Report object management” on page 184.
• Program object management
This section explains program objects and instances, and how to manage them
through the Crystal Management Console (CMC). Additionally, this section
covers type-specific program object configuration, and security considerations
for program objects. For details, see “Program object management” on page 201.
• Object package management
This section explains object packages and instances, and how to manage them
through the Crystal Management Console (CMC). Additionally, this section
explains how to create an object package and how to add objects to an object
package. For details, see “Object package management” on page 208.
General object management
To change the settings of an object and its instances, in the Crystal Management
Console (CMC), go to the Objects management area and then select an object by
clicking its link, which is located in the Object Title column. Once you have selected
your object, click the appropriate tab to change the object and instances settings.
178
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Tip: You can also manage an object by going to the Folders management area in
the CMC, selecting a folder (and any subfolders) by clicking the appropriate
link(s), and selecting the object that is located under the Object Title column.
Copying, moving, or creating a shortcut for an object
Use this procedure to copy, move, or create a shortcut to an object within Crystal
Enterprise:
• “Copy” creates another copy of the object in a different location. The new copy
of the object inherits all object rights from its new parent folder.
• “Move” changes the location of the object from one folder to another. The
object retains its original set of object rights.
• “Create shortcut” enables you to create an alternate, more convenient, access
route for an object. You can also create a shortcut to give users access to the
object when you don’t want them to access the folder that the actual object is
located in. The shortcut inherits object rights from its parent folder. However,
the shortcut object rights do not override the rights of the original object. For
example, if a user does not have rights to schedule a report, they are not able to
schedule that report even through a shortcut that allows them full rights.
To copy, move, or create a shortcut for an object
1 Go to the Objects management area of the CMC.
2 Select the check boxes associated with the object(s) you want to copy, move, or
create a shortcut for.
3 Click Copy/Move/Shortcut.
The Copy/Move/Create Shortcut page appears.
Crystal Enterprise Administrator’s Guide
179
General object management
4 Select one of the three following options:
• Copy to
• Move to
• Create shortcut in
Tip: You may want to create a shortcut if you want to give someone access to
an object without giving that user access to the entire folder that the object is
located in. After you create the shortcut, users who have access to the folder
where the shortcut is located can access this object and its instances. For more
information on folder rights, see “Specifying folder rights” on page 111.
5 Select the appropriate destination folder; then click OK.
Tip:
• To expand a folder, select it and click Show Subfolders.
• To search for a specific folder or object package, use the Look For field.
Deleting an object
This procedure explains how to delete either a single object or multiple objects.
You can also delete a folder (by selecting a folder and clicking Delete in the Folders
management area), which deletes all of the objects and instances that are stored in
that folder. As well, you have the option of deleting object instances, rather than
the object itself. For more information, see “Managing and viewing the history of
instances” on page 248.
Note: When you delete an object, all of its existing instances and scheduled
instances will be deleted.
To delete an object
1 Go to the Objects management area of the CMC.
2 Select the check boxes associated with the object(s).
3 Click Delete.
4 Click OK.
Searching for an object
The search feature enables you to search for specific text within object titles or
descriptions.
To search for an object or objects
1 Go to the Objects management area of the CMC.
2 Specify the search criteria.
In the “Search for” fields, specify the object field to search (title or description)
and the matching method to use (is, is not, contains, does not contain). In the
Text field, type the text to search for.
180
Crystal Enterprise Administrator’s Guide
11: Managing Objects
3 Click Search.
Changing properties of an object
In the Properties page of an object, you can modify an object’s title and description.
As well, you can view its file name, its location, and the date it was created. For
objects that can be scheduled (reports, programs, and object packages), you can see
the last times the object was modified and/or run.
To finalize changes, click Update. Note that once you have clicked Update, you
cannot click Reset to undo changes.
For Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Adobe Acrobat, Text,
and Rich Text objects, a View button appears on the Properties page. Provided that
you have the appropriate software installed on your browser machine, you can
click the View button to open and view the object.
Crystal Enterprise Administrator’s Guide
181
General object management
Similarly, for report objects, a Preview button appears. The Preview button enables
you to view a report on demand with all of your current report settings. Crystal
Enterprise connects to the report’s data source(s) if no cached pages are available.
To use the Preview function, the user will need to have rights at the Schedule level
or higher. (To preview a report with saved data, the user will need to have rights
at the View level or higher.) By default, administrators have rights at the Full
Control level (the highest rights setting) for all report objects. For details about
object rights, see “Setting object rights for users and groups” on page 182.
For reports, the “Show report thumbnail” check box is selected by default. If you do
not want a thumbnail preview of this report to be available in the Crystal Enterprise
web desktop or another web application, clear the Show report thumbnail check box.
Note: A thumbnail is a graphical representation of the first page of a report. If the
original report does not contain a thumbnail, then a thumbnail will not be stored
on Crystal Enterprise.
For object packages, the ”Scheduled package fails upon individual component
failure” check box is selected by default. (A component is an object in an object
package.) This means that if one of the component instances in a package fails, the
object package instance in the History will appear as Failed. If you do not want the
object package instance to fail if one of the component instances fails, clear the
“Scheduled package fails upon individual component failure” check box.
Setting object rights for users and groups
Object rights enable you to set access levels for your users and groups. You control
which folders, reports, and other objects users and groups can access using Crystal
Enterprise. You set security settings at the object level. For objects that can be
scheduled, the security settings are also reflected in the object instances object.
To facilitate administration, Crystal Enterprise includes a set of predefined rights
(“access modes”) that allow you to set common security levels quickly. These
include the following:
• Inherited Rights
• No Access
• View
• Schedule
• View On Demand
• Full Control
• Advanced
In addition to setting user and group rights for report objects from the Objects
management area, you can also set user and group rights at the folder level. When
you set rights at the folder level, these limits will be in effect for all objects that
inherit rights from the folder (including any objects found within the subfolders).
182
Crystal Enterprise Administrator’s Guide
11: Managing Objects
For detailed information on the different “access modes” for object rights and
information on inherited rights, see “Controlling users’ access to objects” on
page 142.
To add groups or users to an object’s rights settings
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Rights tab.
The Rights tab appears.
3 Click Add/Remove.
4 Select an option in the Select Operation list.
5 Select the group(s) or user(s) you would like to add or remove.
6 Click the > arrow to add the group(s) or user(s); click the < arrow to remove
the group(s) or user(s).
7 Click OK.
To change a group or user’s report rights
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Rights tab.
The Rights tab appears.
Crystal Enterprise Administrator’s Guide
183
Report object management
3 Change the access level for a group or user by selecting a right from the
appropriate list in the Access Level column; then click Update.
If you select Advanced from the list, you grant or deny granular rights from the
Advanced Rights page. For more information, see “Setting advanced object
rights” on page 146.
Report object management
This section explains report objects and instances, and how to manage them through
the Crystal Management Console (CMC). Managing report objects includes applying
processing extensions, specifying alert notification, changing database information,
updating parameters, using filters, and working with hyperlinked reports.
Note:
• When you update a report object from the CMC, your changes affect users
who schedule and view reports through Crystal Enterprise; for instance, if you
change the parameter settings for a report object in the CMC, when users
schedule and view reports through a web-based client such as the Crystal
Enterprise web desktop or a custom web application, the parameter
information will be changed for them as well. As such, if you want to update
the settings of a report object without changing the settings of the report object
and its instances permanently, then schedule the reports through the web
desktop or a custom web application. For information on the Crystal
Enterprise web desktop, see the Crystal Enterprise User’s Guide.
• Crystal Enterprise supports reports created in versions 6 through 10 of Crystal
Reports. Once published to Crystal Enterprise, reports are saved, processed,
and displayed in version 10 format.
What are report objects and instances?
A report object is an object that is created using a Crystal designer component
(such as Crystal Reports or Crystal Analysis). Report objects contain report
information (such as database fields). When you schedule a report, Crystal
Enterprise generates an instance or instances of the object. A report object can be
made available to everyone or to individuals in selected user groups.
Note: When you publish a report object to Crystal Enterprise, only the structure
of the report (the template information) is saved; that is, the published report
object contains no saved data.
Crystal Enterprise creates report instances from report objects—that is, an instance
is created when a report object is processed by the Report Job Server. Essentially,
an instance is a report object that contains report data that is retrieved from one or
more databases. Each instance contains data that is current at the time the report
or query is processed.
184
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Typically, report objects are designed such that you can create several instances with
varying characteristics. You can schedule a report object to have several instances.
For example, if you run a report object with parameters, you can schedule one
instance that contains report data that is specific to one department and schedule
another instance that contains information that is specific to another department,
even though both instances originate from the same report object. For more
information about scheduling, see “Scheduling objects overview” on page 212.
Changes that are made to the report object affect future scheduled instances. These
changes also affect instances that users schedule through a Crystal Enterprise
application, such as the Crystal Enterprise web desktop or a custom web application.
Setting report refresh options
You can set report refresh options that determine which settings of a report object
are updated when you refresh it in Crystal Enterprise.
When you refresh a report object, Crystal Enterprise compares the report object
stored in Crystal Enterprise with the original .rpt file stored in the Input File
Repository. Crystal Enterprise deletes or adds report elements in the report object
to make it match the .rpt file, overwriting any changes you’ve made in Crystal
Enterprise. Where report elements are the same in the source report and the report
object, the report refresh settings allow you to control which settings in the report
object are updated with values from the source .rpt file.
For example, if a prompt appears only in the source .rpt file, then refreshing the
report adds the prompt to the report object. This holds true no matter which report
refresh options you select.
If a prompt appears in both the source .rpt and the report object and you have
selected the “Prompt Values” option, then Crystal Enterprise updates the default
value of the prompt in the report object. Any changes that you have made to the
default value of the parameter in Crystal Enterprise are overwritten.
To preserve your changes to the values of report elements when you refresh a
report, clear the appropriate report refresh option.
Note:
• If you select Prompt Values, Crystal Enterprise ensures that changes to either
the default value of a prompt or to the current value of a prompt are updated
in the report object when the report is refreshed.
• If you select Prompt Options, Crystal Enterprise ensures that changes to the
metadata describing a prompt is updated in the report object. For example,
“Can be null” is a prompt option.
• If you select “Use Object Repository when refreshing report”, repository
objects in the report object will be refreshed against the repository. For more
information, see “Refreshing repository objects in published reports” on
page 258.
Crystal Enterprise Administrator’s Guide
185
Report object management
To set a report object’s refresh options
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 On the Properties page, click the Refresh Options link.
3 Choose the report elements that you want to refresh from the source report file.
4 Click Refresh Report.
Setting report viewing options
The report viewing options available in Crystal Enterprise allow you to balance
users’ need for up-to-date information with the need to optimize data retrieval
times and overall system performance.
Crystal Enterprise allows you to enable data sharing, which permits different users
accessing the same report object to use the same data when viewing or refreshing
a report. Enabling data sharing reduces the number of database calls, thereby
reducing the time needed to generate a report instance for subsequent users of the
same report, while greatly improving overall system performance under load.
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. (See “Specifying servers for viewing and modification”
on page 187.) Per-report settings permit you to specify that particular reports will
not share data. 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.
Data sharing may not be ideal for all organizations, or for all reports. 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.
The default report viewing options for Crystal Enterprise emphasize data
freshness and integrity. By default, when you add a report to Crystal Enterprise it
is configured to use per-server settings for report sharing. The default server
settings ensure that users always receive up-to-date information when they refresh
a report, and guarantee that the oldest data given to any user is 0 minutes old. If
you choose to enable per-report settings, the default settings allow data sharing,
allow a viewer refresh to retrieve fresh data from the database, and ensure that the
oldest data given to a client is 5 minutes old.
Tip: Disabling the sharing of report data between clients is not the same as setting
the “Oldest on-demand data given to a client” to 0 minutes. Under high load, your
system may receive more than one request for the same report instance at the same
186
Crystal Enterprise Administrator’s Guide
11: Managing Objects
time. In this case, if the data sharing interval is set to 0 but the “Share report data
between clients” option is enabled, Crystal Enterprise shares data between the
client requests. If it is important that data not be shared between different clients
(for example, because the report uses a User Function Library (UFL) that is
personalized for each user), disable data sharing for that report.
For details on setting report viewing options on a per-server basis, see:
• “Modifying Cache Server performance settings” on page 301
• “Modifying Page Server performance settings” on page 304
• “Modifying performance settings for the RAS” on page 308
For more information on configuring Crystal Enterprise to optimize report
viewing in your system, see the planning chapter in the Crystal Enterprise
Installation Guide.
To set report viewing options for a report
1 In the Objects management area of the CMC, select a report by clicking its link.
2 Click the Process tab.
3 In the “Data Refresh for Viewing” area, click “Use report specific viewing
settings.” Then select the options that you want to set for this report.
4 Click Update.
Specifying servers for viewing and modification
You can specify the default Cache Servers, Page Servers, or Report Application
Servers that Crystal Enterprise will use when a user views or modifies a report.
When specifying your servers, you have three options:
• Use the first available server.
• Use the servers that belong to a selected group first (and, if the servers from
that group aren’t available, use any available server).
• Use only servers that belong to a specific group.
By selecting a particular server or server group, you can balance the load of your
viewing, as specific reports can be processed using specific servers. You must first
create server groups by going to the Server Groups management area in the CMC
before you are able to select servers that belong to a selected group. You can also
set the maximum number of jobs a server will accept. For more information, see
“Modifying Cache Server performance settings” on page 301, “Modifying Page
Server performance settings” on page 304, or “Modifying performance settings for
the RAS” on page 308.
Note:
• If you choose the “Use the first available server” option, the Crystal
Management Server (CMS) will check the servers to see which one has the
lowest load. The CMS does this by checking the percentage of the maximum
Crystal Enterprise Administrator’s Guide
187
Report object management
load on each server. If all of the servers have the same load percentage, then
the CMS will randomly pick a server.
• See “Specifying servers for scheduling” on page 212 for information on
specifying Job Servers used to schedule an object.
To specify the servers to use for a report object
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Process tab.
3 In the “Default Servers To Use For Viewing” area, choose from one of the three
options:
• Use the first available server
Crystal Enterprise will use the server that has the most resources free at the
time of viewing.
• Give preference to servers belonging to the selected group
Select a server group from the list. This option will attempt to process the
object from the servers that are found within your server group. If the
specified servers are not available, then the object will be processed on the
next available server.
• Only use servers belonging to the selected group
This option ensures that Crystal Enterprise will only use the specified
servers that are found within the selected server group. If all of the servers
in the server group are unavailable, then the object will not be processed.
4 Click Update.
188
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Applying processing extensions to reports
Crystal Enterprise supports the use of customized processing extensions. A
processing extension is a dynamically loaded library of code that applies your
business logic to particular Crystal Enterprise view or schedule requests before they
are processed by the system. This section shows how to register your processing
extension with Crystal Enterprise, and how to apply an available processing
extension to a particular report object.
For general information about processing extensions and how you can use them to
customize report processing and security, see “Processing extensions” on page 56.
For information on writing your own processing extensions with the Processing
Extension API, see the developer documentation available on your product CD.
Note: On Windows systems, dynamically loaded libraries are referred to as
dynamic-link libraries (.dll file extension). On UNIX systems, dynamically loaded
libraries are often referred to as shared libraries (.so file extension). You must
include the file extension when you name your processing extensions. Also, file
names cannot include the \ or / characters.
Registering processing extensions with the system
Before you can apply your processing extensions to particular objects, you must
make your library of code available to each machine that will process the relevant
schedule or view requests. The Crystal Enterprise installation creates a default
directory for your processing extensions on each Job Server, Page Server, and
Report Application Server (RAS). It is recommended that you copy your
processing extensions to the default directory on each server. On Windows, the
default directory is C:\Program Files\Crystal Decisions\Enterprise
10\win32_x86\ProcessExt. On UNIX, it is the crystal/processext directory.
Tip: It is possible to share a processing extension file. For details, see “Sharing
processing extensions between multiple servers” on page 191.
Depending upon the functionality that you have written into the extension, copy
the library onto the following machines:
• If your processing extension intercepts schedule requests only, copy your
library onto each machine that is running as a Job Server.
• If your processing extension intercepts view requests only, copy your library
onto each machine that is running as a Page Server or RAS.
• If your processing extension intercepts schedule and view requests, copy your
library onto each machine that is running as a Job Server, Page Server, or RAS.
Note: If the processing extension is required only for schedule/view requests
made to a particular Server Group, you need only copy the library onto each
processing server in the group.
Crystal Enterprise Administrator’s Guide
189
Report object management
To register a processing extension with the system
1 Go to the Objects management area of the CMC.
2 Click Object Settings.
3 In the Name field, type a display name for your processing extension.
4 In the Location field, type the file name of your processing extension along
with any additional path information:
• If you copied your processing extension into the default directory on each
of the appropriate machines, just type the file name (but not the file
extension).
• If you copied your processing extension to a subfolder below the default
directory, type the location as: subfolder/filename
Note: Although the actual file name must include the .dll or .so extension (as
appropriate to the server’s operating system), you must not include the file
extension in the Location field.
5 Use the Description field to add information about your processing extension.
6 Click Add.
Tip: You can now select this processing extension to apply its logic to particular
objects.To delete a processing extension, select its check box and click Delete.
(Make sure that no recurring jobs are based on this processing extension
because any future jobs based on this processing extension will fail.)
Selecting a processing extension for a report
1 Go to the Objects management area of the CMC.
2 Click the link to the report object that you want to apply your processing
extension to.
190
Crystal Enterprise Administrator’s Guide
11: Managing Objects
3 Click the object’s Process tab and then click the Filters link.
4 Select your processing extension in the Available Processing Extensions list.
Note: Your processing extensions appear in this list only after you have
registered them with the system.
5 Click Add.
Tip: You may apply more than one processing extension to a report object.
Repeat steps 4 and 5 for each processing extension; then use the up and down
arrows to specify the order in which the processing extensions should be used.
6 Click Update.
Your processing extension is now enabled for this report object.
Sharing processing extensions between multiple servers
If you want to put all processing extensions in a single location, you can override
the default processing extensions directory for each Job Server, Page Server, and
RAS. First, copy your processing extensions to a shared directory on a network
drive that is accessible to all of the servers. Map (or mount) the network drive from
each server’s machine.
Note: Mapped drives on Windows are valid only until you reboot the machine.
For details, see “Ensuring that server resources are available on local drives” on
page 404.
If you are running servers on both Windows and on UNIX, you must copy a .dll
and an .so version of every processing extension into the shared directory. In
addition, the shared network drive must be visible to Windows and to UNIX
machines (through Samba or some other file-sharing system).
Crystal Enterprise Administrator’s Guide
191
Report object management
Finally, change each server’s command line to modify the default processing
extensions directory. Do this by adding “-report_ProcessExtPath <absolute
path>” to the command line. Replace <absolute path> with the path to the new
folder, using whichever path convention is appropriate for the operating system
that the server is running on (for example, M:\code\extensions, /home/shared/code/
extensions, and so on).
The procedure for making this modification depends upon your operating system:
• On Windows, use the CCM to stop the server. Then open the server’s
Properties to modify the command line. Start the server again when you have
finished.
• On UNIX, run ccm.sh to stop the Report Job Server/Page Server. Then edit
ccm.config to modify the server’s command line. Start the server again when
you have finished. For reference, see “ccm.sh” on page 436.
Specifying alert notification
Alerts are custom messages, created in Crystal Reports, that appear when certain
conditions are met by data in a report. Alerts may indicate action to be taken by the
user or information about report data. If the alert condition (as defined in Crystal
Reports) is true, the alert is triggered and its message is displayed.
In Crystal Enterprise, you can choose to send alert notification when scheduling a
report. If you enable alert notification, messages are sent through an SMTP server.
You can configure email delivery options, specify the “To,” “Cc,” and “From”
fields for the email, add subject and message information, set a URL for the viewer
you want the email recipient to use, and set the maximum number of alert records
to send.
Note:
• The Alert Notification link is available only if the report object contains alerts.
• Alerts are triggered in the report object even if you disable alert notification.
• To enable alert notification, you must also ensure that the Report Job Server’s
SMTP Destination is enabled and configured. For details, see “Setting the
default email (SMTP) destination” on page 312.
To set alert notification
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 Click the Schedule tab, and then click the Alert Notification link.
The Alert Notification page appears.
192
Crystal Enterprise Administrator’s Guide
11: Managing Objects
3 Clear the Enable alert notification check box if you do not want to send an
alert notification.
4 Select either Use the Crystal Job Server’s defaults or Set the values to be used
at schedule time here.
If you select the first option, Crystal Enterprise will deliver the alert notification
using the Report Job Server’s default settings. You can change these settings in
the Servers management area. For more information, see “Setting default
scheduling destinations for Job Servers” on page 309.
If you select the second option, you can specify the email settings:
• From
Type a return address or distribution list.
• To
Type the addresses or distribution list that you wish to send the report to.
Crystal Enterprise Administrator’s Guide
193
Report object management
• Cc
Type the addresses or distribution list that you wish to send a copy of the
alert notification to.
• Subject
Complete the subject field.
• Message
Type a short message, if required.
Note: Separate multiple addresses or distribution lists using semicolons.
5 Type the URL for the viewer in which you want the email recipient to view the
report. Alternatively, you can select the default viewer by clicking Use default.
The viewer URL appears in the hyperlink that is sent in the alert notification
email. You can set the default URL by clicking Object Settings on the main page
of the objects management area of the CMC. For more information, see the
developer documentation available on your product CD.
Note: You must use World Wide Web Consortium (W3C) URL encoding when
typing the viewer URL. For example, replace spaces in the path with %20. For
more information, see http://www.w3.org/
6 Type the maximum number of alert records to be included in the alert
notification.
The hyperlink in the alert notification displays a report page that contains the
records that triggered the alert. Use this field to limit the number of records
displayed.
Tip: The Alert Name and Status fields are set in Crystal Reports.
7 Click Update.
Changing database information
You can select your database type and set the default database logon information
on the Database page for a report. The Database page displays the data source or
data sources for your report object and its instances. You can choose to prompt the
user for a logon name and password when he or she views a report instance.
To change database settings
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 Click the Process tab, and then click the database link.
194
Crystal Enterprise Administrator’s Guide
11: Managing Objects
The Database page appears.
3 In the Data Source(s) list, select the data source.
4 Select Use original database logon information from the report or Use
custom database logon information specified here.
If you select the first option, you can specify a user name and password to be
used with the original report database.
If you select the second option, you can specify a server name (or a DSN in the
case of an ODBC data source), a database name, a user name, and a password
for a number of predefined database drivers, or for a custom database driver
that you’ve specified. If you’ve changed the default table prefix in your
database, specify a custom table prefix here.
The predefined database drivers include: ODBC drivers and native Oracle,
DB2, Sybase, and Informix drivers.
Crystal Enterprise Administrator’s Guide
195
Report object management
5 Select the Prompt the user for database logon when viewing check box if you
want users to be prompted for a password when they refresh a report after
viewing it once.
Note: This option has no effect on a scheduled instance. Also, Crystal
Enterprise only prompts users when they first refresh a report; that is, if they
refresh the report a second time, they will not be prompted.
6 Click Update.
Updating parameters
Parameter fields (with preset values) enable users to view and to specify the data
that they want to see. If a report contains parameters, you can set the default
parameter value for each field or fields (which is used whenever a report instance
is generated). Through a Crystal Enterprise application such as the Crystal
Enterprise web desktop, your users are either able to use the report with the preset
default value(s) or choose another value or values. If you do not specify a default
value, users will have to choose a value when they schedule the report.
Note: The Parameters link is available only if the report object contains parameters.
To view parameter settings
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 Click the Process tab, and then click the Parameters link.
3 Under the Value column, select the value associated with the parameter you
want to change.
A page opens that allows you to change the parameter value. Depending on the
parameter value type, you either type a value in the field or choose a value from
a list. If there is a list, you can also click Edit to type a new value.
196
Crystal Enterprise Administrator’s Guide
11: Managing Objects
4 Select the Clear the current parameter value(s) check box if you want to clear
the current value that is set for the specified parameter.
5 Select the Prompt the user for new value(s) when viewing check box if you
want your users to be prompted when they view a report instance through a
Crystal Enterprise application such as the Crystal Enterprise web desktop.
6 Click Submit.
Using filters
In the Filters page, you set the default selection formulas for the report. Selection
formulas are similar to parameter fields in that they are used to filter results so that
only the required information is displayed. Unlike parameters, end users will not
be prompted for selection formula values when they view or refresh the report.
When users schedule reports through a web-based client such as the Crystal
Enterprise web desktop, they can choose to modify the selection formulas for the
reports. By default, if any formulas are set in the CMC, they will be used by the
web-based client. For more information on selection formulas, see the Crystal
Reports User’s Guide.
In addition to changing selection formulas, if you have developed your own
processing extensions, you can select the processing extensions that you want to
apply to your report. For more information, see “Applying processing extensions
to reports” on page 189. When you use filters in conjunction with processing
extensions, a subset of the processed data is returned. Selection formulas and
processing extensions act as filters for the report.
Crystal Enterprise Administrator’s Guide
197
Report object management
To use filters
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 Click the Process tab, and then click the Filters link.
The Filters page appears.
3 Update or add new selection formulas.
• Record Selection Formula
Use the Record Selection Formula to create or edit a record selection
formula or formulas that limit the records used when you or a user
schedules a report.
• Group Selection Formula
Use the Group Selection Formulas to create or edit a group selection
formula or formulas that limit the groups used when you or a user
schedules a report.
4 In the processing extensions area, where appropriate, select a processing
extension from the Available Processing Extensions list and then click Add.
5 Click Update.
198
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Working with hyperlinked reports
Crystal Reports lets you use hyperlinks to navigate from one report object to
another. You can move to a Report Part within the report itself, to other report
objects or their parts, or to specific instances of reports or Report Parts. This
navigation is available only in the new script-based DHTML viewers (zero-client,
server-side viewers) included in Crystal Enterprise 10. By linking directly from one
object to another, the required data context is passed automatically so that you
navigate to the object and data that is relevant.
Initially, when you add hyperlinks between reports in Crystal Reports, you create
a link from one file directly to another. However, when you publish linked report
files simultaneously to the same object package, the links are modified to point to
managed report objects. (Each link is changed, so that it references the appropriate
destination report by Enterprise ID, rather than by file path.) Also, the modified
links become relative inside the object package. When you schedule the object
package, Crystal Enterprise processes its reports, and again modifies hyperlinks
within each report instance: hyperlinks between report objects in an object package
are converted to hyperlinks between report instances in a specific instance of the
object package. For more information on object packages, see “Scheduling objects
in batches” on page 232.
To view hyperlinked reports, you must publish both the home and destination
reports to the same Crystal Enterprise system. (A home report is one that contains
a hyperlink to another report: the destination report.)
Note: For information about how to create hyperlinks between report objects, see
the Crystal Reports Online Help.
Publishing and hyperlinking reports
The most efficient way to hyperlink between published reports is first to publish
the individual reports, then create the hyperlinks between them. To do so, create
the reports—without hyperlinks—in Crystal Reports, and publish them to Crystal
Enterprise. Next, use Crystal Reports to log on to your Crystal Enterprise system
and create the hyperlinks between the home and destination reports. (For details,
see the Crystal Reports Online Help.) Crystal Reports automatically determines what
type of link—relative or absolute—to establish between the reports. In Crystal
Enterprise, relative links are those between reports in the same object package, and
absolute links are links to specific report objects or instances.
Publishing reports with existing hyperlinks
The recommended method for creating hyperlinked reports is first to publish the
individual reports, then create hyperlinks between them. However, because this is
not always possible, this section explains how to publish reports after they have
been hyperlinked.
Crystal Enterprise Administrator’s Guide
199
Report object management
Depending on how you choose to publish hyperlinked reports to Crystal Enterprise,
existing hyperlinks between reports may be broken or modified. To preserve
existing hyperlinks between reports, you must use the Crystal Publishing Wizard to
publish the reports (that are linked to each other) to the same object package. When
you publish reports this way, the hyperlinks are converted to relative links.
If you publish hyperlinked reports independently of each other, rather than
publishing them simultaneously to the same object package, all hyperlinks
between the reports will break. You must re-establish the links using Crystal
Reports and save the report back to Crystal Enterprise. (For more information, see
the Crystal Reports Online Help.)
Viewing hyperlinks in a report
You can view a list of the links in a report by clicking the Links link on the report’s
Properties page. The links are listed as either relative or absolute. In Crystal
Enterprise, relative links are those between reports in the same object package, and
absolute links are links to specific report objects or instances.
To view a list of links in a report object
1 In the Objects management area of the CMC, select the report object by
clicking its link.
2 Click the Properties tab, and then click the Links link.
The Links page appears.
Viewing hyperlinked reports
Crystal Enterprise supports navigation between hyperlinked reports only with
script-based viewers, specifically the DHTML and Advanced DHTML viewers in
the Crystal Enterprise web desktop. To change your preferred viewer in the CMC,
click the Preferences button in the upper-right corner of the CMC, and select the
appropriate viewer from the Viewer list. For information on how to change your
preferred viewer, see the Crystal Enterprise User’s Guide.
Parameter information is not carried over between the home and destination reports.
That is, when you view a destination report by clicking a hyperlink in a home report,
you are prompted to enter any parameters that the destination report requires.
Security considerations
To view hyperlinked reports through Crystal Enterprise, you must have the
appropriate rights both in Crystal Enterprise and at the database level.
In Crystal Enterprise, to view a destination report through a hyperlink in a home
report, you must have View rights to the destination report. When the hyperlink
points to a report object, you must have View On Demand rights to be able to
refresh the data against the data source. For information about setting the levels of
access to objects, see “Setting common access levels” on page 144.
200
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Database logon information is carried over between hyperlinked reports. If the
credentials you specified to view the home report are not valid for the destination
report, you are prompted for a valid set of database logon credentials for the
destination report.
Program object management
This section explains program objects and instances, and how to manage them
through the Crystal Management Console (CMC). Additionally, this section covers
type-specific program object configuration, and security considerations for
program objects.
What are program objects and instances?
A program object is an object in Crystal Enterprise that represents an application.
Publishing a program object to Crystal Enterprise allows you to use Crystal
Enterprise to schedule and run the program object and to manage user rights in
relation to the program object. For information about publishing program objects,
see “Publishing overview” on page 116.
When you publish a program object or its associated files to Crystal Enterprise, they
are stored in the File Repository Server (FRS). Each time a Crystal Enterprise program
runs, the program and files are passed to the Program Job Server, and Crystal
Enterprise creates a program instance. Unlike report instances, which you can view
in their completed format, program instances exist as records in the object history.
Crystal Enterprise stores the program’s standard out and standard error in a text
output file. This file appears when you click a program instance in the object History.
Three types of applications can be published to Crystal Enterprise as program objects:
• Executable
Executable programs are binary files, batch files, or shell scripts. They generally
have file extensions such as: .com, .exe, .bat, .sh. You can publish any executable
program that can be run from the command line on the machine that runs the
Program Job Server.
• Java
You can publish any Java program to Crystal Enterprise as a Java program
object. For Java program objects to have access to Java SDK objects, your class
must implement the IProgramBase interface from the Crystal Enterprise Java
SDK (com.crystaldecisions.sdk.plugin.desktop.program.IProgramBase). For
details, see the Crystal Enterprise Java SDK Guide.
• Script
Script program objects are JScript and VBScript scripts. They are run on Windows
using an embedded COM object and can—once published—reference the Crystal
Enterprise SDK objects. For details, see the Crystal Enterprise COM SDK Guide.
Note: Script program objects are not supported on UNIX.
Crystal Enterprise Administrator’s Guide
201
Program object management
Note: As the administrator, you can choose to enable or disable any of the types of
program objects. For details, see “Authentication and program objects” on
page 206.
Once you have published a program object to Crystal Enterprise, you can
configure it in the Objects management area of the CMC. For each type of program
object (Executable, Java, or Script) you can choose to specify command-line
arguments and a working directory. For executable and Java programs, there are
additional ways, both required and optional, to configure the program objects and
provide them with access to other files.
Tip: Program objects allow you to write, publish, and schedule scripts or Java
programs that run against Crystal Enterprise, and perform maintenance tasks,
such as deleting instances from the history. Furthermore, you can design these
scripts and Java programs to access Crystal Enterprise session information. This
ensures that the scheduled program objects retain the security rights or restrictions
of the user who scheduled the job. (Your scripts or java programs require access to
the Crystal Enterprise SDK. For details, see the Crystal Enterprise COM SDK Guide
or the Crystal Enterprise Java SDK Guide.)
Specifying command-line arguments
For each program object that you publish to Crystal Enterprise, you can specify
command-line arguments on the Parameters page of the CMC’s Objects
management area. You can specify any argument that is supported by the
command-line interface for your program. Arguments are passed directly to the
command-line interface, without parsing.
To specify command-line arguments
1 In the Objects management area of the CMC, select the program object by
clicking its link.
2 Click the Process tab, then click the Parameters link.
The Parameters page appears.
3 In the Arguments field, type the command-line arguments for your program,
using the same format you would use at the command line itself.
For example, if your program has a loops option, to set the loops value to 100,
you might type -loops 100
Setting a working directory for a program object
By default, when a program object runs, Crystal Enterprise creates a temporary
subdirectory in the Program Job Server’s working directory, and uses this
subdirectory as the working directory for the program. The subdirectory is
automatically deleted when the program finishes running.
202
Crystal Enterprise Administrator’s Guide
11: Managing Objects
You can specify an alternative working directory for the program object by
modifying the Working Directory field on the Parameters page of the object. Or, you
can modify the default setting for the working directory for the Program Job Server.
Note: The account under which the program runs must have appropriate rights to
the folder that you set as the working directory. The level of file permissions
required depend on what the program does; however, the program’s account
generally needs read, write, and execute permissions to the working directory.
For information about setting credentials for an account under which a program
object will run, see “Authentication and program objects” on page 206
To set a working directory for a program object
1 In the Objects management area of the CMC, select the program object by
clicking its link.
2 Click the Process tab, then click the Parameters link.
The Parameters page appears.
3 In the Working Directory field, type the full path to the directory that you
want to set as the program object’s working directory.
For example, on Widows, if you created a working directory named
working_directory, type C:\working_directory
On UNIX, type /working_directory
To modify the default working directory for the Program Job Server
1 Go to the Servers management area of the CMC.
2 Click the link for Program Job Server.
The Properties page appears.
3 In the Temp Directory field, type the full path to the directory you want to set
as the working directory for the Program Job Server.
Configuring executable programs
When you publish an executable program object to the CMC, you can configure it
by providing access to external or auxiliary files either by specifying the full paths
to the files (if the files are on the same machine as the Program Job Server) or by
uploading the files. In the CMC, you can also customize environment variables for
the shell in which Crystal Enterprise runs the program.
When you publish an executable program object to the CMC, you can configure it
by providing it with access to other files. In the CMC, you can also customize
environment variables for the shell in which Crystal Enterprise runs the program.
Crystal Enterprise Administrator’s Guide
203
Program object management
Providing executable programs with access to other files
Some binary files, batch files, and shell scripts require access to external or auxiliary
files to run. Aside from setting a working directory for the program object, there are
two ways to provide access to these files. If a required file is on the same machine
as the Program Job Server, you can specify the full path to the file. Alternatively, if
the file is not located on the Program Job Server, you can upload the file to the File
Repository Server, which will pass the files to the Program Job Server as necessary.
To specify paths to required files
1 In the Objects management area of the CMC, select the executable program
object by clicking its link.
2 Click the Process tab, then click the Parameters link.
The Parameters page appears.
3 In the External Dependencies field, type the full path to the required file and
click Add.
4 Repeat step 3 for each file required.
Tip: To edit or remove external dependencies that you have specified, select the
file path (in the list of external dependencies on the Parameters page) and click the
appropriate button, either Edit or Remove.
To upload required files
1 In the Objects management area of the CMC, select the executable program
object by clicking its link.
2 Click the Process tab, then click the Auxiliary Files link.
The Auxiliary Files page appears.
3 Click Browse to navigate to the required file, then click Add File.
4 Repeat step 3 for each required file.
Tip: To remove auxiliary files that you have specified, select the file(s) (in the list
of external dependencies on the Parameters page) and click Remove File(s).
Specifying environment variables
In the CMC, you can configure your program by adding or modifying environment
variables. Modifications to an existing environment variable override this variable,
rather than append to it. Any changes you make to environment variables exist
only in the temporary shell in which Crystal Enterprise runs the program. Thus,
when the program exits, the environment variables are destroyed.
To add an environment variable
1 In the Objects management area of the CMC, click the link for the program object.
204
Crystal Enterprise Administrator’s Guide
11: Managing Objects
2 Click the Process tab, then click the Parameters link.
The Parameters page appears.
3 In the Environment Variables field, type the environment variables you want
to set.
Use the form name=value, where name is the environment variable name and
value is the value for the environment variable. For example, you can set the
path variable to append a user’s bin directory to the existing path:
• On Windows, you might type: path=%path%;c:\usr\bin
• On UNIX, you might type:PATH=$PATH:/usr/bin
Note: Crystal Enterprise sets your environment variables using the syntax that
is appropriate for your operating system. However, on UNIX you must follow
convention, and use the appropriate case. For example, all name values on
UNIX must be typed in upper-case.
Tip: To edit or remove environment variables that you have specified, select the
variable (in the list of environment variables on the Parameters page), and click the
appropriate button, either Edit or Remove.
Configuring Java programs
To successfully schedule and run Java programs in Crystal Enterprise, you must
specify the required parameters for the program object. Additionally, you can
provide the Java program with access to other files located on the Program Job
Servers, and you can specify Java Virtual Machine options.
Setting required parameters for Java programs
To successfully schedule and run a Java program, you must provide Crystal
Enterprise with the base name of the .class file that implements the IProgramBase
interface from the Crystal Enterprise Java SDK.
Note: The Java Runtime Environment must be installed on each machine that is
running a Program Job Server.
To specify required parameters for Java programs
1 In the Objects management area of the CMC, click the link for the Java
program object.
2 Click the Parameters tab.
The Parameters page appears.
3 In the Class to run field, type the base name of the .class file that implements
the IProgramBase from the Crystal Enterprise Java SDK
(com.crystaldecisions.sdk.plugin.desktop.program.IProgramBase).
For example, if the file name is Arius.class, type Arius
Crystal Enterprise Administrator’s Guide
205
Program object management
Providing Java programs with access to other files
You can provide Java programs with access to files, such as Java libraries, located
on the Program Job Server.
To provide Java programs with access to other files
1 In the Objects management area of the CMC, click the link for the Java
program object.
2 Click the Process tab, then click the Parameters link.
The Parameters page appears.
3 In the Classpath field, type the full paths to the locations of any Java library
files that are required by the Java program, and stored on the Program Job
Server.
You must separate multiple paths with the classpath separator that is
appropriate to your operating system: a semi-colon for Windows, a colon for
UNIX.
Authentication and program objects
Be aware of the potential security risks associated with the publication of program
objects. As the administrator, you must protect the system against abuse. The level
of file permissions for the account under which a program object runs will
determine what modifications, if any, the program can make to files.
You can control the types of program objects users can run, and you can configure
the credentials required to run program objects.
Enabling or disabling a type of program object
As a first level of security, you can configure the types of program objects available
for use.
To enable or disable a type of program object
1 In the Objects management area of the CMC, click Object Settings.
2 Click the Program Objects tab.
3 Select the type or types of program objects you want users to run.
Authentication on all platforms
In the Objects management area of the CMC, you must specify credentials for the
account under which the program runs. This feature allows you, the administrator,
to set up a specific user account for the program, and assign it appropriate rights,
to have the program object run as that account. For details, see “Controlling users’
access to objects” on page 142. Alternatively, users who publish program objects to
206
Crystal Enterprise Administrator’s Guide
11: Managing Objects
Crystal Enterprise can assign their own credentials to a program object, to give the
program access to the system. Thus, the program will run under that user account,
and the rights of the program will be limited to those of the user. If you choose not
to specify a user account for a program object, it runs under the default system
account, which generally has rights locally but not across the network.
Note: By default, when you schedule a program object, the job fails if credentials
are not specified. To provide default credentials, click Object Settings in the
Objects management area, then click the Program Objects tab. Click “Schedule
with the following operating system credentials” and provide a default user name
and password.
To specify a user account for a program object
1 In the Objects management area of the CMC, click the link for the program
object.
2 Click the Process tab, then click the Logon link.
The Logon page appears.
3 In the User Name and Password fields, type the credentials for the user
account under which the program should run.
4 Click Update.
Authentication for Java programs
Crystal Enterprise allows you to set security for all program objects. For Java
programs, Crystal Enterprise forces the use of a Java Policy File, which has a
default setting that is consistent with the Java default for unsecure code. Use the
Java Policy Tool (available with the Java Development Kit) to modify the Java
Policy File, to suit your specific needs.
The Java Policy Tool has two code base entries. The first entry points to the Crystal
Enterprise Java SDK and allows program objects full rights to all Crystal Enterprise
JAR files. The second code base entry applies to all local files. It uses the same
security settings for unsecure code as the Java default for unsecure code.
Note:
• The settings for the Java Policy are universal for all Program Job Servers
running on the same machine.
• By default, the Java Policy File is installed to the Java SDK directory in the
Crystal Enterprise install root directory. For example, a typical location on
Windows is:
C:\Program Files\Crystal Decisions\Enterprise 10\JavaSDK\crystalprogram.policy
On Unix, a typical location is
.../solaris_install/crystal/enterprise/JavaSDK/crystal-program.policy
Crystal Enterprise Administrator’s Guide
207
Object package management
Object package management
This section explains object packages and instances, and how to manage them
through the Crystal Management Console (CMC). Additionally, this section
explains how to create an object package and how to add objects to an object
package.
Related topics
• “Scheduling objects in batches” on page 232
• “Publishing overview” on page 116
What are object packages, components, and instances?
Object packages function as distinct objects in Crystal Enterprise. Think of them as
folders you can schedule, along with all of their contents.
Object packages can be composed of any combination of report and program
objects that are published to the Crystal Enterprise system. (Non-Crystal
Enterprise objects, such as Excel, Word, Acrobat, Text, Rich Text, PowerPoint, and
Hyperlink objects, cannot be added to object packages.) The objects within an
object package are called object package component objects. Placing multiple
component objects in a single object package allows you to schedule them
simultaneously. For reports, object packages allow users to view synchronized
data across reports. Component objects are not autonomous. They have more
limited configuration options than other objects, and they do not appear in the list
of all objects on the first page of the Objects management area of the CMC. Rather,
you can only view them by opening their object package.
Crystal Enterprise creates an object package instance each time it runs an object
package. The object package instance contains individual instances of each of its
component objects. Component instances are tied to object package instances,
rather than to component objects. For example, if you run an object package, and
thereby create an instance, then remove a report object from the object package, the
existing object package instance does not change; it still contains the report
instance from the report object that you removed. Future instances of the object
package, however, will reflect the change.
For hyperlinked report instances in object package instances, the hyperlinks point
to the other report instances in the same object package instance. For details about
hyperlinked reports, see “Working with hyperlinked reports” on page 199.
Creating an object package
1 Go to the Objects management area of the CMC.
2 Click New Object, then click the Object Package tab.
The Object Package tab appears.
208
Crystal Enterprise Administrator’s Guide
11: Managing Objects
3 In the Title field, type the name of the object package you want to create.
4 In the Description field, type a description of the object package.
This field is optional.
5 Ensure the correct folder name appears in the Destination field.
Note: You cannot place object packages in the top level folder or inside other
object packages.
Tip:
• To expand a folder, select it and click Show Subfolders.
• To search for a specific folder, use the Look For field.
6 Click OK.
Note: When the object package has been added to the system, the CMC
displays the Properties page. You can now modify the properties, contents,
scheduling information, destination, user rights, object settings, and
notification for the object package.
Adding objects to an object package
In the CMC, after you have created an object package, you can add report and/or
program component objects to it. You can add previously unpublished objects
directly to the object package, or you can copy existing objects into the object package.
You can only move copies of existing objects into the object package, or between object
packages; you cannot move the existing objects themselves. For details on copying
objects, see “Copying, moving, or creating a shortcut for an object” on page 179.
When you copy an object into an object package, the component object retains the
same settings as the original object. However, once you create the copy of the
original object inside the object package, the component and the original are
separate entities. Changes in one object are not reflected in the other.
Note: You publish objects to new or existing object package using the Crystal
Publishing Wizard. For details, see “Publishing with the Crystal Publishing
Wizard” on page 117.
To publish a new object directly to an object package
1 In the Objects management area of the CMC, view an object package by
clicking its link.
2 Click the Objects tab, then click the New Object button.
3 A list of object tabs appears. Note that you can add only report objects or
program objects to an object.
4 Click the appropriate tab, Report or Program.
5 Specify the file name or, or click browse to navigate to the object you want to
publish.
Crystal Enterprise Administrator’s Guide
209
Object package management
6 Set the appropriate properties.
• For reports, set whether to generate a thumbnail for the report, and
whether to use the Object Repository when refreshing the report.
• For programs, set the program type: Executable, Java, or Script.
7 Click OK.
Configuring object packages and component objects
You can configure object packages as described in “General object management”
on page 178. Additionally, you can, and in some cases you must, configure each
component object individually. For example, you must set logon credentials and
parameters for each component object individually, rather than at the object
package level.
Component objects inside an object package have the same functionality as they
would outside of the object package, regardless of limitations of the object
package. For example, with respect to notification, object packages support only
event notification; however, you can set audit, email, and event notification for the
individual component objects inside the object package. For report objects in object
packages, processing extensions and alert notification are both supported.
However, again, these do not apply to the object package as a whole.
In contrast, you cannot set destinations or server groups for component objects.
You can only set these at the object package level. For details on setting
destinations, see “Selecting a destination” on page 237. For details on setting server
groups for objects, see “Specifying servers for scheduling” on page 212.
On the Properties page of an object package, the ”Scheduled package fails upon
individual component failure” check box is selected by default. This means that if
one of the component instances in a package fails, the object package instance in
the History will appear as Failed. If you do not want the object package instance to
fail if one of the component instances fails, clear the “Scheduled package fails upon
individual component failure” check box.
Authentication and object packages
Object packages simplifies both Enterprise and database authentication. You enter
your Enterprise authentication only once to schedule the object package, including
all of its component objects. Consequently, you must have scheduling rights for
each of the objects inside the object package. If you attempt to schedule a package
that contains one or more component objects to which you do not have schedule
rights, the component instance(s) fail(s).
For database authentication, you specify database logon information for each report
component object in the object package. (If you copied the report into the object
package, it initially inherits the database logon information of the original report.)
210
Crystal Enterprise Administrator’s Guide
Scheduling Objects
12
This chapter provides information on scheduling objects. It
includes information about configuring servers and
creating calendars for scheduling. It provides detailed
instructions for scheduling objects individually and in
batches, and scheduling with events. It also describes
distributing objects, specifying schedule notifications, and
managing instances.
Crystal Enterprise Administrator’s Guide
211
Scheduling objects overview
Scheduling objects overview
Scheduling an object lets you run it automatically at specified times. You can schedule
report objects, program objects, and object packages. (For details about object types
and object management, see “Managing objects overview” on page 178.)
When you schedule an object, Crystal Enterprise generates an instance that
contains information that is captured when the object is run. Report instances
contain relevant database information; for example, instances for program objects
contain the standard out and standard error produced by that instance of the
program. Your instance uses all of the settings that you have set in the CMC for the
original object. This chapter explains how to schedule and manage object instances
through the Crystal Management Console (CMC).
This chapter is organized into three main sections:
• Setting up scheduling
This section describes how to prepare your system for scheduling. You can
specify the servers that objects use for scheduling, and you can create calendars
to provide your users with sets of common scheduling dates.
• Scheduling objects
This section provides information on scheduling objects in various ways, such
as scheduling objects on demand, daily or monthly, in batches, or with events.
• Managing instances
This section describes how to manage instances that are created after you
schedule objects. In the CMC, you can choose from various notification options,
or you can distribute objects by choosing output formats and destinations. You
can also manage an object’s historical instances and control how many
instances are available for each object.
Setting up scheduling
Before your users can schedule objects, you need to set up the servers and prepare
the tools they’ll need for scheduling. After you publish objects, you can specify the
servers used to schedule their instances. To make scheduling easier for your users
you can create custom calendars of run dates.
Specifying servers for scheduling
You can specify the default job servers that Crystal Enterprise will use to run an
object, and to schedule and process instances. When specifying your servers, you
have three options:
• Use the first available server.
• Use the servers that belong to a selected group first (and, if the servers from
that group aren’t available, use any available server).
• Use only servers that belong to a specific group.
212
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
By selecting a particular server or server group, you can balance the load of your
scheduling, because specific objects can be processed by specific job servers. You
must first create server groups by using the Server Groups management area in the
CMC, before you can select servers that belong to a selected group. You can also
set the maximum number of jobs that a job server will accept. For more
information, see “Modifying performance settings for Job Servers” on page 308.
Also, you can balance the load of your scheduling, because specific objects can be
processed by specific job servers. You must first create server groups by using the
Server Groups management area in the CMC, before you can select servers that
belong to a selected group. You can also set the maximum number of jobs that a job
server will accept. For more information, see “Modifying performance settings for
Job Servers” on page 308.
Note:
• If you choose the “Use the first available server” option, the Crystal
Management Server (CMS) will check the job servers to see which one has the
lowest load. The CMS does this by checking the percentage of the maximum
load on each job server. If all of the job servers have the same load percentage,
then the CMS will randomly pick a job server.
• If you are scheduling a program object that requires access to files stored
locally on a Program Job Server, but you have multiple Program Job Servers,
you must specify which server to use to run the program.
• See “Specifying servers for viewing and modification” on page 187 for
information on specifying the servers used to view or modify an object.
To specify the servers to use for an object
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Process tab.
Crystal Enterprise Administrator’s Guide
213
Setting up scheduling
3 In the “Default Servers To Use For Scheduling” area, choose from one of the
three options:
• Use the first available server
Crystal Enterprise will use the server that has the most resources free at the
time of scheduling.
• Give preference to servers belonging to the selected group
Select a server group from the list. This option will attempt to process the
object from the servers that are found within your server group. If the
specified servers are not available, then the object will be processed on the
next available server.
• Only use servers belonging to the selected group
This option ensures that Crystal Enterprise will only use the specified
servers that are found within the selected server group. If all of the servers
in the server group are unavailable, then the object will not be processed.
4 Click Update.
5 In the “Default Servers To Use For Viewing” area, repeat the activities from
steps 3 and 4.
Note: “Default Servers To Use For Viewing” applies only to report objects.
Managing calendars
Calendars make it easy for you to schedule complex recurring jobs efficiently. A
calendar is a customized list of run dates for scheduled jobs. When users schedule
objects, they can use a calendar to run the job on a predefined set of dates. By
providing calendars for your users, you can create more complex processing
schedules than you can with the standard scheduling options.
Calendars are particularly useful when you want to run a recurring job on an
irregular schedule, or if you want to provide users with sets of regular scheduling
dates to choose from. Calendars also allow you to create more complex processing
schedules, combining unique scheduling dates with recurring ones.
For example, if you want a report object to run every business day except for your
country’s statutory holidays, you can create a calendar with the holidays marked
as “non-run” days, on which the report object cannot be run. Crystal Enterprise
will run the job every day you have specified as a “run” day in your calendar.
You can set up as many calendars as you want in Crystal Enterprise. Calendars you
create appear in the Calendar selection list available when you choose to schedule
an object using a calendar. When you apply the calendar to a job, Crystal
Enterprise runs the job on the run dates as scheduled.
You can apply calendars to any object that can be scheduled, including report
objects, program objects, and object packages.
214
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Creating calendars
In the Crystal Management Console (CMC), go to the Calendars management area
to create new calendars and to modify existing calendars. To create a calendar, you
need to provide a name and description. When the calendar is created, you can add
run dates to it using the Dates tab.
Tip: It is good practice to create a calendar for users to use as a template for
creating new calendars. They can copy this template calendar and modify it as
necessary. For example, you can create a default Weekdays calendar that includes
all days as run dates except weekends and company holidays.
To create a calendar
1 Go to the Calendars management area of the CMC.
2 Click New Calendar.
3 On the Properties tab, type the name and description of the new calendar.
This example creates a calendar for Canadian employees that schedules an
object on all weekdays except statutory Canadian holidays.
4 Click Update.
The new calendar is added to the system, and its Properties tab is refreshed.
You can now use the Dates tab to add run dates to this calendar. For details, see
“Adding dates to a calendar” on page 215.
Adding dates to a calendar
You can add dates to a calendar using a number of different formats. You can
choose specific dates using a yearly, quarterly, or monthly view of the calendar, or
you can choose recurring dates using general formats based on the day of the
month or week.
Crystal Enterprise Administrator’s Guide
215
Setting up scheduling
Specific dates
To add a specific date to a calendar, use the Yearly, Quarterly, and Monthly
formats to add dates to the calendars.
The Yearly format displays the run schedule for the entire year. The Quarterly
format displays the run dates for the current quarter. You can also view the
Monthly format for the calendar, which displays the run dates for the current
month. In all three formats, you can change the displayed time range by clicking
the previous and next buttons.
You can add specific dates in the Monthly calendar format. To add dates for the
Yearly and Quarterly calendar formats, click a month to open it in the Monthly
format, where you can select specific days as run dates.
For example, if your company ships products according to an irregular schedule
that cannot be defined using the daily or weekly settings, you can create a list of
these dates in a “Shipping dates” calendar. The Shipping department can now
check the inventory after each shipment by scheduling a report that uses the
calendar to run at the end of each shipping day.
216
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Recurring dates
To create a recurring pattern of monthly run dates, use the generic Monthly
formats. You can add the generic dates based on the day of the week or the day of
the month. To view existing run dates, you must use the Yearly, Quarterly, or
Monthly format; the generic formats are used to add dates to the calendar.
Although you can set a recurring schedule using the standard scheduling options,
calendars allow you to specify several different recurring run patterns at once. You
can also run instances on dates that do not follow the pattern by adding individual
days to a calendar.
For example, to schedule a report object to run on the first four days of every
month, and on the second and fourth Friday of every month, first create a new
calendar object and name it. Then, use the Generic Monthly, by Day of Month
format to add the first four days of the month to this calendar. When you update
the calendar, the Yearly format appears with the new run dates.
Crystal Enterprise Administrator’s Guide
217
Setting up scheduling
To add every second and fourth Friday to the calendar, use the Generic Monthly,
by Day of Week format.
To add dates to a calendar
1 Go to the Calendars management area of the CMC.
2 Click the link for the calendar you want to change.
3 Click the Dates tab.
4 In the “Select a calendar displaying format” list, choose from one of the five
calendar format options:
• Yearly
Yearly displays the calendar’s run dates for the year. To change the year
displayed, you can click the Previous Year and Next Year buttons. To add a
date from the Yearly format, click a month to open it in Monthly format,
where you can add run dates to specific days.
• Quarterly
Quarterly displays the calendar’s run dates for the current calendar quarter.
You can change the displayed quarter using the Previous Quarter and Next
Quarter buttons. To add a date from the Quarterly format, click a month to
open it in Monthly format, where you can add run dates to specific days.
218
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• Monthly
Monthly displays the calendar’s run dates for the current month. You can
change the displayed month using the Previous Month and Next Month
buttons.
• Generic Monthly, by Day of Week
Generic Monthly, by Day of Week allows you to add general recurring
dates based on the day of the week. The dates are applied to the months
specified between the Start and End Dates. Week 1 starts on the Sunday of
the week of the Start Date you specify. Note that this format does not
display the currently selected dates from the calendar; it only allows you to
add new dates and update the schedule.
• Generic Monthly, by Day of Month
Generic Monthly, by Day of Month allows you to add general recurring
dates based on the day of the month. The dates are applied to the months
specified between the Start and End Dates. This format allows you to add
new dates and update the schedule; it does not display currently selected
dates from the calendar.
5 Click the days of the month that you want to include as run days for the
calendar.
To remove a run day, click the day again.
Tip: For the Monthly and Generic Monthly, by Day of Week formats, you can
select multiple dates at once by clicking the row or column headings.
6 To add the new dates to the calendar, click Update.
If you added dates using a generic format, the Yearly format will automatically
appear, displaying the new dates.
Note: When you change an existing calendar, Crystal Enterprise checks all
currently scheduled instances in your system. Objects that use the edited
calendar are automatically updated to run on the revised date schedule.
Deleting calendars
When you delete a calendar, objects can no longer use it for scheduling jobs. If
existing scheduled jobs use the deleted calendar, they will fail if you do not select
a new calendar or create another schedule for them.
To delete a calendar
1 Go to the Calendars management area of the CMC.
2 Select the check box associated with the calendar you want to delete.
Tip: Select multiple check boxes to delete several calendars.
3 Click Delete, and click OK to confirm.
Crystal Enterprise Administrator’s Guide
219
Scheduling objects
Specifying calendar rights
You can grant or deny users and groups access to calendars. Depending how you
organize your calendars, you may have specific sets of dates that you want to be
available only for certain employees or departments. For example, your finance
team may use a series of financial tracking dates that aren’t useful for other
departments. Users will only be able to see the calendars they have the rights to see,
so you can use rights to hide calendars that aren’t applicable to a particular group.
Follow this procedure to change the rights for a calendar. By default, calendars are
based on current security settings, inheriting rights from the users’ parent folders.
To grant access to a calendar
1 Go to the Calendars management area of the CMC.
2 Select the calendar you want to grant access to.
3 Click the Rights tab.
4 Click Add/Remove to add users or groups that you want to give access to the
selected calendar.
The Add/Remove page appears.
5 In the Select Operation list, select Add/Remove Groups, Add Users, or
Remove Users.
6 Select the user or group you want to grant access to the specified calendar.
If you have many users on your system, select the Add Users operation; then
use the “Look for” field to search for a particular account.
7 Click OK.
8 On the Rights tab, change the Access Level for each user or group, as required.
9 To choose specific rights, choose Advanced.
For complete details on the predefined access levels and advanced rights, see
“Rights and Access Levels” on page 413.
10 Click Update.
Scheduling objects
When you schedule an object, Crystal Enterprise generates an instance that
contains information from the time the object is run. Report instances contain
relevant database information; program instances contain the standard out and
standard error produced by that instance of the program. Your instance uses all of
the settings that you have set in the CMC for the original object. The following
sections provide information on scheduling objects in various ways, such as
scheduling objects on demand, daily or monthly, in batches, or with events.
220
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Note:
• In order for a program object to be successfully scheduled and run, you must
provide logon information for the account that the program object will run as.
For details, see “Authentication and program objects” on page 206.
• Your end users, when using Crystal Enterprise to schedule and run objects,
should use a web-based client such as the Crystal Enterprise web desktop or a
custom web application. The Crystal Enterprise web desktop is designed
primarily for scheduling instances and viewing reports (whereas the CMC
enables you to manage and administer object properties and settings in
addition to scheduling and viewing reports).
• For many of the scheduling options, you can choose to schedule an instance to
with events. For information on events, see “Scheduling an object with events”
on page 234.
Scheduling on demand
When you select the schedule “On Demand” option, an object runs only when
users specifically run the object through their web application (the Crystal
Enterprise web desktop or a custom web application). For more information on the
Crystal Enterprise web desktop, see the Crystal Enterprise User’s Guide.
To set an object to be scheduled on demand
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the On Demand option.
Crystal Enterprise Administrator’s Guide
221
Scheduling objects
4 Complete the following fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to
process an object if the first attempt is not successful. By default, the
number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
5 Click Update.
Scheduling an object to run once
This option enables you to schedule an object to run once, whether it is run
immediately, or at a specific time. You can also schedule an object with events. For
detailed information on applying events, see “Scheduling an object with events”
on page 234.
To schedule an object to run once
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the Once option.
The page refreshes.
4 In the Run list, select from the following:
• Now
If you select this option, the object will be run immediately.
222
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• Now, with events
Choose this option to use the event or events that you have already defined.
• At a specific time
Select a start date in the Start Date area and an optional end date in the End
Date area. To select a date, you can either enter a date in the date field, or
click the Popup Calendar button to select a date from the calendar that
appears in a separate window.
• At a specific time, with events
Choose this option to use the event or events that you have already
defined. Select a start date in the Start Date area and an optional end date in
the End Date area. To select a date, you can either enter a date in the date
field, or click the Popup Calendar button to select a date from the calendar
that appears in a separate window.
5 Regardless of which option you select from the Run list, complete the
following fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to
process an object if the first attempt is not successful. By default, the
number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
6 Click Schedule to schedule the object.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved after this instance.
Scheduling a daily object
When you schedule an object to run daily, you can choose to have the object run
every day at a specified time, every set number of hours and minutes, or every
specified number of days. A separate instance is created each time an object is run.
You can also schedule an object with events. For more information on events, see
“Scheduling an object with events” on page 234.
To schedule a daily object
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the Daily option.
Crystal Enterprise Administrator’s Guide
223
Scheduling objects
The page refreshes.
4 In the Run list, select from the following:
• Once each day
The object will be run once a day, and will begin on the day and time that
you specify in the Start Date area. You can also select an optional end date
for the object in the End Date area. To select a date, you can either enter a
date in the date field, or click the Popup Calendar button to select a date
from the calendar that appears in a separate window.
• Daily, with events
Choose this option to use the event or events that you have already
defined. The object will be run once a day, and will begin on the day and
time that you specify in the Start Date area. You can also select an optional
end date for the object in the End Date area. To select a date, you can either
enter a date in the date field, or click the Popup Calendar button to select a
date from the calendar that appears in a separate window.
• Every X hour(s), N minute(s)
For this option, the object will be run every X hour(s) and N minute(s), and
will start on the day and time that you enter in the Start Date area. You can
also select an optional end date for the object in the End Date area. To select
a date, you can either enter a date in the date field, or click the Popup
Calendar button to select a date from the calendar that appears in a
separate window. To specify the hour and minute values, enter numeric
values in the “Where X is” field and the “Where N is” field. By default, X
equals 1 and N equals 0.
224
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• Every X hour(s), N minute(s), with events
Choose this option to use the event or events that you have already
defined. For this option, the object will be run every X hour(s) and N
minute(s), and will start on the day and time that you enter in the Start Date
area. You can also select an optional end date for the object in the End Date
area. To select a date, you can either enter a date in the date field, or click
the Popup Calendar button to select a date from the calendar that appears
in a separate window. To specify the hour and minute values, enter
numeric values in the “Where X is” field and the “Where N is” field. By
default, X equals 1 and N equals 0.
• Every X day(s)
For this option, the object will be run every X day(s) and will start from the
start date and time that you enter in the Start Date area. You can also select
an optional end date for the object in the End Date area. To select a date,
you can either enter a date in the date field, or click the Popup Calendar
button to select a date from the calendar that appears in a separate window.
To specify the day value, enter a numeric value in the “Where X is” field.
By default, X has a value of 1.
• Every X day(s), with events
Choose this option to use the event or events that you have already
defined. For this option, the object will be run every X day(s) and will start
from the start date and time that you enter in the Start Date area. You can
also select an optional end date for the object in the End Date area. To select
a date, you can either enter a date in the date field, or click the Popup
Calendar button to select a date from the calendar that appears in a
separate window. To specify the day value, enter a numeric value in the
“Where X is” field. By default, X has a value of 1.
5 Regardless of which option you select from the Run list, complete the following
fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to
process an object if the first attempt is not successful. By default, the
number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
6 Click Schedule to schedule the object.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved after this instance.
Crystal Enterprise Administrator’s Guide
225
Scheduling objects
Scheduling a weekly object
When you schedule an object to run weekly, you choose the day of the week and
the time when you want it to run. You can also schedule an object with events. For
more information on events, see “Scheduling an object with events” on page 234.
To schedule a weekly object
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the Weekly option.
The page refreshes.
4 In the Run list, select from the following:
• Every week on
When you select this option, the object will be run once a week, on the day
that you select from the days of the week check boxes. You also specify a
start date in the Start Date area and an optional end date for the object in
the End Date area. To select a date, you can either enter a date in the date
field, or click the Popup Calendar button to select a date from the calendar
that appears in a separate window.
226
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• Weekly, with events
Choose this option to use the event or events that you have already
defined. When you select this option, the object will be run once a week
(along with events), on the day that you select from the days of the week
check boxes. You also specify a start date in the Start Date area and an
optional end date for the object in the End Date area. To select a date, you
can either enter a date in the date field, or click the Popup Calendar button
to select a date from the calendar that appears in a separate window.
5 Regardless of which option you select from the Run list, complete the following
fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to
process an object if the first attempt is not successful. By default, the
number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
6 Click Schedule to schedule the object.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved after this instance.
Scheduling a monthly object
You can schedule an object so that it runs on a monthly basis, on a certain day of
the month or specified day of the week, on every set number of months, on the first
Monday of the month, or on the last day of the month. You can also schedule an
object with events. For detailed information on applying events, see “Scheduling
an object with events” on page 234.
To schedule a monthly object
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the Monthly option.
Crystal Enterprise Administrator’s Guide
227
Scheduling objects
The page refreshes.
4 In the Run list, select from the following:
• On the Nth day of the month
When you select this option, the object will be run once a month, on the day
that you select from the “Where N is” list (by default, N equals 15, so
objects will be run on the 15th of every month). If you use 31 as your value
for N, then the object will run only on months that have 31 days, and skip
the months that don’t have 31 days. Similarly, if you choose either 29, 30, or
31 for N, the object will skip February (on non-leap years). If you want to
run an object on the last day of every month, select “On the last day of the
month” in the Run list.
You specify a start date in the Start Date area and an optional end date for
the object in the End Date area. To select a date, you can either enter a date
in the date field, or click the Popup Calendar button to select a date from
the calendar that appears in a separate window.
• On the Nth day of the month, with events
Choose this option to use the event or events that you have already
defined. When you select this option, the object will be run once a month,
on the day that you select from the “Where N is” list (by default, N equals
15, so objects will be run on the 15th of every month). If you use 31 as your
value for N, then the object will run only on months that have 31 days, and
skip the months that don’t have 31 days. Similarly, if you choose either 29,
30, or 31 for N, the object will skip February (on non-leap years). If you
228
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
•
•
•
•
want to run an object on the last day of every month, select “On the last day
of the month, with events” in the Run list.
You specify a start date in the Start Date area and an optional end date for
the object in the End Date area. To select a date, you can either enter a date
in the date field, or click the Popup Calendar button to select a date from
the calendar that appears in a separate window.
On the Nth X of the month
When you select this option, the object will be run once a month. You select
the day of the week and which week the object will be run. Select a day of
the week from the “Where X” list and the particular week of the month
from the “Where N” list. By default, objects will be run on Monday (X) of
the first (N) week of the month. You also specify a start date in the Start
Date area and an optional end date for the object in the End Date area. To
select a date, you can either enter a date in the date field, or click the Popup
Calendar button to select a date from the calendar that appears in a
separate window.
On the Nth X of the month, with events
Choose this option to use the event or events that you have already
defined. When you select this option, the object will be run once a month.
You select the day of the week and which week the object will be run. Select
a day of the week from the “Where X” list and the particular week of the
month from the “Where N” list. By default, objects will be run on Monday
(X) of the first (N) week of the month. You also specify a start date in the
Start Date area and an optional end date for the object in the End Date area.
To select a date, you can either enter a date in the date field, or click the
Popup Calendar button to select a date from the calendar that appears in a
separate window.
Every N months
For this option, an object will be run every set number of months. By
default, the “Where N is” field has a value of one, so an object will be run
every month. You specify a start date in the Start Date area and an optional
end date for the object in the End Date area. To select a date, you can either
enter a date in the date field, or click the Popup Calendar button to select a
date from the calendar that appears in a separate window.
Every N months, with events
Choose this option to use the event or events that you have already
defined. For this option, an object will be run every set number of months.
By default, the “Where N is” field has a value of one, so an object will be
run every month. You specify a start date in the Start Date area and an
optional end date for the object in the End Date area. To select a date, you
can either enter a date in the date field, or click the Popup Calendar button
to select a date from the calendar that appears in a separate window.
Crystal Enterprise Administrator’s Guide
229
Scheduling objects
• On the first Monday of the month
When you select this option, an object will be run on the first Monday of
every month. You specify a start date in the Start Date area and an optional
end date for the object in the End Date area. To select a date, you can either
enter a date in the date field, or click the Popup Calendar button to select a
date from the calendar that appears in a separate window.
• On the first Monday of the month, with events
Choose this option to use the event or events that you have already
defined. When you select this option, an object will be run on the first
Monday of every month. You specify a start date in the Start Date area and
an optional end date for the object in the End Date area. To select a date,
you can either enter a date in the date field, or click the Popup Calendar
button to select a date from the calendar that appears in a separate window.
• On the last day of the month
When you select this option, an object will be run on the last day of every
month. You specify a start date in the Start Date area and an optional end
date for the object in the End Date area. To select a date, you can either
enter a date in the date field, or click the Popup Calendar button to select a
date from the calendar that appears in a separate window.
• On the last day of the month, with events
Choose this option to use the event or events that you have already
defined. When you select this option, an object will be run on the last day of
every month. You specify a start date in the Start Date area and an optional
end date for the object in the End Date area. To select a date, you can either
enter a date in the date field, or click the Popup Calendar button to select a
date from the calendar that appears in a separate window.
5 Regardless of which option you select from the Run list, complete the following
fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to
process an object if the first attempt is not successful. By default, the
number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
6 Click Schedule to schedule the object.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved after this instance.
230
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Scheduling an object with a calendar
When you cannot provide a detailed schedule using the standard settings for
recurring jobs, use a calendar to run the object on the specific dates you need.
When you schedule an object according to a calendar, it will run on each date
specified in the calendar, creating a new instance each time it runs. You can choose
the time of day the instance will run, and for how long, but the dates that the object
runs are controlled by the calendar you choose. For details on creating a calendar,
see “Creating calendars” on page 215.
You can also schedule objects with calendars and events. For more information on
events, see “Scheduling an object with events” on page 234.
To schedule an object with a calendar
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule tab appears.
3 Select the Calendar option.
The page refreshes.
4 In the Run list, select from the following:
• Calendar
When you select this option, the object runs on all specified run dates in the
calendar. To specify a start time and end time for the scheduled job on each
run date, choose values from the lists.
Crystal Enterprise Administrator’s Guide
231
Scheduling objects
• Calendar, with events
Choose this option to use an event or events that you have already defined.
When you select this option, the object and its associated events run on all
specified run dates in the calendar. Choose a start time and end time for the
scheduled job and its events to run on each run date.
For details on scheduling with calendars and events, see “Scheduling an
object with events” on page 234.
5 In the Calendar to run for list, choose the calendar that provides the scheduled
dates you want.
6 Complete the following fields:
• Number of retries allowed
This number indicates the number of times a job server will attempt to process
an object if the first attempt is not successful. By default, the number is zero.
• Retry interval in seconds
Crystal Enterprise will wait for the specified number of seconds to pass
before attempting to process an object again (if the first attempt failed). The
default setting is 1800 seconds.
7 Click Schedule to schedule the object.
8 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved after this instance.
Scheduling objects in batches
You can schedule objects in batches using the object packages feature. Object
packages function as distinct objects in Crystal Enterprise. They can be composed
of any combination of report and program objects published to the Crystal
Enterprise system. (Other types of objects, such as Excel, Word, Acrobat, Text, Rich
Text, PowerPoint, and Hyperlink objects, cannot be added to object packages.)
Using object packages to schedule batches of objects simplifies authentication. In
terms of reports, it allows users to view synchronized data across report instances.
This procedure describes how to use the CMC to schedule published objects in
batches. First you publish an object package. Then, you copy existing objects into the
object package. Finally, you schedule the object package as you would any object.
Alternatively, you can publish objects directly to an object package, and then you
can schedule that object packages as you would any object. For details on publishing
directly to an object package, see “Publishing overview” on page 116. For details on
configuring object packages, see “Object package management” on page 208.
Note:
• You must configure the processing information of each of the components of
an object package individually. For example, if you want a report object in an
232
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
object package to print when scheduled, you must configure it through the
Print Setup link available on the report object’s Process tab. For more
information about configuring objects, see “Managing Objects” on page 177.
• For information about publishing hyperlinked report objects, see “Working
with hyperlinked reports” on page 199.
To schedule objects in a batch
1 Create an object package in Crystal Enterprise.
Go to the Objects management area of the CMC. Click New Object, and then
click the Object Package tab. Type the package name and select a destination. For
details, see “Publishing with the Crystal Management Console” on page 125.
2 Go to the Objects management area of the CMC.
3 Select the check boxes associated with each object you want to place in the
object package.
4 Click Copy/Move/Shortcut.
The Copy/Move/Create Shortcut page appears.
5 Select Copy to.
Note: Existing objects cannot be moved into an object packages; they must be
copied to the object package.
6 Select the object package you created as the Destination for the objects; then
click OK.
Tip:
• Object packages are indicated by [square brackets].
• To expand a folder, select it and click Show Subfolders.
• To search for a specific folder or object package, use the Look For field.
7 Schedule the object package.
For details, see “Scheduling objects” on page 220.
Crystal Enterprise Administrator’s Guide
233
Scheduling objects
Scheduling an object with events
When you schedule an object with events, the object will be run only when the
additional condition (that is, the event) occurs. You can tell an object to wait for
any, or all of the three event types: file-based, custom-based, and schedule-based.
If you want a scheduled object to trigger an event, you must choose a schedulebased event.
Note: A file-based event is triggered upon the existence of a specified file. A
custom-based event is triggered manually. A schedule-based event is triggered by
another object being run.
When you schedule an object that waits for a specified event, the object will run
only when the event is triggered, and only when the rest of the schedule conditions
are met. If the event is triggered before the start date of the object, the object will
not run. If you have specified an end date for this object, and if the event is not
triggered before the end date occurs, the object will not run because not all of the
conditions will have been met. Also, if you choose a weekly, monthly, or calendar
schedule, the object will have a specified time frame in which it can be processed.
The event must be triggered within this specified time for the object to run. For
example, if you schedule a weekly report object that runs every Monday, the event
must be triggered within the 24-hour period on Monday; if the event is triggered
outside of the 24-hour period, then the report will not run.
You can also schedule an object which triggers a schedule-based event upon
completion of the object being run. When the object is run, Crystal Enterprise will
trigger the specified event. For a schedule-based event, if the event is based on the
instance being run successfully, for example, the event won’t be triggered if the
instance fails. For a sample scenario on when you would use a schedule-based
event, see “Schedule-based events” on page 264.
When you schedule an object through the Objects management area, you can
specify in the Run list in the Schedule page whether you want to schedule an object
with events or not. For detailed information on scheduling objects without events,
see “Scheduling objects” on page 220.
To schedule an object with events, first ensure that you have created an event in
the Events management area. When you schedule an object, select any Run option
which includes the phrase, “with events.” For more information on creating events
(and sample scenarios for each type of event), see “Managing events overview” on
page 262.
To select an event or events to wait for
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
The Schedule page appears.
234
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
3 From the list on the left of the page, select a recurrence pattern: Once, Daily,
Weekly, Monthly, or by Calendar.
4 In the Run list, select a run option that contains the words, “with events.”
5 Select and complete the schedule parameters for your object (scheduling
option, Start Date, End Date, and so on).
6 In the Available Events area, select from the list of events and click Add.
For example, the report object above is set to wait for a Custom-based event to
occur before the report is processed.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved.
8 Click the Schedule button to schedule the object.
To trigger a schedule-based event or events upon completion
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab.
3 From the list on the left of the page, select a recurrence pattern: Once, Daily,
Weekly, Monthly, or by Calendar.
Crystal Enterprise Administrator’s Guide
235
Managing instances
4 In the Run list, select a run option that contains the words, “with events.”
5 Select and complete the schedule parameters for your object (scheduling
option, Start Date, End Date, and so on).
6 In the Available Schedule Events area, select from the list of events and click
Add.
For example, the report object above is set to trigger a Schedule-based event
only if the report is successfully processed.
Note: You can only select schedule-based events in this list.
7 To update the default scheduling information, click Update.
If you don’t click Update, any changes you made to the scheduling information
are not saved.
8 Click the Schedule button to schedule the object.
Managing instances
After you publish an object, Crystal Enterprise allows you to control the instances.
You can select the output destination of the object. For reports, you can choose the
output format of the report, and you can specify printer and page layout options.
To manage storage space, it is good practice to limit the number of possible
instances for an object, or to provide a time limit for the instances. You can also
work with instances in an object’s History tab, where you can delete, pause, run,
and refresh instances.
236
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Selecting a destination
Using Crystal Enterprise, you can specify the output destination of a scheduled
object. By default, when you schedule an object, the instances will be saved on the
File Repository Server (FRS). The option to choose a destination provides you with
the flexibility to deliver objects across your enterprise solution in different and
applicable ways. For example, you are able to schedule objects that will be sent via
email to other users.
Note: You can also schedule objects that, upon generation, will be printed. For
more information, see “Setting printer and page layout options” on page 244.
When users schedule objects to specific destinations (other than the default FRS
location), Crystal Enterprise generates a unique name for each output file. To
generate a file name, users can use a combination of ID, name or title of the object,
owner information, or the date and time information.
The following destination support locations are available:
• “Default destination support” on page 237
• “Unmanaged Disk destination support” on page 238
• “FTP support” on page 239
• “Email (SMTP) support” on page 241
Note: You can change your destination settings either in the Crystal Management
Console (CMC) or in the Crystal Enterprise web desktop. When you specify the
destination settings through the CMC, these settings are also reflected in the
default scheduling settings for the web desktop; that is, if a user selects the
Default destination setting in the web desktop, the object will be delivered to the
specified destination (as set on the Schedule page in the CMC).
Default destination support
By default, scheduled objects are saved to the File Repository Server (FRS). If you
want to save instances to the FRS, select this option.
To set your destination to default
1 In the Objects management area of the CMC, select an object by clicking its
link.
2 Click the Schedule tab, then click the Destination link.
The Destination tab appears.
3 Select Default from the Destination list.
4 Click Update.
Crystal Enterprise Administrator’s Guide
237
Managing instances
Unmanaged Disk destination support
You can specify the location where an instance will be saved when it is scheduled
by you or another user.
Note:
• The location must be a local or mapped directory on the processing server. For
servers using Windows, the location can also be a Universal Naming
Convention (UNC) path.
• The processing server must have sufficient rights to the specified location.
• You must have this destination feature enabled in the Job Server in order to use
unmanaged disk destination support. For more information on the Job Server,
see “Setting default scheduling destinations for Job Servers” on page 309.
To set your destination to unmanaged disk
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab, then click the Destination link.
The Destination tab appears.
Select Unmanaged Disk from the Destination list.
238
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
3 Select either Use the Crystal Job Server’s defaults or Set the values to be used
at schedule time here.
If you select the first option, Crystal Enterprise will schedule an object using the
Job Server’s default settings. You can change these settings in the Servers
management area. For more information, see “Setting default scheduling
destinations for Job Servers” on page 309.
If you select the second option, you can set the file name properties and enter
user information:
• Destination Directory
Enter a local location, mapped location, or a UNC path.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file
name.
• Specified File Name
Select this option if you want to specify a file name—you can also add a
variable to the file name. To add a variable, choose a placeholder for a
variable property from the list and click Add. When the instance is run, the
variable will be replaced with the specified information from the instance.
For example, if you add the variable “Owner,” when you schedule an
object, its file name will include the object owner’s name.
• User Name
Specify a user who has permission to write files to the destination directory.
• Password
Type the password for the user.
Note: You can specify a user name and password only for servers using
Windows.
4 Click Update.
FTP support
Crystal Enterprise enables you and your users to schedule an object to a File
Transfer Protocol (FTP) server. To connect to the FTP server, you must specify a
user who has the necessary rights to upload files to the server.
Note: You must have this destination feature enabled in the Job Server in order to
schedule an object to an FTP server.
To set an FTP server as the destination
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab, then click the Destination link.
The Destination tab appears.
Crystal Enterprise Administrator’s Guide
239
Managing instances
3 Select FTP from the Destination list.
4 Select either Use the Crystal Job Server’s defaults or Set the values to be used
at schedule time here.
If you select the first option, Crystal Enterprise will schedule an object using the
Job Server’s default settings. You can change these settings in the Servers
management area. For more information see “Setting default scheduling
destinations for Job Servers” on page 309.
If you select the second option, you can set the FTP and file name properties:
• Host
Enter the FTP host information.
• Port
Enter the FTP port number (the default is 21).
• FTP User Name
Specify a user who has the necessary rights to upload an object to the FTP
server.
240
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• FTP Password
Enter the user’s password.
• Account
Enter the FTP account information, if required.
Account is part of the standard FTP protocol, but it is rarely implemented.
Provide the appropriate account only if your FTP server requires it.
• Destination Directory
Enter the FTP directory that you want the object to be saved to.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file
name.
• Specified File Name
Select this option if you want to enter a file name—you can also add a
variable to the file name. To add a variable, choose a placeholder for a
variable property from the list and click Add.
5 Click Update.
Email (SMTP) support
With Simple Mail Transfer Protocol (SMTP) mail support, you and your users can
do the following:
• Send an object as an attachment in the email.
• Specify the “To,” “Cc,” and “From” in the email.
• Add subject information.
• Include additional information in the body message, which will accompany
the object that is being delivered.
Crystal Enterprise supports Multipurpose Internet Mail Extensions (MIME)
encoding.
Note: You must have this destination feature enabled and configured in the
Report Job Server in order to schedule an object to be sent via email. For details,
see “Setting default scheduling destinations for Job Servers” on page 309.
To send an object via email
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the Schedule tab, then click the Destination link.
The Destination tab appears.
Crystal Enterprise Administrator’s Guide
241
Managing instances
3 Select Email (SMTP) from the Destination list.
4 Select either Use the Crystal Job Server’s defaults or Set the values to be used
at schedule time here.
If you select the first option, Crystal Enterprise will schedule an object using the
Job Server’s default settings. You can change these settings in the Servers
management area. For more information, see “Setting default scheduling
destinations for Job Servers” on page 309.
If you select the second option, you can specify the email settings and the file
name properties:
• From
Enter a return address.
• To
Enter an address or addresses that you wish to send the object to. Separate
multiple addresses with semicolons.
242
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
• Cc
Enter an address or addresses that you wish to send a carbon copy of the
object to.
• Subject
Complete the subject field.
• Message
Type a short message, if required.
• Add viewer hyperlink to message body
Click Add if you want to add the URL for the viewer in which you want the
email recipient to view the object. You can set the default URL by clicking
Object Settings on the main page of the Objects management area of the CMC.
• Attach object instance to email message
Clear this check box if you do not want a copy of the instance attached to
the email.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file
name.
• Specified File Name
Select this option if you want to enter a file name—you can also add a
variable to the file name. To add a variable, choose a placeholder for a
variable property from the list and click Add.
5 Click Update.
Choosing a format
For report objects only, you can select the format that a report instance will be
saved in when it is generated by Crystal Enterprise. This format will be saved to
the destination you have selected for the report object and its instances. For more
information on destinations, see “Selecting a destination” on page 237. You can
select from the following formats:
• Crystal Report
• Excel
• Excel (Data Only)
• Word
• Acrobat
• Rich Text
• Plain Text
• Paginated Text
• Tab-separated Text
• Tab-separated Values
• Character-separated Values
Crystal Enterprise Administrator’s Guide
243
Managing instances
For Excel, Paginated Text, Tab-separated Values, and Character-separated Values,
you specify certain formatting properties for the report. For example, if you select
Character-separated Values, you can enter characters for the separator and
delimiter; you can also select the two check boxes: “Same number formats as in
report” and “Same date formats as in report.”
Note:
• If you choose to print the report when it is scheduled (by checking the “Print in
Crystal Reports format using the selected printer when scheduling” check box
on the Print Setup page), the report instance is automatically sent to the printer
in Crystal Reports format. This does not conflict with the format you select
when scheduling the report.
• The difference between Excel and Excel (Data only) is that Excel attempts to
preserve the look and feel of your original report, while Excel (Data only)
saves only the data, with each cell representing a field.
• The Tab-separated Values format places a tab character between values; the
Character-separated Values format places a specified character between
values. Each of these two formats produce data lists. In contrast, the Tabseparated Text format attempts to preserve the formatting of the report.
To select a format for the report
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 On the Schedule tab, click the Format link.
The Format page appears.
3 Select a format from the Format list.
4 Complete any fields that appear below the list and select (where appropriate)
the check boxes that appear.
5 Click Update.
Setting printer and page layout options
You can choose to print a report instance when scheduling it; report instances are
always printed in Crystal Reports format. When printing a report, you can set the
number of copies and the page range.
The Print Setup page contains two areas: the first area specifies whether or not a
report instance is printed, and if printed, the printer to use, the number of copies, and
the page range; the second area specifies custom layout settings for changing the
page size and orientation (regardless of whether the report instance is printed or not).
244
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Specifying a printer
You can choose to print a report (each time it runs) using the Report Job Server’s
default printer or a different printer. By selecting the Printer destination, Crystal
Enterprise prints your report after it is processed.
Note: The Report Job Server must run under an account that has sufficient
privileges to access the printer you specify. See “Changing the server user
account” on page 326 for information on changing the user account.
To assign a printer
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 On the Process tab, click the Print Setup link.
The Print Setup page appears.
3 Select Print in Crystal Reports format using the selected printer when
scheduling if you want report instances to be sent directly to a printer.
The report instances are automatically sent to the printer in Crystal Reports format.
This does not interfere with the format selected when scheduling the report.
4 Leave Default printer selected if you want to print to the Job Server’s default
printer, otherwise, select Specify a printer.
5 Enter a printer’s path and name, select the number of copies, and choose the
print page range.
If your Job Server is using Windows, in the “Specify a printer” field, type:
\\printserver\printername
Where printserver is the name of your printer server, and printername is the
name of your printer.
If your Job Server is running on UNIX, in the “Specify a printer” field, type the
print command that you normally use. For instance, type:
lp -d printername
Note: Ensure that the printer you are using (on UNIX) is “shown” and not
“hidden.”
6 Click Update.
Specifying page layout
When viewing or scheduling a report instance to any format, you can first specify
page layout criteria such as page orientation, page size, and so on. The settings you
choose in this section of the Print Setup page affect how you’ll see a report instance
when displaying it.
Note: Page layout settings are not specifically related only to scheduling a report
to a printer, but also to the overall look of the report. The overall look is affected
Crystal Enterprise Administrator’s Guide
245
Managing instances
by the properties of the device for which the report is displayed in (that is, the
font metrics and other layout settings of the display and/or the printer).
To set a report’s page layout
1 In the Objects management area of the CMC, select a report object by clicking
its link.
2 On the Process tab, click the Print Setup link.
The Print Setup page appears.
3 Make your settings according to the type of layout you want. The options are
as follows:
• Report file default
Choose this option if you want the page layout to conform to the settings
that were chosen for the report in Crystal Reports.
• Specified printer settings
Choose this option if you want the page layout to conform to the settings of
a specified printer. You can choose the Job Server’s default printer or
another printer. For information about specifying another printer, see
“Specifying a printer” on page 245.
When you choose this option, you can print scheduled report instances
only to the printer you specify in the “Specified printer settings” area. In
other words, you cannot set your report to display with one printer’s
setting and then print to a different printer.
• Custom settings
Choose this option if you want to customize all page layout settings. You
can choose page orientation, page size, measurement units (inches or
millimeters), page width, and page height.
4 Click Update.
Setting instance limits for an object
In the Limits page, you can set the limits for the selected object and its instances.
You set limits to automate regular clean-ups of old Crystal Enterprise content. At
the object level, you can limit the number of instances that remain on the system
for the object or for each user or group; you can also limit the number of days that
an instance remains on the system for a user or group.
246
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
In addition to setting the limits for the objects from the Objects management area,
you can also set limits at the folder level. When you set limits at the folder level,
these limits will be in effect for all objects that reside within the folder (including
any objects found within the subfolders). For information on setting folder limits,
see “Setting limits for folders, users, and groups” on page 112.
Note: When you set the limits at the object level, the object limits will override the
limits set for the folder; that is, the object will not inherit the limits of the folder.
To set limits for instances
1 In the Objects management area of the CMC, select an object by clicking its link.
2 On the History tab, click the Limits link.
The Limits page appears.
3 Make your settings according to the types of limits you want to set for your
instances. The options are as follows:
• Delete excess instances when there are more than N instances of an
object
To limit the number of instances per object, select this check box. Then type
the maximum number of instances that you want to remain on the system.
(The default value is 100.)
• Delete excess instances for the following users/groups
To limit the number of instances for users or groups, click Add/Remove in
this area. Select from the available users and groups and click OK. Then
type the maximum number of instances in the Instance Limit column. (The
default value is 100.)
• Delete instances after N days for the following users/groups
To limit the number of days that instances are saved for users or groups,
click Add/Remove in this area. Select from the available users and groups
and click OK. Then type the maximum age of instances in the Maximum
Days column. (The default value is 100.)
4 Click Update.
Crystal Enterprise Administrator’s Guide
247
Managing instances
Managing and viewing the history of instances
The History page displays all of the instances for a selected object. The Instance
Time column displays the title of the instances and the date of the last update for
each instance. The Status column displays the status of each instance. The Run By
column indicates which user scheduled the instance.
For report objects, the Format column displays which format the report is, or will
be stored in and the Parameters column indicates what parameters were or will be
used for each instance. For program objects, the Arguments column lists the
command-line options that were or will be passed to the command line interface
for each instance.
Crystal Enterprise creates instances from objects. That is, a report instance is
created when a report object is scheduled and run by the Report Job Server.
Essentially, a report instance is a report object that contains report data that is
retrieved from one or more databases. Each instance contains data that is current
at the time the report is processed. You can view specific report instances on the
History page of the report object.
Crystal Enterprise creates a program instance each time that a program object is
scheduled and run by the Program Job Server. Unlike report instances, which can
be viewed in their completed format, program instances exist as records in the
object history. Crystal Enterprise stores the program’s standard out and standard
error in a text output file. This file appears when you click a program instance in
the object History.
To manage instances
1 In the Objects management area of the CMC, select an object by clicking its link.
2 Click the History tab.
The History tab appears.
3 Select an instance or instances by selecting the appropriate check boxes.
4 Click either Run Now, Pause, Resume, Delete, Select All, Clear All, or
Refresh.
Note: If you click Run Now, a new instance will be generated (which uses the
current settings of the object).
248
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
To view an instance
1 Select a object in the Objects management area of the CMC.
2 Click the History tab.
The History page appears.
3 In the Instance Time column, click the instance you want to view.
Tip: You can also use the Instance Manager tool to view a list of instances by status
or by user. Access the Instance Manager by clicking its link in the Administrative
Tools area of the Crystal Enterprise Admin Launchpad.
Setting notification for an object’s success or failure
You can set scheduling options that automatically send notification when an object
instance succeeds or fails. You can send notification using audit or email
notification. You can also combine multiple notification methods, and provide
different notification settings for successful and failed instances.
For example, you may have a large number of reports that run a new instance
every day. You need to check each instance to make sure it ran properly, and then
send out emails to the users who need to know that the new report is available.
With thousands of reports, it would take too much time to manually check the
reports and contact the users who need the information. Using notification settings
in Crystal Enterprise, you can set each object to automatically notify you when the
report fails to run properly, and you can automatically inform users when new
report instances run successfully.
Determining an object’s success or failure
When you schedule an object, the scheduled instance either succeeds or fails. The
conditions required for an instance’s success or failure depend on the type of object
you schedule:
• Report objects
A report instance runs successfully if it doesn’t encounter any errors while
processing the report or accessing the database. A report instance may fail if the
user does not provide the correct parameters or logon information.
• Program objects
For program objects, the program must run in order to succeed. If the program
does not run, the instance is considered a failure. If the program runs, but does
not perform the tasks it is supposed to, it is still considered a successful instance
because the program object ran. Crystal Enterprise does not monitor problems
with the program object’s code.
• Object packages
An object package may fail if one of its components fails. To change this setting,
click the object package’s Properties tab and clear the “Scheduled package fails
upon individual component failure” option.
Crystal Enterprise Administrator’s Guide
249
Managing instances
You can also set scheduling options for individual objects within an object package.
Note: You cannot set audit or email notification for object packages, but you
can set any type of notification for the individual objects in the object package.
You can also schedule object packages with events on the Schedule tab. For
more information about events, see “Schedule-based events” on page 264.
About notification
You can set notification at the object level, and you can apply it to all objects that
can be scheduled in Crystal Enterprise. You can select unique notification options
for each object, sending different types of notification for different conditions. For
object packages, you can set only event notification, which will trigger an event
based on success or failure of the object package. To monitor object successes and
failures from a more general perspective, use the auditing functionality within
Crystal Enterprise.
If notification fails, then the object instance fails. For example, if an email
notification sends a message to an invalid email address, then the notification fails
and the object instance is recorded as a failure in the object’s history.
You can choose to notify using:
• Audit notification
To use audit notification, you must configure the auditing database and enable
auditing for the servers. If you use auditing to monitor your Crystal Enterprise
system, you can use audit notification. For more information about configuring
the auditing database and enabling auditing, see “Managing Auditing” on
page 329.
When you select audit notification, information about the scheduled object is
written to the auditing database. You can choose to have a notification sent to the
auditing database when the job runs successfully, when it fails to run, or both.
Note: For the Crystal Report Server and the Crystal Program Server, you can
also set audit notification on the Auditing tab.
• Email notification
You can send an email as a notification of an object instance’s success or failure.
You can choose the sender and recipients of the email message. You can send
an email when the instance fails and when it succeeds. For example, you could
send your administrator an email if the report fails, but when the report
succeeds you can automatically send a notification to everyone who needs the
report to let them know it is now available.
Note: For information on changing the Crystal Job Server’s default email, see
“Setting the default email (SMTP) destination” on page 312.
• Event notification
You can choose a Crystal Enterprise event that will be triggered based on the
completion of the object instance. For more information about events, see
“Schedule-based events” on page 264.
250
Crystal Enterprise Administrator’s Guide
12: Scheduling Objects
Note: Notification of a scheduled object’s success or failure is not the same as alert
notification. Alert notification must be built into the design of the report. For
example, alert notification can send an email to you whenever a specific value in
the report exceeds $1000000. In this case, the notification has nothing to do with
the contents of the report - it’s just about whether or not the report object instance
has failed or succeeded.
To set notification for an instance’s success or failure
1 Select a object in the Objects management area of the CMC.
2 Click the Schedule tab, then click the Notification link.
3 Click the notification type (or types) you want to use.
Note: If the notification type is already being used, it will be labelled
“Enabled”. If not, it will be labelled “Not in use”.
4 Choose the specific settings for the notification.
Audit notification
To send a record to the auditing database when the job succeeds, select “A job
has been run successfully.”
To send a record when the job fails, select “A job has failed to run.”
Email notification
Choose whether you want to send a notification when the job fails or when it
succeeds.
To specify the contents and recipients of the email notification, select “Set the
vales to be used here” and provide the From and To email addresses, the email
subject line, and the message.
Note: By default, the notification is sent to the server’s default email
destination. For details on how to change the default email settings, see
“Setting the default email (SMTP) destination” on page 312.
5 Click Update.
Crystal Enterprise Administrator’s Guide
251
Managing instances
252
Crystal Enterprise Administrator’s Guide
Managing Crystal Repository
13
This chapter discusses installing and managing Crystal
Repository in Crystal Enterprise. It explains how to migrate
data from previous versions of Crystal Repository, and
discusses how to refresh repository objects in reports.
Crystal Enterprise Administrator’s Guide
253
Crystal Repository overview
Crystal Repository overview
The Crystal Repository is a database in which you manage shared report elements
such as text objects, bitmaps, custom functions, and custom SQL commands. When
you save any Business View, it is also saved to the Crystal Repository.You can
refresh a report’s repository objects with the latest version from your Crystal
Repository when you publish reports to Crystal Enterprise. Alternatively, you can
refresh a report’s repository objects on demand over the Web.
The Crystal Repository is now hosted by the Crystal Management Server (CMS)
system database. Before publishing reports that reference repository objects, move
your existing Crystal Repository to the Crystal Management Server (CMS)
database. See the rest of this chapter for details.
Copying data from one repository database to another
Crystal Enterprise enables you to copy the contents of one Crystal Repository
database into another database. This procedure is also referred to as migrating a
Crystal Repository database. You can migrate repository data from a different
repository database (from version 9 of Crystal Reports, or version 9 of Crystal
Enterprise) into your current CMS database. Or, you can migrate the repository
data from your current CMS database into a different data source.
Throughout this section, the source CMS database refers to the database that holds
the data you are copying; this data is copied into the destination database.
Copying data from a Crystal Enterprise 10 CMS
You may want to copy repository objects from one Crystal Enterprise 10
installation to another. For example, you may have repository data on a test system
that you want to move onto a production server.
Use the Crystal Import Wizard to copy repository data from the source CMS. You
can choose to merge the contents of the source repository into the destination
repository, or you can update the destination with the contents of the source CMS.
Merging repositories
When you merge the contents of the source repository with the destination
repository, you add all repository objects from the source CMS into the destination
CMS without overwriting objects in the destination.
This is the safest import option. All of the objects in the destination repository are
preserved. Also, at a minimum, all repository objects from the source system with
a unique title are copied to the destination repository.
If an object from the source has the same title as an object in the destination, the
object is imported to the destination repository if:
• The object is not a Business View.
254
Crystal Enterprise Administrator’s Guide
13: Managing Crystal Repository
• You have selected “Automatically rename top-level folders that match toplevel folders on the destination system.”
The end result is a destination repository that contains all objects from the source
repository that have unique titles, copies of all non-Business View objects from the
source repository that have titles that match titles of objects in the destination, and
all objects originally in the destination repository.
When an object is copied from the source CMS to the destination CMS, the folder or
folders that contain the object are also copied, replicating the folder hierarchy of the
source system on the destination. However, the names of top-level folders must be
unique. Selecting “Automatically rename top-level folders that match top-level folders
on the destination system” allows these folders to be renamed on the destination
repository, and the objects in such folders to be copied to these renamed folders.
Note: Top-level folders containing Business Views are not renamed, regardless of
the options set. Renaming these folders would change the unique identifier
associated with the Business View, causing the Business View functionality to fail.
Updating the destination repository
When you update the contents of the destination repository using the source
repository as a reference, you add all objects in the source CMS to the destination
CMS. If an object in the source repository has the same unique identifier as an object
in the destination, the object in the destination is overwritten.
All object titles in a folder must be unique. By default, if copying an object from the
source CMS to the destination CMS would result in more than one object in a
folder with the same title, the copy fails.
If you want these objects to be copied, select the check box “Automatically rename
objects if an object with that title already exists in the destination folder.”
Note: System Objects (users, user groups, servers, server groups, events, and
calendars), are not renamed when you import them from one CMS to another,
regardless of the options set. Changing the names of these objects would cause user
management, server management, and event management for these objects to fail.
See “Importing with the Crystal Import Wizard” on page 135 for full instructions
on using the Import Wizard to copy objects from one Crystal Enterprise 10
repository to another.
Copying data from a Crystal Enterprise 9 repository database
In Crystal Enterprise 9, the Crystal Repository database was hosted on a separate
database server that you could connect to through ODBC.
In a Crystal Enterprise environment, begin by making a backup copy of the source
repository database. Then replace the repository by importing its contents into the
CMS database using the Crystal Repository Migration Wizard.
Crystal Enterprise Administrator’s Guide
255
Copying data from one repository database to another
When you use the Crystal Repository Migration Wizard, neither the source nor the
destination database is overwritten. Objects from the source repository will be
added to the destination repository database. If the Wizard finds identical objects
(that is, objects with the same unique identifier) in the source and destination
repositories, the source objects will not be copied.
When you copy repository objects into Crystal Enterprise 10, only the most recent
version of each object is copied.
Note: Reports configured to use the source repository will now refer to the
destination data source.
To copy repository data from Crystal Enterprise 9
1 From the Crystal Enterprise program group, click Crystal Repository
Migration Wizard. You must run the wizard on the machine containing your
source repository.
2 From the Source list in the Select Source Repository dialog, click the name of
the repository that you want to import.
3 Type the UserID and Password of a user with administrative rights to the
repository database. Click Next.
4 The Select Destination Data Source dialog appears. In the CMS field, type the
name of the destination data source’s Crystal Management Server.
5 Type the User Name and Password of an Enterprise account that provides you
with administrative rights to the CMS; then click Next.
256
Crystal Enterprise Administrator’s Guide
13: Managing Crystal Repository
6 From the “Source Repository Objects” list, select the items that you want to
copy to your Crystal Enterprise repository database. Click Next.
Crystal Enterprise exports the selected repository objects from your Crystal
Repository, reporting success or failure for each object.
7 Click Next, and then Finish to complete the transfer and close the Crystal
Repository Migration Wizard.
Copying data from a Crystal Reports 9 repository database
The Crystal Repository shipped with Crystal Reports 9 was an Access database
(Repository.mdb). By default, it was located in the following directory of your
Crystal Reports installation:
C:\Program Files\Common Files\Crystal Decisions\2.0\bin\
Begin by making a backup copy of this default database. Then replace the default
repository by importing its contents into the CMS database using the Crystal
Repository Migration Wizard.
When you use the Crystal Repository Migration Wizard, neither the source nor the
destination database is overwritten. Objects from the source repository will be
added to the destination repository database. If the Wizard finds identical objects
in the source and destination repositories, the source objects will not be copied.
When you copy repository objects into Crystal Enterprise 10, only the most recent
version of each object is copied.
Note: Reports configured to use the source repository will now refer to the
destination data source.
To copy repository data from Crystal Reports 9
1 From the Crystal Enterprise program group, click Crystal Repository
Migration Wizard. You must run the wizard on the machine containing your
source repository.
2 From the Source list in the Select Source Repository dialog, click the name of
the repository that you want to import.
If you created security for your repository database, type a User id and
Password valid for the repository database.
3 Click Next.
4 Log on to the CMS using a user name with administrative rights to Crystal
Enterprise.
Crystal Enterprise Administrator’s Guide
257
Refreshing repository objects in published reports
5 From the “Source Repository Objects” list, select the items that you want to
copy to your Crystal Enterprise repository database. Click Next.
6 Select the folder in your destination repository where objects from your source
directory will be placed.
• To add objects to a new folder, select “Insert a new folder”, and then type
the name of the folder.
• To delete an existing folder from your repository, select it, and then click
“Delete the item/folder”.
7 Click Next.
Crystal Enterprise exports the selected repository objects from your Crystal
Reports repository, reporting success or failure for each object.
8 Click Next, and then Finish to complete the transfer and close the Crystal
Repository Migration Wizard.
Refreshing repository objects in published reports
As you update objects stored in your Crystal Repository, you will want to update
the published Crystal reports that reference those repository objects. When you
refresh a report in this way, the old repository objects stored in the report are
replaced with the latest versions from the Crystal Repository.
Note: Although refreshing with the repository is faster, you can also refresh
reports by setting options that compare reports to their original source .rpt files.
For more information, see “Setting report refresh options” on page 185.
258
Crystal Enterprise Administrator’s Guide
13: Managing Crystal Repository
Tip: If you use Crystal Reports to open reports directly from your Crystal
Enterprise folders, you can update repository objects at that time. You can also
refresh repository objects when you publish reports. For details, see “Publishing
Objects to Crystal Enterprise” on page 115.
To refresh a published report’s repository objects
1 Go to the Objects management area of the CMC.
2 Click the link to the report you want to refresh.
3 On the Properties tab, click the Refresh Options link.
4 Verify that the Use Object Repository when refreshing report check box is
selected.
Note: If the check box is cleared, select it now and click Update.
5 Click Refresh Report.
Tip: Once you have enabled repository refresh for each report, you can refresh
multiple reports simultaneously using the Report Repository Helper. The Report
Repository Helper is available from Administrative Tools area in the Crystal
Enterprise Admin Launchpad.
Crystal Enterprise Administrator’s Guide
259
Refreshing repository objects in published reports
260
Crystal Enterprise Administrator’s Guide
Managing Events
14
This chapter provides information on creating and
managing events. It describes file-based events, custom
events, and schedule-based events.
Crystal Enterprise Administrator’s Guide
261
Managing events overview
Managing events overview
Event-based scheduling provides you with additional control over scheduling
objects: you can set up events so that objects are processed only after a specified
event occurs. Working with events consists of two steps: creating an event and
scheduling an object with events. That is, once you create an event, you can select
it as a dependency when you schedule an object. The scheduled job is then
processed only when the event occurs. This chapter shows how to create events in
the Events management area of the Crystal Management Console (CMC).
You can create three kinds of events:
• File events
When you define a file-based event, you specify a filename that the Event
Server should monitor for a particular file. When the file appears, the Event
Server triggers the event. For instance, you might want to make some reports
dependent upon the regular file output of other programs or scripts.
For details, see “File-based events” on page 263.
• Schedule events
When you define a schedule-based event, you select an object whose existing
recurrence schedule will serve as the trigger for your event. In this way,
schedule-based events allow you to set up contingencies or conditions between
scheduled objects. For instance, you might want certain large reports to run
sequentially, or you might want a particular sales summary report to run only
when a detailed sales report runs successfully.
For details, see “Schedule-based events” on page 264.
• Custom events
When you create a custom event, you create a shortcut for triggering an event
manually. Basically, your custom event occurs only when you or another
administrator clicks the corresponding “Trigger this event” button in the CMC.
For details, see “Custom events” on page 266.
When working with events, keep in mind that an object’s recurrence schedule still
determines how frequently the object runs. For instance, a daily report that is
dependent upon a file-based event will run, at most, once a day (so long as the file
that you specify appears every day). In addition, the event must occur within the
time frame established when you actually schedule the event-based report.
Note: For information on scheduling an event-based object in the Objects
management area of the CMC, see “Scheduling an object with events” on page 234.
262
Crystal Enterprise Administrator’s Guide
14: Managing Events
File-based events
File-based events wait for a particular file (the trigger) to appear before the event
occurs. Before scheduling an object that waits for a file-based event to occur, you must
first create the file-based event in the Events management area of the CMC. Then you
can schedule the object and select this event. For more information on scheduling an
object with events, see “Scheduling an object with events” on page 234.
File-based events are monitored by the Event Server. When the file that you specify
appears, the Event Server triggers the event. The Crystal Management Server
(CMS) then releases any schedule requests that are dependent on the event.
For instance, suppose that you want your daily reports to run after your database
analysis program has finished and written its automatic log file. To do this, you
specify the log file in your file-based event, and then schedule your daily reports
with this event as a dependency. When the log file appears, the event is triggered
and the reports are processed.
Note: If the file already exists prior to the creation of the event, the event is not
triggered. In this case, the event is triggered only when the file is removed and
then recreated. If you want an event to be triggered multiple times, you must
remove and recreate the file each time.
To create a file-based event
1 Go to the Events management area of the CMC.
2 Click New Event.
The New Event page appears.
3 In the Type list, select File.
Crystal Enterprise Administrator’s Guide
263
Schedule-based events
4 Type a name for the event in the Event Name field.
5 Complete the Description field.
6 In the Server list, select the Event Server that will monitor the specified file.
7 Type a filename in the Filename field.
Note: Type the absolute path to the file that the Event Server should look for
(for example, C:\folder\filename, or /home/folder/filename). The drive and
directory that you specify must be visible to the Event Server. Ideally, the
directory should be on a local drive.
8 Click OK.
Schedule-based events
Schedule-based events are dependent upon scheduled objects. That is, a schedulebased event is triggered when a particular object has been processed. When you
create this type of event, it can be based on the success or failure of a scheduled
object, or it can be based simply on the completion of the job.
Most importantly, you must associate your schedule-based event with at least two
scheduled objects. The first object serves as the trigger for the event: when the object
is processed, the event occurs. The second object is dependent upon the event:
when the event occurs, this second object runs. For more information on scheduling
objects with events, see “Scheduling an object with events” on page 234.
For instance, suppose that you want report objects R1 and R2 to run after program
object P1 runs. To do this, you create a schedule-based event in the Events
management area. You specify the “Success” option for the event, which means
that the event is triggered only when program P1 runs successfully. Then, you
schedule reports R1 and R2 with events, and select your new schedule-based event
as the dependency. Schedule program P1 with events, and set program P1 to
trigger the schedule-based event upon successful completion. Now, when
program P1 runs successfully, the schedule-based event is triggered, and reports
R1 and R2 are subsequently processed.
To create a schedule-based event
1 Go to the Events management area of the CMC.
2 Click New Event.
264
Crystal Enterprise Administrator’s Guide
14: Managing Events
The New Event page appears.
3 In the Type list, select Schedule.
4 Type a name for the event in the Event Name field.
5 Complete the Description field.
6 In the “Event based on” area, select from three options:
• Success
The event is triggered only upon successful completion of a specified object.
• Failure
The event is triggered only upon non-successful completion of a specified
object.
• Success or Failure
The event is triggered upon completion of a specified object, regardless of
whether that object was processed successfully or not.
7 Click OK.
Crystal Enterprise Administrator’s Guide
265
Custom events
Custom events
A custom event occurs only when you explicitly click its “Trigger this event” button.
As with all other events, an object based on a custom event runs only when the event
is triggered within the time frame established by the object’s schedule parameters.
Custom events are useful because they allow you to set up a shortcut that, when
clicked, triggers any dependent schedule requests.
Tip: When developing your own web applications, you can trigger Custom events
from within your own code, as required. For more information, see the developer
documentation available on your product CD.
For instance, you may have a scenario where you want to schedule a number of
reports, but you want to run them after you have updated information in your
database. To do this, create a new custom event, and schedule the reports with that
event. When you update the data in the database and you need to run the reports,
return to the event in the CMC and trigger it manually. Crystal Enterprise then
runs the reports. For more information on event-based scheduling, see
“Scheduling an object with events” on page 234.
Note: You can trigger a custom event multiple times. For example, you might
schedule two sets of event-based program objects to run daily—one set runs in
the morning, and one set runs in the afternoon. When you first trigger the related
custom event in the morning, one set of programs is run; when you trigger the
event again in the afternoon, the remaining set of programs is run. If you neglect
to trigger the event in the morning and trigger it only in the afternoon, both sets of
programs run at that time.
To create a custom event
1 Go to the Events management area of the CMC.
2 Click New Event.
3 In the Type list, select Custom.
4 Type a name for the event in the Event Name field.
5 Complete the Description field.
6 Click OK.
Note: Before you trigger this custom event, schedule an object that is dependent
upon this event.
To trigger a custom event
1 Go to the Events management area of the CMC.
2 In the Event Name column, select a custom event by clicking its link.
3 Click Trigger this event.
A message appears: “This event has been triggered.”
266
Crystal Enterprise Administrator’s Guide
14: Managing Events
Specifying event rights
You can grant or deny users and groups access to events. Depending how you
organize your events, you may have specific events that you want to be available
only for certain employees or departments. For example, you may want certain
events to be triggered only by management or IT.
Users will only be able to see events they have the rights to see, so you can use
rights to hide events that aren’t applicable to a particular group. For example, by
granting only the ITadmin group access to IT-related events, those events won’t
appear for a user from the HRadmin group; this makes the event list easier for the
HRadmin group to navigate.
Follow this procedure to change the rights for an event. By default, events are
based on current security settings, inheriting rights from the users’ parent folders.
To grant access to an event
1 Go to the Events management area of the CMC.
2 Select the event you want to grant access to.
3 Click the Rights tab.
4 Click Add/Remove to add users or groups that you want to give access to the
event.
The Add/Remove page appears.
5 In the Select Operation list, select Add/Remove Groups, Add Users, or
Remove Users.
6 Select the user or group you want to grant access to the specified event.
7 If you have many users on your system, select the Add Users operation; then
use the “Look for” field to search for a particular account.
8 Click OK.
9 On the Rights tab, change the Access Level for each user or group, as required.
10 To choose specific rights, choose Advanced.
Note: For complete details on the predefined access levels and advanced
rights, see “Rights and Access Levels” on page 413.
11 Click Update.
Crystal Enterprise Administrator’s Guide
267
Specifying event rights
268
Crystal Enterprise Administrator’s Guide
Managing and Configuring Servers
15
This chapter provides information on a range of server
tasks that allow you to customize the behavior of Crystal
Enterprise. The chapter first covers straightforward tasks
like starting and stopping servers, and then proceeds to
more advanced configuration options, including CMS
clustering and other server-specific settings.
Crystal Enterprise Administrator’s Guide
269
Server management overview
Server management overview
This chapter provides information on a range of server tasks that allow you to
customize the behavior of Crystal Enterprise. It also includes information on the
server settings that you can alter to accommodate the needs of your organization.
The default values for these settings have been chosen to maximize the reliability,
predictability, and consistency of operation of a typical Crystal Enterprise
installation. The default settings guarantee the highest degree of data accuracy and
timeliness. For example, by default, data sharing between reports is disabled.
When running reports on demand, disabling data sharing means that every user
can always assume that they will receive the latest data.
If you prefer to place more emphasis on the efficiency, economy, and scalability of
Crystal Enterprise, you can tune server settings to set your own balance between
system reliability and performance. For example, enabling data sharing between
reports markedly increases system performance when user loads are heavy. To
take advantage of this feature while ensuring that every user receives data that
meets your criteria for timeliness, you can also specify how long data will be shared
between users.
Crystal Enterprise includes two key administrative tools that allow you to view and
to modify a variety of server settings. These two tools are the Crystal Management
Console and the Crystal Configuration Manager:
• Crystal Management Console (CMC)
The CMC is the web-based administration tool that allows you to view and to
modify server settings while Crystal Enterprise is running. For instance, you
will use the CMC when you need to change the status of a server, change server
settings, access server metrics, or create server groups. Because the CMC is a
web-based interface, you are able to configure your Crystal Enterprise servers
remotely over the Internet or through your corporate intranet.
• Crystal Configuration Manager (CCM)
The CCM is a program that allows you to view and to modify server settings
while Crystal Enterprise is offline. It also allows you to accomplish tasks that
require you to take Crystal Enterprise offline. For instance, you use the CCM to
stop the Web Component Server (WCS) or the Crystal Management Server
(CMS), to start Crystal Enterprise after you have stopped the system
completely, and to change the default server port numbers. This tool also allows
you to configure Crystal Enterprise remotely over your corporate network.
You can accomplish some configuration tasks with both tools, while other tasks must
be performed with a specific tool. This chapter takes a task-oriented approach to server
management by first explaining the server settings that are available to you, and then
by showing how to accomplish each task with whichever tool(s) are appropriate.
Related topics
• For an overview of the multi-tier architecture and the Crystal Enterprise server
components, see “Crystal Enterprise Architecture” on page 27.
270
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• For information about creating groups of servers, see “Server group overview”
on page 350.
• With the Crystal Enterprise Software Development Kit (SDK), you can now
access and modify server metrics and settings from your own web
applications. For more information, see the developer documentation available
on your product CD.
Viewing current metrics
The CMC allows you to view server metrics over the Web. These metrics include
general information about each machine, along with details that are specific to the
type of server. The CMC also allows you to view system metrics, which include
information about your product version, your CMS, and your current system activity.
Tip: For an example of how to use server metrics in your own web applications, see
the “View Server Summary” sample on the Crystal Enterprise Admin Launchpad.
Viewing current server metrics
The Servers management area of the CMC displays server metrics that provide
statistics and information about each Crystal Enterprise server. The general
information displayed for each server includes information about the machine that
the server is running on—its name, operating system, total hard disk space, free hard
disk space, total RAM, number of CPUs, and local time. The general information
also includes the time the server started and the version number of the server.
This example shows the metrics for an Event Server that is running on a machine
called Baracus.
Crystal Enterprise Administrator’s Guide
271
Viewing current metrics
For some servers, the Metrics tab includes additional server-specific information:
• Input and Output File Repository Servers
The Metrics tab of each File Repository Server lists the root directory of the files
that the server maintains, indicates the maximum idle time, and displays the
number of active files and active client connections. It also lists the total
available hard disk space, as well as the number of bytes sent and received.
Each File Repository Server also has an Active Files tab, which lists the
filename, the number of readers, and the number of writers for each active file.
• Web Component Server
The Metrics tab of the Web Component Server (WCS) includes statistical data
about the requests that it handles. It lists the total number of requests, the
current number of requests, the total number of bytes sent, the average bytes
per request, the total time taken, and the average time taken per request. This
information is useful in determining how efficiently the WCS is handling the
requests that are sent to it.
• Cache Server
The Metrics tab of the Cache Server displays the maximum number of
processing threads, the maximum cache size, the minutes before an idle job is
closed, the minutes between refreshes from the database, whether or not the
database is accessed whenever a viewer’s file (object) is refreshed, the location
of the cache files, the total threads running, the number of requests served, the
number of bytes transferred, the cache hit rate, the number of current
connections, and the number of requests that are queued.
The Metrics tab also provides a table that lists the Page Servers that the Cache
server has connections to, along with the number of connections made to each
Page Server.
• Event Server
The Metrics tab of the Event Server contains statistics on the files that the server
is monitoring. This tab includes a table showing the file name and the last time
the event occurred.
• Page Server
The Metrics tab of the Page Server contains information on how the server is
running. It lists the maximum number of simultaneous report jobs, the location of
temporary files, the number of minutes before an idle connection is closed, the
minutes before a report job is closed, the maximum number of database records
shown when previewing or refreshing a report, the oldest processed data given to
a client, whether a viewer refresh always hits the database, and the setting for the
Report Job Database Connection. It also shows the number of current connections,
the number of requests queued, the current number of processing threads
running, the total number of requests served, and the total bytes transferred.
• Report Application Server
The Metrics tab of the Report Application Server (RAS) shows the number of
reports that are open, and the number of reports that have been opened. It also
272
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
shows the number of open connections, along with the number of open
connections that have been created.
• Report Job Server
The Metrics tab of the Job Server lists the current number of jobs that are being
processed, the total number of requests received, the total number of failed job
creations, the processing mode, and the location of its temporary files.
• Program Job Server
The Metrics tab of the Program Job Server lists the current number of program
objects that are being processed, the total number of requests received, the total
number of failed program object creations, the processing mode, and the
location of its temporary files.
• Crystal Management Server
The Metrics tab of the CMS lists only the general information about the machine
it is running on. The Properties tab, however, shows a list of users who have
active sessions on the system. Click any user’s link to view the associated
account details.
To view server metrics
1 Go to the Servers management area of the CMC.
2 Click the link to the server whose metrics you want to view.
3 Click the Metrics tab.
Viewing system metrics
The Settings management area of the CMC displays system metrics that provide
general information about your Crystal Enterprise installation. The Properties tab
includes information about the product version and build. It also lists the data
source, database name, and database user name of the CMS database. The Metrics
tab lists current account activity, along with statistics about current and processed
jobs. The Cluster tab lists the name of the CMS you are connected to, the name of
the CMS cluster, and the names of other cluster members.
To view system metrics
1 Go to the Settings management area of the CMC.
2 View the contents of the Properties, Metrics, and Cluster tabs.
Related topics
• For more information about licenses and account activity, see “Licensing
overview” on page 408.
• For information about CMS clusters, see “Clustering Crystal Management
Servers” on page 284.
Crystal Enterprise Administrator’s Guide
273
Viewing and changing the current status of servers
Viewing and changing the current status of servers
The status of a server is its current state of operation: a server can be started,
stopped, enabled, or disabled. To respond to Crystal Enterprise requests, a server
must be started and enabled. A server that is disabled is still running as a process;
however, it is not accepting requests from the rest of Crystal Enterprise. A server
that is stopped is no longer running as a process. This section shows how to modify
the status of servers with the CMC and the CCM.
Starting, stopping, and restarting servers
Starting, stopping, and restarting servers are common actions that you perform
when you configure servers or take them offline for other reasons. The remainder
of this chapter tells you when a certain configuration change requires that you first
stop or restart the server. However, because these tasks appear frequently, the
concepts and differences are explained first, and the general procedures are
provided for reference.
Action
Description
Stopping a server
You must stop Crystal Enterprise servers before you can
modify certain properties and settings.
Starting a server
If you have stopped a server to configure it, you need to
start it to effect your changes and to have the server
resume processing requests.
Restarting a server
Restarting a server is a shortcut to stopping a server
completely and then starting it again. You can change
certain settings without stopping the server; however, the
changes typically do not take effect until your restart the
server.
For example, if you want to change the name of a CMS, or if you want to configure
the WCS to support NT Single Sign On, then you must first stop the server. Once
you have made your changes, you start the server again to effect your changes.
Tip: When you stop (or restart) a server, you terminate the server’s process,
thereby stopping the server completely. If you want to prevent a server from
receiving requests without actually stopping the server process, you can also
enable and disable servers. We recommend that you disable Report Job Servers
and Program Job Servers before stopping them so that they can finish processing
any jobs they have in progress before stopping. For details, see “Enabling and
disabling servers” on page 276.
274
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To start, stop, or restart servers over the Web
Note: You cannot stop the CMS or the WCS over the Web. You must use the CCM
instead. See “Stopping a Crystal Management Server” on page 276 for more
information.
1 Go to the Servers management area of the CMC.
A list of servers appears. The icon associated with each server identifies its
status:
• Running is indicated by a server with a green arrow.
• Stopped is indicated by a server with a red arrow.
• Disabled is indicated by a server with a red circle.
2 Select the check box for the server whose status you want to change.
3 Depending upon the action you need to perform, click Start, Stop, or Restart.
You may be prompted for network credentials that allow you to start and stop
services running on the remote machine.
4 Click Refresh to update the page.
To start, stop, or restart a Windows server with the CCM
1 Start the CCM.
2 Select the server that you want to start, stop, or restart.
3 On the toolbar, click the appropriate button.
Toolbar Icon
Action
Start the selected server.
Stop the selected server.
Restart the selected server.
You may be prompted for network credentials that allow you to start and stop
services running on the remote machine.
The CCM performs the action and refreshes the list of servers.
To start, stop, or restart a UNIX server with the CCM
Use the ccm.sh script. For reference, see “ccm.sh” on page 436.
Crystal Enterprise Administrator’s Guide
275
Viewing and changing the current status of servers
Stopping a Crystal Management Server
If your Crystal Enterprise installation has a single Crystal Management Server
(CMS), shutting it down will make Crystal Enterprise unavailable to your users
and will interrupt the processing of reports and programs. Before stopping your
CMS, you may wish to disable your processing servers so that they can finish any
jobs in progress before Crystal Enterprise shuts down. See “Enabling and disabling
servers” on page 276 for more information.
If you have a CMS cluster consisting of more than one active CMS, you can shut
down a single CMS without losing data or affecting system functionality. The
other CMS in the cluster will assume the workload of the stopped server. Using a
CMS cluster enables you to perform maintenance on each of your Crystal
Management Servers in turn without taking Crystal Enterprise out of service.
For more information on CMS clusters, see “Clustering Crystal Management
Servers” on page 284.
Enabling and disabling servers
When you disable a Crystal Enterprise server, you prevent it from receiving and
responding to new Crystal Enterprise requests, but you do not actually stop the
server process. This is especially useful when you want to allow a server to finish
processing all of its current requests before you stop it completely.
For example, you may want to stop a Report Job Server before rebooting the machine
it is running on. However, you want to allow the server to fulfill any outstanding
report requests that are in its queue. First, you disable the Report Job Server so it
cannot accept any additional requests. Next, go to the Crystal Management Console
to monitor when the server completes the jobs it has in progress. (From the Servers
management area, choose the server name and then the metrics tab). Then, once it
has finished processing current requests, you can safely stop the server.
Note: The CMS must be running in order for you to enable and/or disable other
servers.
To enable and disable servers over the Web
1 Go to the Servers management area of the CMC.
The icon associated with each server identifies its status. In this example, the
Event Server is disabled (but not stopped), and the remaining servers are
running and enabled.
276
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
2 Select the check box for the server whose status you want to change.
3 Depending upon the action you need to perform, click Enable or Disable.
To enable or disable a Windows server with the CCM
1 Start the CCM.
2 On the toolbar, click Enable/Disable.
3 When prompted, log on to your CMS with the credentials that provide you
with administrative privileges to Crystal Enterprise.
4 Click Connect.
The Enable/Disable Servers dialog box appears.
This dialog box lists all of the Crystal Enterprise servers that are registered with
your CMS, including servers running on remote machines. By default, servers
running on remote machines are displayed as MACHINE.servertype. So, in this
example, LCONNORS02.eventserver is an Event Server running on a remote
machine called LCONNORS02. The server named Input is the Input File Repository
Server running on the local machine. In this example, all of the listed servers are
currently enabled.
Crystal Enterprise Administrator’s Guide
277
Viewing and changing the current status of servers
5 To disable a server, clear the check box in the Server Name column.
This example disables all servers running on LCONNORS02.
6 Click OK to effect your changes and return to the CCM.
To enable or disable a UNIX server with the CCM
Use the ccm.sh script. For reference, see “ccm.sh” on page 436.
Printing, copying, and refreshing server status
When using the CCM on Windows, you can print and copy the properties of a
server, and refresh the list of servers.
To print the status of a server
1 Start the CCM.
2 Select the server(s).
3 Click Print.
The Print dialog box appears.
4 Click OK.
A brief listing of the server’s properties is printed, including the Display Name,
Version, Command Line, Status, and so on.
To copy the status of a server
To save the status of a server, you can copy the details from the CCM to a document
or to an email message (if you want to send the status information to someone else).
1 Start the CCM.
2 Select the server(s).
3 Click Copy.
4 Paste the information into a document for future reference.
278
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To refresh the list of servers
• To ensure you are looking at the latest information, click Refresh.
Note: Disabled servers may not appear in this list. Click Enable/Disable to view a
list of servers and ensure that each is enabled.
Configuring the application tier
This section includes technical information and procedures that show how you can
modify settings for the application tier. If you are already familiar with the Crystal
Enterprise architecture, you will recognize this graphic representation of the
application tier.
The majority of the settings discussed here allow you to integrate Crystal Enterprise
more effectively with your current hardware, software, and network configurations.
Consequently, the settings that you choose will depend largely upon your own
requirements.
Note: This section does not show how to configure your web server with the Web
Connector, nor does it show how to set up effective communication between the
Web Connector and the Web Component Server, or how to configure your Web
Application Server to deploy Crystal Enterprise applications. These tasks are
typically performed when you install Crystal Enterprise. For details, see the
Crystal Enterprise Installation Guide. For further troubleshooting, see “Working
with Firewalls” on page 367.
Configuring properties for the Web Component Server
Modifying logging behavior of the Web Component Server
The Properties tab of the Web Component Server (WCS) allows you to specify the
location of its log files and the types of information that it logs for each Crystal
Enterprise web request.
The web attributes that you can audit include: Date, Time, IP address and port,
Duration, Bytes transferred, Used cache, Method, URI, URI-stem, URI-query, and
Status. There are no performance penalties for logging this information. It is
recommended that you leave logging enabled.
Crystal Enterprise Administrator’s Guide
279
Configuring the application tier
To change the logging behavior of the WCS
1 Go to the Servers management area of the CMC.
2 Click the link to the WCS whose settings you want to change.
3 Make your changes on the Properties tab.
This example shows the Logging area of the Properties tab. Here, the log files
are saved to the default file location for a WCS that is running on Windows.
4 Click either Apply or Update:
• Click Apply to submit changes and restart the server so that the changes
take effect immediately.
• Click Update to save the changes. You must restart the server for the
changes to take effect.
Modifying report viewing and viewer options
The Properties tab of the WCS allows you to modify report viewing settings that
affect users who view reports with the legacy DHTML, ActiveX, and Java viewers.
You can change the default directory where the WCS stores its temporary image
files. And you can customize the “look and feel“ of the different viewer controls to
suit users’ preferences or to suit your administrative requirements.
Note: Changing options here affects only the properties of legacy DHTML viewers
(that is, viewers shipped with previous versions of Crystal Enterprise). To change
these options for a DHTML viewer shipped with Crystal Enterprise 10, you must
change the CSP pages that invoke the viewers. See the developer documentation
for details.
Tip: On Windows, you can also change some of these settings in the CCM. Stop the
WCS and view its Properties. Then click the Configuration tab.
280
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
This table lists the properties that you can change for each of the viewer controls.
Viewer Property
DHTML Viewer ActiveX Viewer Java Viewer
Drilldown for more detail
Supported
Supported
Supported
Hide the Group Tree
(if it is displayed)
Supported
Supported
Supported
Group Tree
Supported
Supported
Supported
Refresh Report data
Not Supported
Supported
Supported
Search the Report
Not Supported
Supported
Supported
Export the Report
Not Supported
Supported
Supported
Zoom
Not Supported
Supported
Supported
Print the Report
Not Supported
Supported
Supported
Product logo (if applicable)
Not Supported
Supported
Supported
To modify report viewing and viewer settings
1 Go to the Servers management area of the CMC.
2 Click the link to the WCS whose settings you want to change.
3 Make your changes on the Properties tab.
This example shows the Report Viewing area of the Properties tab. Here, the
WCS is using the default values.
4 Click either Apply or Update:
• Click Apply to submit changes and restart the server so that the changes
take effect immediately.
• Click Update to save the changes. You must restart the server for the
changes to take effect.
Crystal Enterprise Administrator’s Guide
281
Configuring the application tier
Enabling Single Sign On
On the Properties tab, use the Single Sign On check boxes only when you are
running more than one WCS. (If you are running a single WCS, use the CCM
instead.) This feature requires your web server to support Integrated Windows
Authentication. For more information on Single Sign On, see “Setting up NT Single
Sign On” on page 83 or “Using AD Single Sign On” on page 102.
Configuring the Web Component Adapter
In Crystal Enterprise installations that use the Crystal Enterprise Java SDK, the
Web Component Server is replaced by a Web Component Adapter (WCA) running
on a Java application server. (These Crystal Enterprise installations include all
UNIX installations, and any installation of Crystal Enterprise on Windows that has
been configured to use the Java version of the Crystal Enterprise web desktop, as
per the instructions in Crystal Enterprise Installation Guide. The WCA provides
support for the Crystal Management Console and CSP applications. The Web
Component Adapter is a Java web application; it does not appear as a server in the
Crystal Management Console or in the Crystal Configuration Manager.
If you need to configure any of the parameters formerly controlled through the
WCS, you can do so by editing the web.xml deployment descriptor file associated
with the WCA.
To configure web.xml
The web.xml file used by the WCA is in the WEB-INF subdirectory of the
webcompadapter.war archive file stored in the crystal_root/enterprise/JavaSDK/
applications directory on UNIX, or C:\Program Files\Common Files\Crystal
Decisions\2.5\jars\JavaSDK\applications on Windows.
Each of the options displayed in the CMC or the CCM for the WCS appears as a
context parameter in web.xml. For example, the context parameter that controls
whether a group tree will be generated looks like this:
<context-param>
<param-name>viewrpt.groupTreeGenerate</param-name>
<param-value>true</param-value>
<desctiption>”true” or “false” value determining whether a group tree
will be generated.</description>
</context-param>
To change the value of a context parameter, edit the value between the <paramvalue> </param-value> tags.
Your Java Web Application Server may provide tools to allow you to edit web.xml
directly from an administrative console. Otherwise you need to stop your
application server and extract the web.xml file from the webcompadapter.war archive
before editing it using a text editor such as Notepad or vi. Once you have made
282
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
your changes to web.xml, you must reinsert the file into the WEB-INF directory in
webcompadapter.war, and restart your application server.
Tip: To reinsert web.xml into WEB-INF using WinZip, right-click on 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.
When you install more than one WCA, each webcomponentadapter.war file contains
its own web.xml file containing configuration parameters for that WCA. However,
you can only set the parameters listed in the following table individually for each
WCA. The remaining parameters must be the same for all WCA in your system.
Context Parameter
Description
display-name
Equivalent to WCA name, or friendly name
of WCS
cspApplication.defaultPage
The default page that will be loaded if no
filename is specified in a particular request.
cspApplication.dir
This is the real path to the directory
containing the CSP/WAS application(s) that
you would like to host. This is a required
field.
connection.cms
This is the name (or name and port number)
of the CMS that you would like your
application(s) to connect to. This is
equivalent to setting -requestport for the
WCS.
connection.listeningPort
This field defaults to the port that the WCA
related servlets are running on. This setting
is equivalent to configuring the WCS to listen
on a port for the web connector, using -port.
log.file
Filename of the logfile including full real
path to file, excluding extension. Defaults to
WCA with no path
log.ext
File extension of logfile, defaults to .log
log.isRolling
Determines whether or not the logs will be
rotated, defaults to true.
log.size
If log rolling is turned on, this will govern
the max size before logfile is rotated.
Accepted suffix: MB, KB and GB.
log.level
The default loglevel is “error.”
log.entryPattern
Please refer to log4j documentation for
accepted log entry patterns.
Crystal Enterprise Administrator’s Guide
283
Configuring the intelligence tier
Configuring the intelligence tier
This section includes technical information and procedures that show how you can
modify settings for the Crystal Enterprise servers that make up the intelligence
tier. If you are already familiar with the Crystal Enterprise architecture, you will
recognize this graphic representation of the intelligence tier.
The majority of the settings discussed here allow you to integrate Crystal
Enterprise more effectively with your current hardware, software, and network
configurations. Consequently, the settings that you choose will depend largely
upon your own requirements.
Clustering Crystal Management Servers
If you have a large or mission-critical implementation of Crystal Enterprise, you
will probably want to run several CMS machines together in a CMS cluster. A CMS
cluster consists of two or more CMS servers working together to maintain the
system database. If a machine that is running one CMS fails, a machine with
another CMS will continue to service Crystal Enterprise requests. This “failover”
support helps to ensure that Crystal Enterprise users can still access information
when there is equipment failure.
This section shows how to add a new CMS cluster member to a production system
that is already up and running. When you add a new CMS to an existing cluster,
you instruct the new CMS to connect to the existing CMS database and to share the
processing workload with any existing CMS machines. For information about your
current CMS and CMS cluster, go to the Settings management area of the CMC and
click the Cluster tab.
Before clustering CMS machines, you must make sure that each CMS is installed
on a system that meets the detailed requirements (including version levels and
patch levels) for operating system, database server, database access method,
database driver, and database client outlined in the platforms.txt file included in
your product distribution.
In addition, you must meet the following clustering requirements:
• For best performance, the database server that you choose to host the system
database must be able to process small queries very quickly. The CMS
communicates frequently with the system database and sends it many small
queries. If the database server is unable to process these requests in a timely
manner, Crystal Enterprise performance will be greatly affected.
284
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• For best performance, run each CMS cluster member on a machine that has the
same amount of memory and the same type of CPU.
• Configure each machine similarly:
• Install the same operating system, including the same version of operating
system service packs and patches.
• Install the same version of Crystal Enterprise (including patches, if applicable).
• Ensure that each CMS connects to the CMS database in the same manner:
whether you use native or ODBC drivers, ensure that the drivers are the
same on each machine, and are a supported version.
• Ensure that each CMS uses the same database client to connect to its system
database, and that it is a supported version.
• Check that each CMS uses the same database user account and password to
connect to the CMS database. This account must have create, delete, and
update rights on the system database.
• Run each CMS service/daemon under the same account. (On Windows, the
default is the “LocalSystem” account.)
• Verify that the current date and time are set correctly on each CMS machine
(including settings for daylight savings time).
• Ensure that each and every CMS in a cluster is on the same Local Area
Network.
• If you wish to enable auditing, each CMS must be configured to use the same
auditing database and to connect to it in the same manner. The requirements
for the auditing database are the same as those for the system database in
terms of database servers, clients, access methods, drivers, and user IDs.
Tip: By default, a CMS cluster name reflects the name of the first CMS that you
install, but the cluster name is prefixed by the @ symbol. For instance, if your
existing CMS is called CRYSTALCMS, then the default cluster name is @CRYSTALCMS. To
modify the default name, see “Changing the name of a CMS cluster” on page 288.
There are two ways to add a new CMS cluster member. Follow the appropriate
procedure, depending upon whether or not you have already installed a second CMS:
• “Installing a new CMS and adding it to a cluster” on page 286
See this section if you have not already installed the new CMS on its own
machine.
• “Adding an installed CMS to a cluster” on page 286
Follow this procedure if you have already installed a second, independent CMS
on its own machine. While testing various server configurations, for instance,
you might have set up an independent Crystal Enterprise system with its own
CMS. Follow this procedure when you want to incorporate this independent
CMS into your production system.
Note: Back up your current CMS database before making any changes. If necessary,
contact your database administrator.
Crystal Enterprise Administrator’s Guide
285
Configuring the intelligence tier
Installing a new CMS and adding it to a cluster
When you install a new CMS, you can quickly cluster it with your existing CMS.
Run the Crystal Enterprise installation and setup program on the machine where
you want to install the new CMS cluster member. The setup program allows you
to perform an Expand installation. During the Expand installation, you specify the
existing CMS whose system you want to expand, and you select the components
that want to install on the local machine. In this case, specify the name of the CMS
that is running your existing system, and choose to install a new CMS on the local
machine. Then provide the Setup program with the information it needs to connect
to your existing CMS database. When the Setup program installs the new CMS on
the local machine, it automatically adds the server to your existing CMS cluster.
For complete information on running the Setup program and performing the
Expand installation, see the Crystal Enterprise Installation Guide.
Adding an installed CMS to a cluster
In these steps, the independent CMS refers to the one that you want to add to a
cluster. You will add the independent CMS to your production CMS cluster. By
adding an independent CMS to a cluster, you disconnect the independent CMS
from its own database and instruct it to share the system database that belongs to
your production CMS.
Before starting this procedure, ensure that you have a database user account with
Create, Delete, and Update rights to the database storing the Crystal Enterprise
tables. Ensure also that you can connect to the database from the machine that is
running the independent CMS (through your database client software or through
ODBC, according to your configuration). Also ensure that the CMS you are adding
to the cluster meets the requirements outlined in
Note: Back up your current CMS database before beginning this procedure. If
necessary, contact your database administrator.
To add an installed CMS to a cluster on Windows
1 Use the CCM to stop the independent Crystal Management Server.
2 With the CMS selected, click Specify CMS Data Source on the toolbar.
286
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
The CMS Database Setup dialog box appears.
3 Click Select a Data Source; then click OK.
4 In the Select Database Driver dialog box, specify whether you want to connect
to the production CMS database through ODBC, or through one of the native
drivers.
5 Click OK.
6 The remaining steps depend upon the connection type you selected:
• If you selected ODBC, the Windows “Select Data Source” dialog box
appears. Select the ODBC data source that corresponds to your production
CMS database; then click OK. If prompted, provide your database
credentials and click OK. The CCM connects to the database server and
adds the new CMS to the cluster.
• If you selected a native driver, you are prompted for your database Server
Name, your Login ID, and your Password. Once you provide this information,
the CCM connects to the database server and adds the new CMS to the cluster.
The SvcMgr dialog box notifies you when the CMS database setup is complete.
7 Click OK.
8 Start the Crystal Management Server.
To add an installed CMS to a cluster on UNIX
Use the cmsdbsetup.sh script. For reference, see “cmsdbsetup.sh” on page 438.
Crystal Enterprise Administrator’s Guide
287
Configuring the intelligence tier
Changing the name of a CMS cluster
By default, a CMS cluster name reflects the name of the first CMS that you install,
but the cluster name is prefixed by the @ symbol. For instance, if your existing CMS
is called CRYSTALCMS, then the default cluster name is @CRYSTALCMS.
This procedure allows you to change the name of a cluster that is already installed
and running. To change the cluster name, you need only stop one of the CMS
cluster members. The remaining CMS cluster members are dynamically notified of
the change.
For optimal performance, after changing the name of the CMS cluster reconfigure
each Crystal Enterprise server so that it registers with the CMS cluster, rather than
with an individual CMS.
To change the cluster name on Windows
1 Use the CCM to stop any Crystal Management Server that is a member of the
cluster.
2 With the CMS selected, click Properties on the toolbar.
3 Click the Configuration tab.
4 Select the Change Cluster Name to check box.
5 Type the new name for the cluster.
6 Click OK and then start the Crystal Management Server.
The CMS cluster name is now changed. All other CMS cluster members are
dynamically notified of the new cluster name (although it may take several
minutes for your changes to propagate across cluster members).
7 Go to the Servers management area of the CMC and check that all of your
servers remain enabled. If necessary, enable any servers that have been
disabled by your changes.
To change the cluster name on UNIX
Use the cmsdbsetup.sh script. For reference, see “cmsdbsetup.sh” on page 438.
To register servers with the CMS cluster on Windows
1 Use the CCM to stop a Crystal Enterprise server.
2 Select the server from the list, and then click Properties.
3 Click the Configuration tab.
4 In the CMS Name box, type the name of the cluster.
The name of the cluster begins with the @ symbol. For example, if the cluster
name was changed to ENTERPRISE, type @ENTERPRISE in the box.
5 Click OK, and then start the server. Repeat for each Crystal Enterprise server
in your installation.
288
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To registers servers with the CMS cluster on UNIX
1 Use ccm.sh to stop each server.
2 Use a text editor such as vi to open the ccm.config file found in the root
directory of your Crystal Enterprise installation.
3 Find the -ns command in the launch string for each server, and change the
name of the CMS to the name of the CMS cluster.
The name of the cluster begins with the @ symbol. For example, if the cluster
name was changed to ENTERPRISE, type @ENTERPRISE. Do not include a port
number with the cluster name.
4 Save the file, and then use ccm.sh to restart the servers.
Copying CMS data from one database to another
Crystal Enterprise enables you to copy the contents of one CMS database into
another database. This procedure is also referred to as migrating a CMS database.
You can migrate CMS data from a different CMS database (versions 8.0 through 10
of Crystal Enterprise) into your current CMS database. Or, you can migrate the
data from your current CMS database into a different data source.
Throughout this section, the source CMS database refers to the database that holds
the data you are copying; this data is copied into the destination database. The
destination database is initialized before the new data is copied in, so any existing
contents of the destination database are permanently deleted (all Crystal Enterprise
tables are destroyed permanently and then recreated). Once the data has been
copied, the destination database is established as the current database for the CMS.
Note: Prior to Crystal Enterprise 10, the CMS was known as the Automated
Process Scheduler (APS).
Tip: If you want to import users, groups, folders, and reports from one system to
another, without deleting the contents of the current CMS database, see
“Importing with the Crystal Import Wizard” on page 135.
Preparing to migrate a CMS database
Before migrating a CMS database, take the source and the destination environments
offline by disabling and subsequently stopping all servers. Back up both CMS
databases, and back up the root directories used by all Input and Output File
Repository Servers. If necessary, contact your database or network administrator.
Ensure that you have a database user account that has permission to read all data
in the source database, and a database user account that has Create, Delete, and
Update rights to the destination database. Ensure also that you can connect to both
databases—through your database client software or through ODBC, according to
your configuration—from the CMS machine whose database you are replacing.
Crystal Enterprise Administrator’s Guide
289
Configuring the intelligence tier
Make a note of the license keys you purchased for the current version of Crystal
Enterprise. During migration, license keys that are present in the destination
database are retained only if the source database contains no license keys that are
valid for the current version of Crystal Enterprise. License keys in the destination
database are replaced with license keys from the source database when the source
license keys are valid for the current version of Crystal Enterprise. License keys
from earlier versions of Crystal Enterprise are not copied.
If you are copying CMS data from a different CMS database (version 8.0, 8.5, 9, or
10) of Crystal Enterprise) into your current CMS database, your current CMS
database is the destination database whose tables are deleted before they are
replaced with the copied data. In this scenario, make note of the current root
directories used by the Input and Output File Repository Servers in the source
environment. The database migration does not actually move report files from one
directory location to another. After you migrate the database, you will connect
your new Input and Output File Repository Servers to the old root directories, thus
making the report files available for the new system to process. Log on with an
administrative account to the CMS machine whose database you want to replace.
Complete the procedure that corresponds to the version of the source environment:
• “Copying data from a CMS on Windows” on page 291
• “Copying data from a Crystal Enterprise 8 APS on Windows” on page 292
If you are copying a CMS database from its current location to a different database
server, your current CMS database is the source environment. Its contents are
copied to the destination database, which is then established as the active database
for the current CMS. This is the procedure to follow if you want to move the default
CMS database on Windows from the local Microsoft Data Engine (MSDE) to a
dedicated database server, such as Microsoft SQL Server, Informix, Oracle, DB2, or
Sybase. Log on with an administrative account to the machine that is running the
CMS whose database you want to move. Complete the following procedure:
• “Copying data from a CMS on Windows” on page 291
• “Copying data from a CMS installed on UNIX” on page 293
Note:
• When you migrate a CMS database from an earlier version of Crystal
Enterprise, the database and database schema are upgraded to the format
required by the current version of Crystal Enterprise.
• When you copy data from one database to another, the destination database is
initialized before the new data is copied in. That is, if your destination
database does not contain the four Crystal Enterprise 10 system tables, these
tables are created. If the destination database does contain Crystal Enterprise
10 system tables, the tables will be permanently deleted, new system tables
will be created, and data from the source database will be copied into the new
tables. Other tables in the database, including previous versions of Crystal
Enterprise system tables, are unaffected.
290
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
Copying data from a CMS on Windows
Use this procedure if your CMS is installed on Windows and you are copying data
from Crystal Enterprise versions 8.5, 9, or 10. If you are copying data from version
8 of Crystal Enterprise, please see “Copying data from a Crystal Enterprise 8 APS
on Windows” on page 292.
1 Use the CCM to stop the Crystal Management Server.
2 With the CMS selected, click Specify CMS Data Source on the toolbar.
3 Click Copy data from another Data Source; then click OK.
The Specify Data Source dialog box appears.
4 In the “Source contains data from version” list, click Autodetect (or explicitly
select the version of the source CMS database).
You must now specify the source CMS database whose contents you want to copy.
5 Click Specify.
6 In the Select Database Driver dialog box, specify whether you want to connect
to the source CMS database through ODBC, Informix, or through one of the
native drivers.
7 Click OK.
8 The next steps depend upon the connection type you selected:
• If you selected ODBC or Informix, the Windows “Select Data Source”
dialog box appears. Select the data source that corresponds to the source
CMS database; then click OK. If prompted, provide your database
credentials and click OK.
• If you selected a native driver, provide your database Server Name, your
Login ID, and your Password; then click OK.
You are returned to the Specify Data Source dialog box. You must now specify
the destination CMS database whose contents you want to replace with the
copied data.
Crystal Enterprise Administrator’s Guide
291
Configuring the intelligence tier
Tip: If the correct destination database already appears in the “Copy to the
following data source” field, proceed to step 13.
9 Click Browse.
10 In the Select Database Driver dialog box, specify whether you want to connect
to the destination CMS database through ODBC, or through one of the native
drivers.
11 Click OK.
12 The next steps depend upon the connection type you selected:
• If you selected ODBC, the Windows “Select Data Source” dialog box
appears. Select the ODBC data source that corresponds to the destination
CMS database; then click OK. If prompted, provide your database
credentials and click OK.
• If you selected a native driver, provide your database Server Name, your
Login ID, and your Password; then click OK.
You are returned to the Specify Data Source dialog box. You are now ready to
copy the CMS data.
13 Click OK and, when prompted to confirm, click Yes.
The SvcMgr dialog box notifies you when the CMS database setup is complete.
14 Click OK.
15 Proceed to “Completing a CMS database migration” on page 294.
Copying data from a Crystal Enterprise 8 APS on Windows
Note: Prior to Crystal Enterprise 10, the CMS was known as the Automated
Process Scheduler (APS).
Use this procedure if your CMS is installed on Windows, and you are copying data
from a Crystal Enterprise 8 APS system database.
1 Use the CCM to stop the Crystal Management Server.
2 With the CMS selected, click Specify CMS Data Source on the toolbar.
3 Click Copy data from another Data Source; then click OK.
The Specify Data Source dialog box appears.
4 In the “Source contains data from version” list, click Crystal Enterprise 8.0.
You must now specify the source CMS database whose contents you want to copy.
5 Click Specify.
6 In the “Browse data” dialog box, click one of the following:
• CMS machine name
Click this option if you have administrative rights to the Crystal Enterprise 8
CMS machine. Your administrative rights allow the CCM to read the data
292
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
source information from the Windows Registry on the CMS machine. Click
OK and use the Browse for Computer dialog box to specify the CMS machine.
• CMS ODBC data source
Click this option if you do not have administrative rights to the Crystal
Enterprise 8 CMS machine. Use the Windows “Select Data Source” dialog
box to select (or create) an ODBC data source that provides the local
machine with access to the Crystal Enterprise 8 CMS database. If prompted,
provide your database credentials and click OK.
You are returned to the Specify Data Source dialog box. You must now specify
the destination CMS database whose contents you want to replace with the
copied data.
Tip: If the correct destination database already appears in the “Copy to the
following data source” field, proceed to step 11.
7 Click Browse.
8 In the Select Database Driver dialog box, specify whether you want to connect
to the destination CMS database through ODBC, or through one of the native
drivers.
9 Click OK.
10 The next steps depend upon the connection type you selected:
• If you selected ODBC, the Windows “Select Data Source” dialog box
appears. Select the ODBC data source that corresponds to the destination
CMS database; then click OK. If prompted, provide your database
credentials and click OK.
• If you selected a native driver, provide your database Server Name, your
Login ID, and your Password; then click OK.
You are returned to the Specify Data Source dialog box. You are now ready to
copy the CMS data.
11 Click OK and, when prompted to confirm, click Yes.
The SvcMgr dialog box notifies you when the CMS database setup is complete.
Note: Migration of a large source database could take several hours.
12 Click OK.
13 Proceed to “Completing a CMS database migration” on page 294.
Copying data from a CMS installed on UNIX
Note: Prior to Crystal Enterprise 10, the CMS was known as the Automated
Process Scheduler (APS).
Use this procedure if your CMS is installed on UNIX and you are copying data
from Crystal Enterprise versions 8.5, 9, or 10.
Then proceed to “Completing a CMS database migration” on page 294.
Crystal Enterprise Administrator’s Guide
293
Configuring the intelligence tier
Note:
• On UNIX you can not migrate directly from a source environment that uses an
ODBC connection to the CMS database. If your source CMS database uses
ODBC, you must first migrate that system to a supported native driver. (See
“Copying data from a CMS on Windows” on page 291.)
• If your CMS is installed on UNIX, you cannot migrate directly from a Crystal
Enterprise version 8 APS.
To copy data from a CMS installed on UNIX
1 Use ccm.sh to stop the Crystal Management Server. (See “ccm.sh” on page 436
for details.)
2 Run cmsdbsetup.sh. When prompted, enter the name of your CMS or press
enter to select the default name.
Tip: For information on finding the name of your CMS, see “ccm.sh” on
page 436.
3 Type copy to begin the database migration.
4 The script prompts you to confirm that all data in the destination database will
deleted. Type yes, and then press enter to proceed.
5 Next the script asks you for the version of your source Crystal Enterprise
installation. You can also select autodetect to have the version of the source
detected automatically. Press Enter.
6 Now the script asks you if you want to use the current CMS database as your
destination.
If you type no, you are first asked for information about the new destination
database, and are then prompted for information on the source database. If you
type yes, you are prompted for information about the source CMS database.
7 After entering the source information, the script will begin the migration process.
Note: Migration of a large source database could take several hours.
8 The script notifies you when migration is complete.
If errors occurred during the migration, the script gives you the location of a log
file explaining the migration results.
9 Proceed to “Completing a CMS database migration” on page 320.
Completing a CMS database migration
When you finish copying data from the source database to the destination
database, complete these steps before allowing users to access the system.
When migrating from an older version of Crystal Enterprise, servers that existed
in the source installation do not appear in the migrated install. This occurs because
there cannot be a mix of old and new servers in a Crystal Enterprise installation.
294
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
Server groups from the old installation appear in the new system, but they will be
empty. New servers are automatically detected and added to the servers list
(outside of any group) in a disabled state. You must enable these servers before they
can be used. You may add the new servers to the imported groups as appropriate.
Reports that depend on a particular server group for scheduled processing will not
execute until a job server is added to that group. Reports that depend on a particular
server group for processing are not available until servers are added to that group.
To complete a CMS database migration on Windows
1 If errors occurred during migration, a db_migration log file was created in the
logging directory on the machine where you ran the CCM to carry out the
migration. The CCM will notify you if you need to check the log file.
The default logging directory is:
C:\Program Files\Crystal Decisions\Enterprise10\Logging\
2 If you migrated CMS data from a different CMS database into your current CMS
database, you need to make your old input and output directories available to the
new Input and Output File Repository Servers. You can do this in several ways:
• Copy the contents of the original input root directory into the root directory
that the new Input File Repository Server is already configured to use. Then
copy the contents of the original output directory into the root directory
that the new Output File Repository is already configured to use.
• Reconfigure the new Input and Output File Repository Servers to use the
old input and output root directories.
• If the old Input and Output File Repository Servers are running on a
dedicated machine, you can run the Crystal Enterprise setup program to
upgrade the servers directly. Then you need not move the input and output
directories. Instead, modify the -ns option in both servers’ command lines
to have them register with your new CMS. (Consult “Server Command
Lines” on page 425 for information on command line options.)
For more information, see “Setting root directories and idle times of the File
Repository Servers” on page 300.
3 Use the Crystal Configuration Manager (CCM) to start the CMS on the local
machine.
4 Start and enable the WCS, and check that your web server is running.
5 Log on to the Crystal Management Console with the default Administrator
account, using Enterprise authentication.
Tip: If you just replaced your CMS database with data from an older system,
keep in mind that you now need to provide the Administrator password that
was valid in the older system.
6 Go to the Authorization management area and check that your Crystal
Enterprise license keys are entered correctly.
Crystal Enterprise Administrator’s Guide
295
Configuring the intelligence tier
7 In the CCM, start and enable the Input File Repository Server and the Output
File Repository Server.
8 Go to the Servers management area of the Crystal Management Console and
verify that the Input File Repository Server and the Output File Repository
Server are both started and enabled.
9 Click the link to each File Repository Server and, on the Properties tab, check
that the Root Directory points to the correct location.
10 Return to the Crystal Configuration Manager.
11 If objects in your source database require updating, the Update Objects button
on the toolbar contains a flashing red exclamation mark. Click Update
Objects.
12 When prompted, log on to your CMS with credentials that provide you with
administrative privileges to Crystal Enterprise.
The Update Objects dialog box tells you how many objects require updating.
Objects typically require updating because their internal representation has
changed in the new version of Crystal Enterprise, or because the objects require
new properties to support the additional features offered by Crystal Enterprise
10. Because your Crystal Management Server was stopped when the migration
occurred, you need to update the objects now.
13 If there are objects that require updating, click Update, otherwise click Cancel.
14 Start and enable the remaining Crystal Enterprise servers.
15 Verify that Crystal Enterprise requests are handled correctly, and check that
you can view and schedule reports successfully.
To complete a CMS database migration on UNIX
1 If errors occurred during migration, a db_migration log file was created in the
logging directory on the machine where you ran cmsdbsetup.sh to carry out the
migration. The script will notify you if you need to check the log file.
The default logging directory is:
crystal_root/logging
where crystal_root is the absolute path to the root crystal directory of your
Crystal Enterprise installation.
2 If you migrated CMS data from a different CMS database into your current CMS
database, you need to make your old input and output directories available to the
new Input and Output File Repository Servers. You can do this in several ways:
• Copy the contents of the original input root directory into the root directory
that the new Input File Repository Server is already configured to use. Then
copy the contents of the original output directory into the root directory
that the new Output File Repository is already configured to use.
296
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• Reconfigure the new Input and Output File Repository Servers to use the
old input and output root directories.
• If the old Input and Output File Repository Servers are running on a
dedicated machine, you can run the Crystal Enterprise setup program to
upgrade the servers directly. Then you need not move the input and output
directories. Instead, modify the -ns option in both servers’ command lines
to have them register with your new CMS. (Consult “Server Command
Lines” on page 425 for information on command line options.)
For more information, see “Setting root directories and idle times of the File
Repository Servers” on page 300.
3 Use the ccm.sh script to start the CMS on the local machine. (See “ccm.sh” on
page 436 for instructions.)
4 Ensure that the Java web application server that hosts your Web Component
Adapter is running.
5 Log on to the Crystal Management Console with the default Administrator
account, using Enterprise authentication.
Tip: If you just replaced your CMS database with data from an older system,
keep in mind that you now need to provide the Administrator password that
was valid in the older system.
6 Go to the Authorization management area and check that your Crystal
Enterprise license keys are entered correctly.
7 Use the ccm.sh script to start and enable the Input File Repository Server and
the Output File Repository Server.
8 Go to the Servers management area of the Crystal Management Console and
verify that the Input File Repository Server and the Output File Repository
Server is started and enabled.
9 Click the link to each File Repository Server and, on the Properties tab, check
that the Root Directory points to the correct location.
10 Run the ccm.sh script again. If you migrated a source database from an earlier
version of Crystal Enterprise, enter the following command:
./ccm.sh -updateobjects authentication info
See “UNIX Tools” on page 435 for information on the authentication
information required by ccm.sh.
Objects typically require updating because their internal representation has
changed in the new version of Crystal Enterprise, or because the objects require
new properties to support the additional features offered by Crystal Enterprise 10.
11 Use ccm.sh to start and enable the remaining Crystal Enterprise servers.
12 Verify that Crystal Enterprise requests are handled correctly, and check that
you can view and schedule reports successfully.
Crystal Enterprise Administrator’s Guide
297
Configuring the intelligence tier
Deleting and recreating the CMS database
This procedure shows how to recreate (re-initialize) the current CMS database. By
performing this task, you destroy all data that is already present in the database.
This procedure is useful, for instance, if you have installed Crystal Enterprise in a
development environment for designing and testing your own, custom web
applications. You can re-initialize the CMS database in your development
environment every time you need to clear the system of absolutely all its data.
When you recreate the CMS database with the CCM, your existing license keys
should be retained in the database. However, if you need to enter license keys
again, log on to the CMC with the default Administrator account (which will have
been reset to have no password). Go to the Authorization management area and
enter your information on the License Keys tab.
Note: Remember that all data in your current CMS database will be destroyed if
you follow this procedure. Consider backing up your current CMS database
before beginning. If necessary, contact your database administrator.
To recreate the CMS database on Windows
1 Use the CCM to stop the Crystal Management Server.
2 With the CMS selected, click Specify CMS Data Source on the toolbar.
3 In the CMS Database Setup dialog box, click Recreate the current Data Source.
4 Click OK and, when prompted to confirm, click Yes.
The SvcMgr dialog box notifies you when the CMS database setup is complete.
5 Click OK.
You are returned to the CCM.
6 Start the Crystal Management Server.
While it is starting, the CMS writes required system data to the newly emptied
data source. You may need to click the Refresh button in the CCM to see that
the CMS has successfully started.
To recreate the CMS database on UNIX
Use the cmsdbsetup.sh script. For reference, see “cmsdbsetup.sh” on page 438.
Selecting a new or existing CMS database
Follow this procedure if you want to disconnect a CMS from its current database
and connect it to an alternate database. When you complete these steps, none of the
data in the current database is copied into the alternate database. If the alternate
database is empty, the CCM initializes it by writing system data that is required by
Crystal Enterprise. If the alternate database already contains Crystal Enterprise
system data, the CMS uses that data when it starts.
298
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
Generally, there are only a few times when you need to complete these steps:
• If you have changed the password for the current CMS database, these steps
allow you to disconnect from, and then reconnect to, the current database.
When prompted, you can provide the CMS with the new password.
• If you want to select and initialize an empty database for Crystal Enterprise,
these steps allow you to select that new data source.
• If you have restored a CMS database from backup (using your standard
database administration tools and procedures) in a way that renders the
original database connection invalid, you will need to reconnect the CMS to
the restored database. (This might occur, for instance, if you restored the
original CMS database to a newly installed database server.)
Note: These steps are essentially the same as adding a CMS to an existing cluster;
in this case, however, there are no other CMS machines already maintaining the
database. For complete details about CMS clusters, see “Clustering Crystal
Management Servers” on page 284.
To select a new or existing database for a CMS on Windows
1 Use the CCM to stop the Crystal Management Server.
2 With the CMS selected, click Specify CMS Data Source on the toolbar.
The CMS Database Setup dialog box appears.
3 Click Select a Data Source; then click OK.
4 In the Select Database Driver dialog box, specify whether you want to connect
to the new database through ODBC, or through one of the native drivers.
5 Click OK.
6 The remaining steps depend upon the connection type you selected:
Crystal Enterprise Administrator’s Guide
299
Configuring the intelligence tier
• If you selected ODBC, the Windows “Select Data Source” dialog box appears.
Select the ODBC data source that you want to use as the CMS database; then
click OK. (Click New to configure a new DSN.) When prompted, provide
your database credentials and click OK.
• If you selected a native driver, you are prompted for your database Server
Name, your Login ID, and your Password. Provide this information and
then click OK.
The SvcMgr dialog box notifies you when the CMS database setup is complete.
7 Click OK.
8 Start the Crystal Management Server.
To select a new or existing database for a CMS on UNIX
Use the cmsdbsetup.sh script. For reference, see “cmsdbsetup.sh” on page 438.
Setting root directories and idle times of the File Repository
Servers
The Properties tabs of the Input and Output File Repository Servers enable you to
change the locations of the default root directories. These root directories contain
all of the report objects and instances on the system. You may change these settings
if you want to use different directories after installing Crystal Enterprise, or if you
upgrade to a different drive (thus rendering the old directory paths invalid).
Note:
• The Input and Output File Repository Servers must not share the same root
directory, because modifications to the files and subdirectories belonging to
one server could have adverse effects on the other server. In other words, if the
Input and Output File Repository Servers share the same root directory, then
one server might damage files belonging to the other.
• If you run multiple File Repository Servers, all Input File Repository Servers
must share the same root directory, and all Output File Repository Servers
must share the same root directory (otherwise there is a risk of having
inconsistent instances).
• It is recommended that you replicate the root directories using a RAID array or
an alternative hardware solution.
• The root directory should be on a drive that is local to the server.
You can also set the maximum idle time of each File Repository Server. This setting
limits the length of time that the server waits before it closes inactive connections.
Before you change this setting, it is important to understand that setting a value too
low can cause a user's request to be closed prematurely. Setting a value that is too
high can result the uneasier consumption of system resources such as processing
time and disk space.
300
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To modify settings for a File Repository Server
1 Go to the Servers management area of the CMC.
2 Click the link to the File Repository Server you want to change.
By default, the File Repository Servers are named Input and Output,
respectively. If you run multiple instances of each server, their names should be
prefixed with “Input.” and “Output.” as appropriate.
3 Make your changes on the Properties tab.
In this example, the Input File Repository Server is set to use D:\InputFRS\ as its
root directory. The server will remain idle for a maximum of 15 minutes.
4 Click either Apply or Update:
• Click Apply to submit changes and restart the server so that the changes
take effect immediately.
• Click Update to save the changes. You must restart the server for the
changes to take effect.
Modifying Cache Server performance settings
The Properties tab of the Cache Server allows you to set the location of the cache
files, the maximum cache size, the maximum number of simultaneous processing
threads, the number of minutes before an idle job is closed, and the number of
minutes between refreshes from the database.
The “Location of the Cache Files” setting specifies the absolute path to the directory
on the Cache Server machine where the cached report pages (.epf files) are stored.
Note: The cache directory must be on a drive that is local to the server.
The “Maximum Cache Size Allowed” setting limits the amount of hard disk space
(in KBytes) that is used to cache reports. When the Cache Server has to handle large
numbers of reports, or reports that are especially complex, a larger cache size is
needed. The default value is 5000 Kbytes, which is large enough to optimize
performance for most installations.
Crystal Enterprise Administrator’s Guide
301
Configuring the intelligence tier
The “Maximum Simultaneous Processing Threads” setting limits the number of
concurrent reporting requests that the Cache Server processes. The default value is
set to “Automatic”, and is acceptable for most, if not all, reporting scenarios. With
this setting, the Cache Server sets the maximum number of threads using the
number of processors in your system as a guide. If your Cache Server responds
slowly under high load, and resource utilization on the machine is high (that is,
either memory usage is high or CPU utilization is high, particularly in the kernel),
you may wish to decrease the number of threads to improve performance. If the
Cache Server is slow under high load but CPU utilization is low, increasing the
number of threads may improve performance. However, the ideal setting for your
reporting environment is highly dependent upon your hardware configuration,
your database software, and your reporting requirements. Thus, it is
recommended that you contact your Crystal Decisions, Inc. sales representative
and request information about the Crystal Enterprise Sizing Guide. A Crystal
Services consultant can then assess your reporting environment and assist you in
customizing these advanced configuration and performance settings.
The “Minutes Before an Idle Connection is Closed” setting alters the length of time
that the Cache Server waits for further requests from an idle connection. Before you
change this setting, it is important to understand that setting a value too low can
cause a user’s request to be closed prematurely, and setting a value that is too high
can cause requests to be queued while the server waits for idle jobs to be closed.
The “Oldest On-Demand Data Given To a Client (in minutes)” setting determines
how long cached report pages are used before new data is requested from the
database. This setting is respected for report instances with saved data, and for
report objects that do not have on-demand subreports or parameters and that do
not prompt for database logon information. Generally, the default value of 15
minutes is acceptable: as with other performance settings, the optimal value is
largely dependent upon your reporting requirements.
When enabled, the “Viewer Refresh Always Hits Database” setting ensures that,
when users explicitly refresh a report, all cached pages are ignored, and new data
is retrieved directly from the database. When disabled, this setting prevents users
from retrieving new data more frequently than is permitted by the time specified
in the “Minutes Between Refreshes from Database” setting.
To modify Cache Server performance settings
1 Go to the Servers management area of the CMC.
2 Click the link to the Cache Server whose settings you want to change.
3 Make your changes on the Properties tab.
In this example, the Cache Server retains most of the default settings, but the
“Maximum Simultaneous Processing Threads” is increased to 50.
302
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
4 Click either Apply or Update:
• Click Apply to submit changes and restart the server so that the changes
take effect immediately.
• Click Update to save the changes. You must restart the server for the
changes to take effect.
Modifying the polling time of the Event Server
The Properties tab of the Event Server allows you to change the frequency with
which the Event Server checks for file events. This “File Polling Interval in
Seconds” setting determines the number of seconds that the server waits between
polls. The minimum value is 1 (one). It is important to note that, the lower the
value, the more resources the server requires.
Tip: On Windows, you can also change this setting in the CCM. Stop the Event
Server and view its Properties. Then click the Configuration tab.
To modify the polling time
1 Go to the Servers management area of the CMC.
2 Click the link to the Event Server whose settings you want to change.
3 Make your changes on the Properties tab.
The value that you type must be 1 or greater.
4 Click Update.
5 Return to the Servers management area of the CMC and restart the server.
Crystal Enterprise Administrator’s Guide
303
Configuring the processing tier
Configuring the processing tier
This section includes technical information and procedures that show how you can
modify settings for the Crystal Enterprise servers that make up the processing tier.
The processing tier includes one or more Job Servers and one or more Page Servers.
The majority of the settings discussed here allow you to integrate Crystal
Enterprise more effectively with your current hardware, software, and network
configurations. Consequently, the settings that you choose will depend largely
upon your own requirements.
Modifying Page Server performance settings
The Properties tab of the Page Server in the Crystal Management Console lets you
set the location of temporary files, the maximum number of simultaneous report
jobs, the minutes before an idle connection is closed, the minutes before a
processing job is closed, the number of database records to read when previewing
or refreshing a report, the oldest processed data to give a client, and when to
disconnect from the report job database.
The “Location of Temp Files” setting specifies the absolute path to a directory on
the Page Server machine.This directory must have plenty of free hard disk space.
If not enough disk space is available, job processing may be slower than usual, or
job processing may fail.
The “Maximum Simultaneous Report Jobs” setting limits the number of concurrent
reporting requests that any single Page Server processes. The default value of 75 is
acceptable for most, if not all, reporting scenarios. The ideal setting for your
reporting environment, however, is highly dependent upon your hardware
configuration, your database software, and your reporting requirements. Thus, it
is difficult to discuss the recommended or optimum settings in a general way. It is
recommended that you contact your Crystal Decisions, Inc. sales representative
and request information about the Crystal Enterprise Sizing Guide. A Crystal
Services consultant can then assess your reporting environment and assist you in
customizing these advanced configuration and performance settings.
The “Minutes Before an Idle Connection is Closed” setting alters the length of time
that the Page Server waits for further requests from an idle connection. Before you
change this setting, it is important to understand that setting a value too low can
cause a user’s request to be closed prematurely. Setting a value that is too high can
cause system resources to be consumed for longer than necessary.
304
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
The “Minutes before a Report Job is Closed” setting alters the length of time that
the Page Server keeps a report job active. Before you change this setting, it is
important to understand that setting a value too low can cause a user’s request to
be closed prematurely. Setting a value that is too high can cause system resources
to be consumed for longer than necessary. (Note that this setting works in
conjunction with the “Report Job Database Connection” setting.)
The “Database records to read when previewing or refreshing a report” area
allows you to limit the number of records that the server retrieves from the
database when a user runs a query or report. This setting is useful when you want
to prevent users from running on-demand reports containing queries that return
excessively large record sets. You may prefer to schedule such reports, both to
make the reports available more quickly to users and to reduce the load on your
database from these large queries.
The “Oldest On-Demand Data Given To a Client (in minutes):” setting controls
how long the Page Server uses previously processed data to meet requests. If the
Page Server receives a request that can be met using data that was generated to
meet a previous request, and the time elapsed since that data was generated is less
than the value set here, then the Page Server will reuse this data to meet the
subsequent request. Reusing data in this way significantly improves system
performance when multiple users need the same information. When setting the
value of the “oldest processed data given to a client” consider how important it is
that your users receive up-to-date data. If it is very important that all users receive
fresh data (perhaps because important data changes very frequently) you may
need to disallow this kind of data reuse by setting the value to 0.
When enabled, the “Viewer Refresh Always Hits Database” setting ensures that,
when users explicitly refresh a report, all previously processed data is ignored, and
new data is retrieved directly from the database. When disabled, the setting
ensures that the Page Server will treat requests generated by a viewer refresh in
exactly the same way as it treats as new requests.
The “Report Job Database Connection” settings can be used to make a trade-off
between the number of database licenses you use and the performance you can
expect for certain types of reports. If you select “Disconnect when all records have
been retrieved or the job is closed”, the Page Server will automatically disconnect
from the report database as soon as it has retrieved the data it needs to fulfill a
request. Selecting this option limits the amount of time that Page Server stays
connected to your database server, and therefore limits the number of database
licenses consumed by the Page Server. However, if the Page Server needs to
reconnect to the database to generate an on-demand sub-report or to process a
group-by-on-server command for that report, performance for these reports will
be significantly slower than if you had selected “Disconnect when the job is
closed”. (The latter option ensures that Page Server stays connected to the database
server until the report job is closed. Note that you can set the “Minutes before a
Report Job is Closed” above.)
Crystal Enterprise Administrator’s Guide
305
Configuring the processing tier
To modify Page Server performance settings
1 Go to the Servers management area of the CMC.
2 Click the link to the Page Server whose settings you want to change.
3 Make your changes on the Properties tab.
In this example, the “Maximum Simultaneous Report Jobs” is increased to 75.
4 Click either Apply or Update:
• Click Apply to submit changes and restart the server so that the changes
take effect immediately.
• Click Update to save the changes. You must restart the server for the
changes to take effect.
Modifying database interaction settings for the RAS
The Database tab of the Report Application Server (RAS) in the Crystal Management
Console lets you modify the way the server runs reports against your databases.
The “Number of database records to read when previewing or refreshing a report”
area allows you to limit the number of records that the server retrieves from the
database when a user runs a query or report. This setting is particularly useful if
you provide users with ad hoc query and reporting tools, and you want to prevent
them from running queries that return excessively large record sets.
306
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
When the RAS retrieves records from the database, the query results are returned
in batches. The “Number of records per batch” setting allows you to determine the
number of records that are contained in each batch. The batch size cannot be equal
to or less than zero.
The “Number of records to browse” setting allows you to specify the number of
distinct records that will be returned from the database when browsing through a
particular field’s values. The data will be retrieved first from the client’s cache—if
it is available—and then from the server’s cache. If the data is not in either cache,
it is retrieved from the database.
The “Oldest on-demand data given to a client (in minutes)” setting controls how long
the RAS uses previously processed data to meet requests. If the RAS receives a request
that can be met using data that was generated to meet a previous request, and the time
elapsed since that data was generated is less than the value set here, then the RAS will
reuse this data to meet the subsequent request. Reusing data in this way significantly
improves system performance when multiple users need the same information.
When setting the value of the “oldest on-demand data given to a client” consider how
important it is that your users receive up-to-date data. If it is very important that all
users receive fresh data (perhaps because important data changes very frequently)
you may need to disallow this kind of data reuse by setting the value to 0. This is the
default on the RAS, to support the data needs of users performing ad hoc reporting.
The “Report Job Database Connection” settings can be used to make a trade-off
between the number of database licenses you use and the performance you can
expect for certain types of reports. If you select “Disconnect when all records have
been retrieved or the job is closed”, the Report Application Server will automatically
disconnect from the report database as soon as it has retrieved the data it needs to
fulfill a request. Selecting this option limits the amount of time that RAS stays
connected to your database server, and therefore limits the number of database
licenses consumed by the RAS. However, if the RAS needs to reconnect to the
database to generate an on-demand sub-report or to process a group-by-on-server
command for that report, performance for these reports will be significantly slower
than if you had selected “Disconnect when the job is closed”. (The latter option
ensures that RAS stays connected to the database server until the report job is closed.)
Tip: On Windows, you can also change these settings in the CCM. Stop the RAS
and view its Properties. Click the Parameters tab. From the Option Type list, select
Database.
To modify database interaction settings for the RAS
1 Go to the Servers management area of the CMC.
2 Click the link to the RAS whose settings you want to change.
3 Make your changes on the Database tab.
4 Click Apply to submit changes and restart the server so that the changes take
effect immediately.
Crystal Enterprise Administrator’s Guide
307
Configuring the processing tier
Modifying performance settings for the RAS
The Server tab of the Report Application Server (RAS) in the Crystal Management
Console allows you to modify the number of minutes before an idle connection is
closed, and the maximum number of simultaneous processing threads.
The “Minutes Before an Idle Connection is Closed” setting alters the length of time
that the RAS waits for further requests from an idle connection. Before you change
this setting, it is important to understand that setting a value too low can cause a
user’s request to be closed prematurely, and setting a value that is too high can
affect the server’s scalability (for instance, if the ReportClientDocument object is not
closed explicitly, the server will be waiting unnecessarily for an idle job to close).
The “Maximum Simultaneous Report Jobs” setting limits the number of
concurrent reporting requests that a RAS processes. The default value is acceptable
for most, if not all, reporting scenarios. The ideal setting for your reporting
environment, however, is highly dependent upon your hardware configuration,
your database software, and your reporting requirements. Thus, it is difficult to
discuss the recommended or optimum settings in a general way. It is
recommended that you contact your Crystal Decisions, Inc. sales representative
and request information about the Crystal Enterprise Sizing Guide. A Crystal
Services consultant can then assess your reporting environment and assist you in
customizing these advanced configuration and performance settings.
Tip: On Windows, you can also change these settings in the CCM. Stop the RAS
and view its Properties. Click the Parameters tab. From the Option Type list, select
Server.
To modify performance settings for the RAS
1 Go to the Servers management area of the CMC.
2 Click the link to the RAS whose settings you want to change.
3 Make your changes on the Server tab.
4 Click Apply to submit changes and restart the server so that the changes take
effect immediately.
Modifying performance settings for Job Servers
By default, the Job Server runs jobs as independent processes rather than as
threads. This method allows for more efficient processing of large, complex
reports. The “Maximum Jobs Allowed” setting limits the number of concurrent
independent processes (child processes) that the Job Server allows—that is, it limits
the number of scheduled reports that the Job Server will process at any one time.
You can tailor the maximum number of jobs to suit your reporting environment.
The default “Maximum Jobs Allowed” setting is acceptable for most, if not all,
reporting scenarios. The ideal setting for your reporting environment, however, is
308
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
highly dependent upon your hardware configuration, your database software, and
your reporting requirements. Thus, it is difficult to discuss the recommended or
optimum settings in a general way. It is recommended that you contact your
Crystal Decisions, Inc. sales representative and request information about the
Crystal Enterprise Sizing Guide. A Crystal Services consultant can then assess your
reporting environment and assist you in customizing these advanced configuration
and performance settings
You can also change the default directory where the Job Server stores its temporary
files.
To modify performance settings for Job Servers
1 Go to the Servers management area of the CMC.
2 Click the link to the Job Server whose settings you want to change.
3 Make your changes on the Properties tab.
4 Click Update.
5 Return to the Servers management area of the CMC and restart the Job Server.
Setting default scheduling destinations for Job Servers
By default, when users schedule objects, the instances are saved to the Output File
Repository Server. However, Crystal Enterprise also allows users to specify other
output destinations for scheduled objects. The supported output destinations are
unmanaged disk, FTP, and email (Simple Mail Transfer Protocol, or SMTP). This
section shows how to set up destination support on the Report Job Servers and
Program Job Servers. You must perform these tasks in order to enable the
“schedule to destinations” features offered by Crystal Enterprise.
For complete information about scheduling objects to particular destinations, see
“Selecting a destination” on page 237.
Setting the default disk destination
1 Go to the Servers management area of the CMC.
2 Click the link to the Report or Program Job Server whose settings you want to
change.
3 On the Destinations tab, click the Crystal Enterprise.DiskUnmanaged link.
4 On the Properties tab, set the default values to be used at schedule time:
• Destination Directory
Type the absolute path to the directory. The directory can be on a local
drive of the Job Server machine, or on any other machine that you can
specify with a UNC path.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file name.
Crystal Enterprise Administrator’s Guide
309
Configuring the processing tier
• Specified File Name
Select this option if you want to specify a file name—you can also add a variable
to the file name. To add a variable, choose a placeholder for a variable property
from the list and click Add. When each instance runs, the variable is replaced
with the appropriate information. For example, when you add the variable
“Owner,” the file name of each object includes the object owner’s name.
• User Name
Specify a user who has permission to write files to the destination directory.
• Password
Type the password for the user.
In this example, the destination directory is on a network drive that is accessible
to the Report Job Server machine through a UNC path. Each file name will be
randomly generated, and a user name and password have been specified to
grant the Report Job Server permission to write files to the remote directory.
5 Click Update.
6 Return to the server’s Destinations tab, select the check box that corresponds
to your newly defined destination, and click Enable.
Setting the default FTP destination
1 Go to the Servers management area of the CMC.
2 Click the link to the Job Server whose settings you want to change.
3 On the Destinations tab, click the Crystal Enterprise.Ftp link.
4 On the Properties tab, set the default values to be used at schedule time:
• Host
Enter your FTP host information.
310
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• Port
Enter the FTP port number (the standard FTP port is 21).
• FTP User Name
Specify a user who has the necessary rights to upload a report to the FTP
server.
• FTP Password
Enter the user’s password.
• Account
Enter the FTP account information, if required.
Account is part of the standard FTP protocol, but it is rarely implemented.
Provide the appropriate account only if your FTP server requires it.
• Destination Directory
Enter the FTP directory that you want the object to be saved to. A relative
path is interpreted relative to the root directory on the FTP server.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file
name.
• Specified File Name
Select this option if you want to enter a file name—you can also add a
variable to the file name. To add a variable, choose a placeholder for a
variable property from the list and click Add.
In this example, all of the required FTP information is provided. Reports
scheduled to this destination are randomly named and uploaded to the
ftp.crystaldecisions.com site.
Crystal Enterprise Administrator’s Guide
311
Configuring the processing tier
5 Click Update.
6 Return to the server’s Destinations tab, select the check box that corresponds
to your newly defined destination, and click Enable.
Setting the default email (SMTP) destination
1 Go to the Servers management area of the CMC.
2 Click the link to the Job Server whose settings you want to change.
3 On the Destinations tab, click the Crystal Enterprise.Smtp link.
4 On the Properties tab, complete these required fields with the information that
corresponds to your SMTP server:
• Domain Name
Enter the fully qualified domain of the SMTP server.
• Server Name
Enter the name of the SMTP server.
• Port
Enter the port that the SMTP server is listening on. (This standard SMTP
port is 25.)
• Authentication
Select Plain or Login if the Job Server must be authenticated using one of
these methods in order to send email.
• SMTP User Name
Provide the Job Server with a user name that has permission to send email
and attachments through the SMTP server.
• SMTP Password
Provide the Job Server with the password for the SMTP server.
• From
Provide the return email address.
In this example, the SMTP server resides in the crystaldecisions.com domain.
Its name is EMAIL_SERV and it is listening on the standard SMTP port. Plain text
authentication is being used, and an account called CrystalJobAccount has been
created on the SMTP server for use by the Report Job Server.
312
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
5 Complete the optional email fields (To, Cc, Subject, and Message) if you want
to set default values for users who schedule reports to this SMTP destination.
Users can override these defaults with their own values when they schedule
reports to this SMTP destination.
6 Use these optional fields to specify whether you want the email to include a
hyperlink to the report, an attached report instance, or both. (If you send a
hyperlink, the email recipient must log on to Crystal Enterprise to see the report.)
Again, users can override these settings with their own values.
• Add viewer hyperlink to message body
Click Add if you want to add the URL for the viewer in which you want the
email recipient to view the report. You can set the default URL by clicking
Object Settings on the main page of the Objects management area of the CMC.
• Attach report instance to email message
Clear this check box if you do not want a copy of the report instance
attached to the email (for a Report Job Server). For a Program Job Server,
clear this check box if you do not want a copy of the program instance (a
text file containing the standard out and standard error from the program)
attached to the email.
• Default File Name (randomly generated)
Select this option if you want Crystal Enterprise to generate a random file name.
• Specified File Name
Select this option if you want to enter a file name—you can also add a
variable to the file name. To add a variable, choose a placeholder for a
variable property from the list and click Add.
7 Click Update.
8 Return to the server’s Destinations tab, select the check box that corresponds
to your newly defined destination, and click Enable.
Configuring Windows processing servers for your data source
When started on Windows, the report processing servers—Report Job Servers,
Program Job Servers, Page Servers, and Report Application Servers—by default log
on to the local system as services with the Windows NT/2000 “LocalSystem”
account. This account determines the permissions that each service is granted on
the local machine. This account does not grant the service any network permissions.
In the majority of cases, this account is irrelevant in relation to the server’s task of
processing reports against your data source. (The database logon credentials are
stored with the report object.) Thus, you can usually leave each server’s default
logon account unchanged or, if you prefer, you can change it to a Windows user
account with the appropriate permissions.
However, there are certain cases when you must change the logon account used by
the processing servers. These cases arise either because the server needs additional
Crystal Enterprise Administrator’s Guide
313
Configuring the processing tier
network permissions to access the database, or because the database client
software is configured for a particular Windows user account. This table lists the
various database/ driver combinations and shows when you must complete
additional configuration.
Tip: If your reports require ODBC connections, set up identical System Data Source
Names (DSNs) on each machine that is running a processing server. Ensure that
each of these DSNs matches the DSN that was used when the report was designed.
Database
Driver
Additional Configuration Required
Oracle™
Native
None
ODBC (CROR8)
OLE DB
Sybase™
Native
None
ODBC (CRSYB)
Lotus
Domino®
Native
None
Microsoft®
Native
SQL Server™ ODBC (CRSS)
OLE DB
If you use SQL Server’s “Trusted Connection” setting, change
each server’s log on account to a Windows user account that has
permissions within the database. (In this case, the database logon
credentials stored with the report object should be blank.)
DB2™
Native
None
DB2
ODBC (CRDB2) For on-demand viewing, configure the Page Server and RAS to
close idle jobs after one minute, thereby allowing other users to
access the database. For details, see “Modifying Page Server
performance settings” on page 304.
Tip: IBM offers several client applications for connecting to DB2.
The recommended client is IBM DB2 Direct Connect, whose ODBC
drivers were written for actual programmatic interaction with
products like Crystal Enterprise. See the Crystal Care Knowledge
Base for discussions of this and other DB2 clients.
Informix®
Native
• Change the log on account for each processing server to the
account under which the Informix client was installed.
• Add the Informix bin directory to the System Path (for
example, C:\Informix\bin) environment variable.
Informix
ODBC
(CRINF9)
• Change the log on account for each processing server to the
Windows user account under which the Informix client was installed.
• For on-demand viewing, configure the Page Server and RAS to
close idle jobs after one minute, thereby allowing other users to
access the database. For details, see “Modifying Page Server
performance settings” on page 304.
Microsoft
Exchange™
314
• Ensure that the Exchange profile is set up on the local machine.
• Change the log on account of each processing server to the
Windows user account that has access to the mailbox in which the
report data is located.
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
Database
Driver
PC databases Native, ODBC
(Btrieve™,
Microsoft
Access™,
Paradox™,
XML)
Additional Configuration Required
• If the database is installed on the server’s local machine, no
additional configuration is required.
• If the processing server must access the database over the
network, change the server’s log on account to a Windows domain
user account that has the appropriate network permissions.
Ensure that the account has READ access to the shared resource.
Tip: Running a service under an Administrator account does not inadvertently grant
administrative privileges to another user, because users cannot impersonate services.
For details on changing the user account for the Job Server or Page Server, see
“Changing the server user account” on page 326.
Configuring UNIX processing servers for your data source
The Job Servers and Page Server support native and ODBC connections to a
number of reporting databases. This section discusses the environment variables,
software, and configuration files that must be available to the servers in order for
them to process reports successfully. Whether your reports use native or ODBC
drivers, ensure that the reporting environment configured on the server accurately
reflects the reporting environment configured on the Windows machine that you
use when designing reports with Crystal Reports.
See the Platforms.txt file included with your product distribution for a complete
list of tested database software and version requirements.
Native drivers
If you design reports using native drivers, you must install the appropriate database
client software on each Job Server and/or Page Server machine that will process the
reports. The server loads the client software at runtime in order to access the database
that is specified in the report. The server locates the client software by searching the
library path environment variable that corresponds to your operating system
(LD_LIBRARY_PATH on Sun Solaris, LIBPATH on IBM AIX, and so on), so this variable
must be defined for the login environment of each Job Server and Page Server.
Depending on your database, additional environment variables may be required
for the Job Server and Page Server to use the client software. These include:
• Oracle
The ORACLE_HOME environment variable must define the top-level directory of
the Oracle client installation.
• Sybase
The SYBASE environment variable must define the top-level directory of the
Sybase client installation. The SYBPLATFORM environment variable must define
the platform architecture.
Crystal Enterprise Administrator’s Guide
315
Configuring the processing tier
• DB2
The DB2INSTANCE environment variable must define the DB2 instance that is
used for database access. Use the DB2 instance initialization script to ensure
that the DB2 environment is correct.
Note: For complete details regarding these and other required environment
variables, see the documentation included with your database client software.
As an example, suppose that you are running reports against both Sybase and Oracle.
The Sybase database client is installed in /opt/sybase, and the Oracle client is installed
in /opt/oracle/app/oracle/product/8.1.7. You installed Crystal Enterprise under the
crystal user account (as recommended in the Crystal Enterprise Installation Guide).
If the crystal user’s default shell is a C shell, add these commands to the crystal
user’s login script:
setenv LD_LIBRARY_PATH /opt/oracle/app/oracle/product/8.1.7/lib:opt/sybase/
lib:$LD_LIBRARY_PATH
setenv ORACLE_HOME /opt/oracle/app/oracle/product/8.1.7
setenv SYBASE /opt/sybase
setenv SYBPLATFORM sun_svr4
If the crystal user’s default shell is a Bourne shell, modify the syntax accordingly:
LD_LIBRARY_PATH=/opt/oracle/app/oracle/product/8.1.7/lib:opt/sybase/
lib:$LD_LIBRARY_PATH;export LD_LIBRARY_PATH
ORACLE_HOME=/opt/oracle/app/oracle/product/8.1.7;export ORACLE_HOME
SYBASE=/opt/sybase;export SYBASE
SYBPLATFORM=sun_svr4;export SYBPLATFORM
ODBC drivers
If you design reports off ODBC data sources (on Windows), you must set up the
corresponding data sources on the Job Server and Page Server machines. In
addition, you must ensure that each server is set up properly for ODBC. During
the installation, Crystal Enterprise installs ODBC drivers for UNIX, creates
configuration files and templates related to ODBC reporting, and sets up the
required ODBC environment variables. This section discusses the installed
environment, along with the information that you need to edit.
Note:
• Detailed documentation covering the various ODBC drivers is included in the
Merant Connect ODBC Reference (odbcref.pdf). This is installed below the
crystal/enterprise/platform/odbc directory; it is also located in the doc
directory of your product distribution.
• If you report off DB2 using ODBC, your database administrator must first bind
the UNIX version of the driver to every database that you report against (and not
just each database server). The bind packages are installed below the crystal/
enterprise/platform/odbc/lib directory; their filenames are iscsso.bnd,
iscswhso.bnd, isrrso.bnd, isrrwhso.bnd, isurso.bnd, and isurwhso.bnd. Because
Crystal Reports runs on Windows, ensure also that the Windows version of the
driver has been bound to each database.
316
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• On UNIX, Crystal Enterprise does not include the Informix client-dependent
ODBC driver (CRinf16) that is installed on Windows. The UNIX version does,
however, include the clientless ODBC driver for Informix connectivity.
ODBC environment variables
The environment variables related to ODBC reporting are: the library path that
corresponds to your operating system (LD_LIBRARY_PATH on Sun Solaris, LIBPATH on
IBM AIX, and so on), ODBC_HOME, and ODBCINI. The Crystal Enterprise installation
includes a file called env.csh that is sourced automatically every time you start the
Crystal Enterprise servers with the CCM. Thus, the environment for the Job Server
and Page Server is set up automatically:
• The INSTALL_ROOT/crystal/enterprise/platform/odbc/lib directory of your
installation is added to the library path environment variable.
• The ODBC_HOME environment variable is set to the INSTALL_ROOT/crystal/
enterprise/platform/odbc directory of your installation.
• The ODBCINI environment variable is defined as the path to the .odbc.ini file
that was created by the Crystal Enterprise installation.
Modify the environment variables in the env.csh script only if you have
customized your configuration of ODBC. The main ODBC configuration file that
you need to modify is the system information file.
Working with the ODBC system information file
The system information file (.odbc.ini) is created in the HOME directory of the user
account under which you installed Crystal Enterprise (typically the crystal user
account). In this file, you define each of the ODBC data sources (DSNs) that the Job
Server and Page Server need in order to process your reports. The Crystal
Enterprise installation completes most of the required information—such as the
location of the ODBC directory and the name and location of each installed ODBC
driver—and shows where you need to provide additional information.
Tip: A template of the system information file is installed to INSTALL_ROOT/
crystal/defaultodbc.ini
The following example shows the contents of a system information file that defines a
single ODBC DSN for servers running on UNIX. This DSN allows the Job Server and
Page Server to process reports based on a System DSN (on Windows) called CRDB2:
[ODBC Data Sources]
CRDB2=MERANT 3.70 DB2 ODBC Driver
[CRDB2]
Driver=/opt/crystal/enterprise/platform/odbc/lib/crdb216.so
Description=MERANT 3.70 DB2 ODBC Driver
Database=myDB2server
LogonID=username
Crystal Enterprise Administrator’s Guide
317
Configuring the processing tier
[ODBC]
Trace=0
TraceFile=odbctrace.out
TraceDll=/opt/crystal/enterprise/platform/odbc/lib/odbctrac.so
InstallDir=/opt/crystal/enterprise/platform/odbc
As shown in the example above, the system information file is structured in three
major sections:
• The first section, denoted by [ODBC Data Sources], lists all the DSNs that are
defined later in the file. Each entry in this section is provided as dsn=driver,
and there must be one entry for every DSN that is defined in the file. The value
of dsn must correspond exactly to the name of the System DSN (on Windows)
that the report was based off.
• The second section sequentially defines each DSN that is listed in the first
section. The beginning of each definition is denoted by [dsn]. In the example
above, [CRDB2] marks the beginning of the single DSN that is defined in the file.
Each DSN is defined through a number of option=value pairs. The options that
you must define depend upon the ODBC driver that you are using. These pairs
essentially correspond to the Name=Data pairs that Windows stores for each
System DSN in the registry:
\\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\odbc.ini\dsn
However, the options for a particular ODBC driver on UNIX may not
correspond by name to the options available for a Windows version of the same
driver. For example, some Windows drivers store a UID value in the registry,
and on UNIX you may need to specify this value with the LogonID option.
Note: For detailed documentation on each ODBC driver, see the Merant
Connect ODBC Reference (odbcref.pdf). The PDF is installed below the crystal/
enterprise/platform/odbc directory; it is also located in the doc directory of
your product distribution.
• The final section of the file, denoted by [ODBC], includes ODBC tracing
information. You need not modify this section.
When the installation creates the system information file, it completes some fields
and sets up a number of default DSNs—one for each of the installed ODBC drivers.
The standard options that are commonly required for each driver are included in
the file (Database=, LogonID=, and so on). Edit the file and provide the
corresponding values that are specific to your reporting environment.
This example shows the entire contents of a system information file created when
Crystal Enterprise was installed to the /usr/local directory.
[ODBC Data Sources]
CRDB2=MERANT 3.70 DB2 ODBC Driver
CRINF_CL=MERANT 3.70 Informix Dynamic Server ODBC Driver
CROR8=MERANT 3.70 Oracle8 ODBC Driver
CRSS=MERANT 3.70 SQL Server ODBC Driver
CRSYB=MERANT 3.70 Sybase ASE ODBC Driver
CRTXT=MERANT 3.70 Text ODBC Driver
318
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
[CRDB2]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/crdb216.so
Description=MERANT 3.70 DB2 ODBC Driver
Database=
LogonID=
[CRINF_CL]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/crifcl16.so
Description=MERANT 3.70 Informix Dynamic Server ODBC Driver
ServerName=
HostName=
PortNumber=
Database=
LogonID=
[CROR8]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/cror816.so
Description=MERANT 3.70 Oracle8 ODBC Driver
ServerName=
ProcedureRetResults=1
LogonID=
[CRSS]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/crmsss16.so
Description=MERANT 3.70 SQL Server ODBC Driver
Address=
Database=
QuotedId=Yes
LogonID=
[CRSYB]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/crase16.so
Description=MERANT 3.70 Sybase ASE ODBC Driver
NetworkAddress=
Database=
LogonID=
[CRTXT]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/crtxt16.so
Description=MERANT 3.70 Text ODBC Driver
Database=
[ODBC]
Trace=0
TraceFile=odbctrace.out
TraceDll=/usr/local/crystal/enterprise/platform/odbc/lib/odbctrac.so
InstallDir=/usr/local/crystal/enterprise/platform/odbc
Crystal Enterprise Administrator’s Guide
319
Logging server activity
Adding a DSN to the default ODBC system information file
When you need to add a new DSN to the installed system information file
(.odbc.ini) file, first add the new DSN to the bottom of the [ODBC Data Sources]
list. Then add the corresponding [dsn] definition just before the [ODBC] section.
For example, suppose that you have a Crystal report that uses ODBC drivers to
report off your Oracle8 database. The report is based off a System DSN (on
Windows) called SalesDB. To create the corresponding DSN, first append this line
to the [ODBC Data Sources] section of the system information file:
SalesDB=MERANT 3.70 Oracle8 ODBC Driver
Then define the new DSN by adding the following lines just before the system
information file’s [ODBC] section:
[SalesDB]
Driver=/usr/local/crystal/enterprise/platform/odbc/lib/cror816.so
Description=MERANT 3.70 Oracle8 ODBC Driver
ServerName=MyServer
ProcedureRetResults=1
LogonID=MyUserName
Once you have added this information, the new DSN is available to the Job Server
and Page Server, so they can process reports that are based off the SalesDB System
DSN (on Windows).
Logging server activity
Crystal Enterprise allows you to log specific information about Crystal Enterprise
web activity. For details on locating and customizing the web activity logs, see
“Configuring properties for the Web Component Server” on page 279.
In addition, each of the Crystal Enterprise servers is designed to log messages to
your operating system’s standard system log.
• On Windows NT/2000, Crystal Enterprise logs to the Event Log service. You
can view the results with the Event Viewer (in the Application Log).
• On UNIX, Crystal Enterprise logs to the syslog daemon as a User application.
Each server prepends its name and PID to any messages that it logs.
This example shows two messages logged to the syslog daemon on UNIX:
320
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
Each server also logs assert messages to the logging directory of your product
installation. The programmatic information logged to these files is typically useful
only to Crystal Decisions support staff for advanced debugging purposes. The
location of these log files depends upon your operating system:
• On Windows, the default logging directory is C:\Program Files\Crystal
Decisions\Logging
• On UNIX, the default logging directory INSTALL_ROOT/crystal/logging
directory of your installation.
The important point to note is that these log files are cleaned up automatically, so
there will never be more than approximately 1 MB of logged data per server.
Advanced server configuration options
This section includes additional configuration tasks that you may want to perform,
depending upon your reporting environment.
Changing the default server port numbers
During installation, the CMS and the WCS are set up to use default port numbers.
The default CMS port number is 6400, and the default WCS port number is 6401.
These ports fall within the range of ports reserved by Crystal Decisions, Inc. (6400
to 6410). Thus, Crystal Enterprise communication on these ports should not
conflict with third-party applications that you have in place. (Although unlikely, it
is possible that your custom applications use these ports. If so, you can change the
default CMS and WCS ports.)
The Web Component Adapter (which replaces the WCS on UNIX, and on
Windows installations of Crystal Enterprise that use the Java SDK) is not a server.
However, you can configure its listening port by changing the
connection.listeningPort context parameter in web.xml. (See “Configuring the
Web Component Adapter” on page 282 for details.)
When started and enabled, each of the other Crystal Enterprise servers
dynamically binds to an available port (higher than 1024), registers with this port
on the CMS, and then listens for Crystal Enterprise requests. If necessary, you can
instruct each server component to listen on a specific port (rather than dynamically
selecting any available port). Also, when the WCS receives a request from the Web
Connector (on port 6401, by default), the WCS dynamically selects a second port
for all subsequent communication. You will likely need to specify this second WCS
port explicitly (with -requestPort) if you are working with firewalls. (For more
information on working with firewalls see “Working with Firewalls” on page 367.)
On Windows, you view and modify server command lines with the CCM. The
Command field appears on each server’s Properties tab. On UNIX, you view and
modify server command lines (also referred to as launch strings) in the ccm.config
file, which is installed in the crystal directory.
Crystal Enterprise Administrator’s Guide
321
Advanced server configuration options
This table summarizes the command-line options as they relate to port usage for
specific server types. (See “Server Command Lines” on page 425 for additional
usage details.)
Option
CMS
WCS
Other Servers
-port
Specifies the primary
Crystal Enterprise port on
which the CMS listens for
requests from all other
servers. The default is
6400.
Specifies the port on which
the WCS listens for web
requests from the Web
Connector. The default is
6401.
Used only in multihomed
environments or for certain
NAT firewall environments.
In both cases, specify -port
interface only. (-port
number has no meaning for
these servers).
-requestPort
Specifies the secondary
port that the CMS uses for
identifying other servers
and for registering with
itself and/or a cluster.
Selected dynamically if
unspecified.
Specifies the port on which
the WCS listens for replies
from the CMS and the
other servers. The WCS
registers this port with the
CMS. Selected dynamically
if unspecified.
Specifies the port on which
the server listens for
Crystal Enterprise
requests. The server
registers this port with the
CMS. Selected dynamically
if unspecified.
-ns
n/a
Specifies the CMS that the
WCS will register with.
Specifies the CMS that the
server will register with.
Before modifying any port numbers, consider the following:
• If you change the default CMS port number, you must change the -ns option in
every other server’s command line, to ensure that each server connects to the
appropriate port of the CMS. (The -ns option stands for “nameserver.” The CMS
functions as the nameserver in Crystal Enterprise, because it maintains a list that
includes the host name and port number of each server that is started, enabled,
and thus available to accept Crystal Enterprise requests.) If you are using the
WCA (as you will if you have a UNIX installation of Crystal Enterprise, or a
Windows installation that uses the Java SDK), you must also set the name and
port number of the CMS with the connection.cms context parameter in web.xml.
See “Configuring the Web Component Adapter” on page 282 for details.
• If you change the default WCS port number, you must make corresponding
changes to the mapping that allows the Web Connector to communicate with
the WCS. For information about configuring your Web Connector and any of
your web server configuration files, see Crystal Enterprise Installation Guide.
• If you are working with multihomed machines or in certain NAT firewall
configurations, you may wish to specify -port interface:number for the WCS
or CMS and -port interface for the other servers. For details, see
“Configuring Crystal Enterprise on a multihomed machine” on page 324 or
“Configuring for Network Address Translation” on page 375.
• On Windows, the CCM displays default port numbers on each server’s
Configuration tab. This displayed port corresponds to the -port option. For
server’s other than the CMS and the WCS, this default port is not actually in
use (each server registers its -requestPort number with the CMS instead).
322
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To change the default CMS port for Crystal Enterprise servers
1 Use the CCM (on Windows) or ccm.sh (on UNIX) to stop all the Crystal
Enterprise servers.
2 Add (or modify) the following option in the CMS command line:
-port number
Replace number with the port that you want the CMS to listen on. (The default
port is 6400.)
3 Add (or modify) the following option in the command line of all of the
remaining non-CMS Crystal Enterprise servers:
-ns hostname:number
Replace hostname with the host name of the machine that is running the CMS.
The host name must resolve to a valid IP address within your network. Replace
number with the port that the CMS is listening on.
4 Start and enable all the Crystal Enterprise servers.
The CMS begins listening on the port specified by number, and the non-CMS
servers broadcast to that port when attempting to register with the CMS.
If you are using the WCA (as you will if you have a UNIX installation of Crystal
Enterprise, or a Windows installation that uses the Java SDK), you must also set the
name and port number of the CMS with the connection.cms context parameter in
web.xml. See “Configuring the Web Component Adapter” on page 282 for details.
To change the default WCS port
1 Use the CCM to stop all the Crystal Enterprise servers.
2 Add (or modify) the following option in the WCS command line:
-port number
Replace number with the port that you want the WCS to listen on. (The default
port is 6401.)
3 Reconfigure the Web Connector so that it forwards Crystal Enterprise requests
to the WCS host on the new port specified by number.
For details, see Crystal Enterprise Installation Guide.
To change the port a server registers with the CMS
1 Use the CCM (on Windows) or ccm.sh (on UNIX) to stop the server.
2 Add (or modify) the following option in the server’s command line:
-requestPort number
Replace number with the port that you want the server to listen on.
3 Start and enable the server.
The server binds to the new port specified by number. It then registers with the CMS
and begins listening for Crystal Enterprise requests on the new port.
Crystal Enterprise Administrator’s Guide
323
Advanced server configuration options
By default, each server registers itself with the CMS by IP address, rather than by
name. This typically provides the most reliable behavior. If you need each server
to register with the CMS by fully qualified domain name instead, use the
-requestPort option in conjunction with -port interface (where interface is the
server’s fully qualified domain name). Having the servers register by name can be
useful if a NAT firewall resides between the server and the CMS. For more
information, see “Configuring for Network Address Translation” on page 375.
You may also need to specify -port interface when Crystal Enterprise is running
on a multihomed machine.
Configuring Crystal Enterprise on a multihomed machine
A multihomed machine is one that has multiple network addresses. You may
accomplish this with multiple network interfaces, each with one or more IP addresses,
or with a single network interface that has been assigned multiple IP addresses.
If you have multiple interface cards, each with a single IP address, change the
binding order so that the card at the top of the binding order is the one you want
the Crystal Enterprise servers to bind to. If your interface card has multiple IP
addresses, use the -port command-line option to specify a IP address for the
Crystal Enterprise server.
Tip: This section shows how to restrict all servers to the same network address, but
it is possible to bind individual servers to different addresses. For instance, you might
want to bind the File Repository Servers to a private address that is not routable from
users’ machines. Advanced configurations such as this require your DNS
configuration to route communications effectively between all the Crystal Enterprise
server components. In this example, the DNS must route communications from the
other Crystal Enterprise servers to the private address of the File Repository Servers.
Configuring the CMS and WCS to bind to a network address
When you use the -port command-line option to configure the CMS and the WCS
to bind to a specific IP address, you must also include the port number these
servers use (even if the server is using the default port). Add the following option
to both of their command lines:
-port interface:port
If the machine has multiple network interfaces, interface can be the fully qualified
domain name or the IP address of the interface that you want the server to bind to.
If the machine has a single network interface, interface must be the IP address
that you want the server to bind to.
Note:
• To retain the default port numbers, replace port with 6400 for the CMS, and
with 6401 for the WCS. If you change the default port numbers, you will need
to make additional configuration changes. For details, see “Changing the
default server port numbers” on page 321.
324
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
• To configure the WCA, use interface:port when setting the
connection.listeningPort context parameter in web.xml. (See “Configuring
the Web Component Adapter” on page 282 for details.)
Configuring the remaining servers to bind to a network
address
The remaining Crystal Enterprise servers select their ports dynamically by default,
so you need only add the following option to their command lines:
-port interface
Replace interface with the same value that you specified for the CMS and the
WCS. Ensure that each server’s -ns parameter points to the CMS, and that the DNS
resolves the value to the appropriate network address.
Adding and removing Windows server dependencies
When installed on Windows, each server in Crystal Enterprise is dependent on at
least three services: the Event Log, NT LM Security Support Provider, and Remote
Procedure Call (RPC) services. If you are having problems with a server, check to
ensure that all three services appear on the server’s Dependency tab.
To add and remove server dependencies
1 Use the CCM to stop the server whose dependencies you want to modify.
2 With the server selected, click Properties on the toolbar.
3 Click the Dependency tab.
As shown here, at least three services should be listed: Event Log, NT LM
Security Support Provider, and Remote Procedure Call (RPC).
Crystal Enterprise Administrator’s Guide
325
Advanced server configuration options
4 To add a dependency to the list, click Add.
The Add Dependency dialog box provides you with a list of all available
dependencies. Select the dependency or dependencies, as required, and then
click Add.
5 To remove a dependency from the list, select it and click Remove.
6 Click OK.
7 Restart the server.
Changing the server startup type
When installed on Windows, each server is configured to start automatically. As
with other Windows services, there are three startup types:
• Automatic starts the server each time the machine is started.
• Manual requires you to start the server before it will run.
• Disabled requires you to change the startup type to automatic or manual
before it can run.
To change the server startup type on Windows
1 Start the CCM.
2 Stop the server whose startup type you want to modify.
3 With the server selected, click Properties on the toolbar.
4 Click the Startup Type list and select Automatic, Disabled, or Manual.
5 Click OK.
6 Restart the server.
To change the server startup type on UNIX
On UNIX, this requires root privileges. See “setupinit.sh” on page 444.
Changing the server user account
If the incorrect user account is running on a server on Windows, change it in the
Crystal Configuration Manager (CCM).
Tip: The Program Job Server must be configured to use the Local System account,
or a user account that has the right “Act as part of the operating system”. (To set
this right for a user in Windows 2000, go to Start>Programs>Administrative
Tools>Local Security Policy>Local Policies> User Rights Assignment).
326
Crystal Enterprise Administrator’s Guide
15: Managing and Configuring Servers
To change a server’s user account
1 Use the CCM to stop the server.
2 Click Properties.
3 Clear the System Account check box.
4 Enter the Windows NT/2000 user name and password information.
When started, the server process will log on to the local machine with this user
account. In addition, all reports processed by this server will be formatted using
the printer settings associated with the user account that you enter.
5 Click Apply, and then click OK.
6 Start the server.
Crystal Enterprise Administrator’s Guide
327
Advanced server configuration options
328
Crystal Enterprise Administrator’s Guide
Managing Auditing
16
This chapter provides an overview of the auditing
functionality in Crystal Enterprise. It also describes how to
configure the auditing database, how to select actions to
audit, and how to create a custom audit report.
Crystal Enterprise Administrator’s Guide
329
Auditing overview
Auditing overview
Auditing allows you to monitor and record key facts about your Crystal Enterprise
system. Having information about who is using your system and which objects
they are accessing allows you to answer system-level questions like “which groups
within the company use our Crystal Enterprise system the most?” or “how many
concurrent user licenses are we using at any given time?”. Auditing also allows
you to better administer individual user accounts and reports by giving you more
insight into what actions users are taking and which reports they are accessing.
This information lets you be more proactive in managing the operation and
deployment of your Crystal Enterprise system, while helping you better evaluate
the value that Crystal Enterprise provides to your organization.
How does auditing work?
The Crystal Management Server (CMS) acts as the system auditor, while each
Crystal Enterprise server that controls actions that you can monitor is an auditee.
To audit an action in Crystal Enterprise, you must first determine which server
controls that action. Then you must enable auditing of that action in the Servers
management area of the Crystal Management Console. As the auditee, the Crystal
Enterprise server will then begin to record these audit actions in a local log file.
As the auditor, the CMS controls the overall audit process. Each server writes audit
records to a log file local to the server. At regular intervals the CMS communicates
with the auditee servers to request copies of records from the auditee’s local log
files. When the CMS receives these records it writes data from the log files to the
central auditing database.
The CMS also controls the synchronization of audit actions that occur on different
machines. Each auditee provides a time stamp for the audit actions that it records in
its log file. To ensure that the time stamps of actions on different servers are consistent,
the CMS periodically broadcasts its system time to the auditees. The auditees then
compare this time to their internal clocks. If differences exist, they make a correction
to the time stamp they record in their log files for subsequent audit actions.
Once the data is in the auditing database you can run pre-configured reports
against the database or design custom reports to suit your own needs.
330
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
Note:
• You must configure the auditing database on the CMS before you can begin to
audit. See “Configuring the auditing database” on page 334.
• The CMS acts as both an auditor and as an auditee when you configure it to
audit an action that the CMS itself controls.
• In a CMS cluster, the cluster will nominate one CMS to act as system auditor. If
the machine that is running this CMS fails, another CMS from the cluster will
take over and begin acting as auditor.
Which actions can I audit?
You can use auditing to track the actions of individual users of Crystal Enterprise
as they log in and out of the system, access data, or create file-based events. You
can also monitor system actions like the success or failure of scheduled objects.
(For a complete list of auditable actions, see “Reference list of auditable actions” on
page 331).
For each action, Crystal Enterprise records the time of the action, the name and
user group of the user who initiated the action, the server where it was performed,
and a variety of other parameters more fully documented in “Auditing database
schema reference” on page 341.
Once you have collected this data, you can use a custom or pre-configured report
to view the raw data, or to answer more complex queries such as “how many
concurrent licenses are we using at a given time?”. See “Reporting on audit
results” on page 339 for more information.
Reference list of auditable actions
This list contains a complete list of the audit actions you can enable in Crystal
Enterprise. It is organized according to the types of actions that you can audit, to
help you find the server where you enable auditing of these actions. For step by
step instructions on how to enable audit actions, see “Enabling auditing of user
and system actions” on page 335.
For more information about the actions that are audited, and the data that is
recorded for each audit action, see “AuditID and AuditString reference” on
page 343, and “Auditing database schema reference” on page 341.
Crystal Enterprise Administrator’s Guide
331
Auditing overview
User Actions
Crystal
Enterprise
Server
Actions
A folder is created.
A folder is deleted.
Folders
A folder is modified.
(The name, location, or description of a folder is
modified.)
CMS
A report has been viewed successfully.
Cache
Server
A report could not be viewed.
A report is opened successfully using:
• the Web Report Design Wizard.
• the Advanced DHTML viewer.
• a custom application that uses RAS SDK.
A report fails to open.
Reports
A report has been created successfully using:
• the Web Report Design Wizard.
• a custom application that uses the RAS SDK.
Or
A report has been saved successfully using the Web
Report Design Wizard.
RAS
A report fails to be created.
Or
A report fails to save (using the Web Report Design
Wizard).
A report is saved successfully (using a custom
application based on the RAS SDK).
A report fails to save using a custom application based
on the RAS API.
A concurrent user logon succeeds.
A named user logon succeeds.
Users
A user logon fails.
CMS
A user’s password is changed.
User logs off.
332
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
Actions
Crystal
Enterprise
Server
An event is registered.
(Event is created, and registered with system)
Filebased
events
An event is updated.
(The name, description, or filename of an event is
modified.)
Event Server
An event is unregistered.
(Event is removed from system.)
System Actions
Actions
Crystal
Enterprise
Server
A job has been run successfully.
That is, a scheduled report has run successfully.
Reports
A job has failed to run.
That is, a scheduled report has failed to run.
(See Tip following this table.)
Report Job
Server
A job failed but will try to run again.
Communication with a running instance is lost.
That is, a scheduled report has failed to run because
communication with the instance was lost, and the
scheduled time for running the report expired.
File-based An event is triggered.
events
Crystal
Management
Server
Event Server
A job has been run successfully.
That is, a scheduled program has run successfully.
Programs
A job has failed to run.
That is, a scheduled program has failed to run.
(See Tip following this table.)
Program Job
Server
A job failed but will try to run again.
Communication with a running instance is lost.
That is, a scheduled program has failed to run because Crystal
Management
communication with the instance was lost, and the
Server
scheduled time for running the program expired.
Crystal Enterprise Administrator’s Guide
333
Configuring the auditing database
Tip: To audit every failure of a scheduled report or a scheduled program, enable
auditing of “A job has failed to run” on the Job Server, and “Communication with
a running instance is lost.” on the Crystal Management Server.
Configuring the auditing database
Before you audit actions within Crystal Enterprise, you must configure your
Crystal Management Server to connect to an auditing database. You can use any
database server supported for the CMS system database for your auditing
database. See the Platforms.txt file included with your product distribution for a
complete list of tested database software and version requirements.
Use a page size of 8K on database servers that support variable page sizes, such as
IBM DB2, Oracle, or Sybase. Using a smaller page size on these database servers
may cause table creation or row insertion to fail. Databases with fixed page size,
such as SQL Server or Informix, will perform row splits as necessary.
It is recommended that you develop a back up strategy for your auditing database.
If necessary, contact your database administrator for more information.
Note:
• The CMS system database and the auditing database are independent. If you
choose, you can use different database software for the CMS system database
and the auditing database, or you can install these databases on separate servers.
• If you have a CMS cluster, every CMS in the cluster must be connected to the
same auditing database, using the same connection method and the same
connection name. Note that connection names are case sensitive. (See
“Installing a new CMS and adding it to a cluster” on page 286 for more
information on CMS clusters.)
To configure the auditing database on Windows
1 Start the Crystal Configuration Manager (CCM).
2 Stop the CMS.
3 Click Specify Auditing Data Source.
4 In the Select Database Driver dialog box, specify whether you want to connect
to the new database through ODBC, or through one of the native drivers.
5 Click OK.
6 The remaining steps depend upon the connection type you selected:
• If you selected ODBC, the Windows “Select Data Source” dialog box appears.
Select the ODBC data source that you want to use as the auditing database;
then click OK. (Click New to configure a new DSN.) Use a System DSN, and
not a User DSN or File DSN. By default, server services are configured to run
under the System account, which only recognizes System DSNs.
When prompted, provide your database credentials and click OK.
334
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
• If you selected a native driver, you are prompted for your database Server
Name, your Login ID, and your Password. Provide this information and
then click OK.
The SvcMgr dialog box notifies you when the auditing database setup is complete.
7 Click OK.
8 Start the CMS. When the CMS starts, it will create the auditing database.
Note: You can also configure the auditing database using the Properties option for
the CMS. Stop the CMS, select Properties, and then go to the Configuration tab. Select
“Write server audit information to specified data source”, and then click Specify.
To configure the auditing database on UNIX
For more information on UNIX scripts, see “UNIX Tools” on page 435.
1 Use ccm.sh to stop the CMS.
2 Run cmsdbsetup.sh.
3 Choose the selectaudit option, and then supply the requested information
about your database server.
4 Run serverconfig.sh.
5 Choose the “Modify a server” option.
6 Select the CMS, and enable auditing. Enter the port number of the CMS when
prompted (the default value is 6400).
7 Use ccm.sh to start the CMS. When the CMS starts, it will create the auditing
database.
Enabling auditing of user and system actions
To audit an action in Crystal Enterprise you must first determine which Crystal
Enterprise server controls the action. Then you must enable auditing on the server
from the Servers management area of the Crystal Management Console (CMC).
If you have multiple Crystal Enterprise servers of a given type, be sure to enable
identical audit actions on every server. Doing so ensures that you collect
information on all user or system actions in your Crystal Enterprise system. For
example, if you are interested in the total number of concurrent user logons, enable
auditing of concurrent user logons on each of your Crystal Management Servers.
If you enable auditing on only one Crystal Management Server, you will only
collect audit information about actions that occur on that server.
In some special cases you may wish to enable auditing on only one server of a
given type. For example, if you are interested in the success or failure of only one
kind of scheduled report and you have configured your system so that these
reports are processed on one particular Report Job Server, it is not necessary to
Crystal Enterprise Administrator’s Guide
335
Enabling auditing of user and system actions
enable auditing on every Report Job Server in your system. You only need to
enable auditing on the Report Job Server where the reports are processed.
Note: You must configure the auditing database before you can collect data on
audit actions. See “Configuring the auditing database” on page 334 for
instructions.
To enable audit actions
1 Go to the Servers management area of the CMC.
2 Click the server that controls the action that you wish to audit.
(See the “Reference list of auditable actions” on page 331 to find the correct
server.) The server management area for the server opens.
3 Click the Auditing tab.
4 Select the Auditing is enabled check box.
5 Select the audit actions that you wish to record.
6 Ensure that your audit log file is located on a hard drive that has sufficient
space to store the log files. (See “Optimizing system performance while
auditing” on page 338 for information on adjusting the size of log files.)
7 Click Update.
336
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
Tip:
• To audit every failure of a scheduled report or a scheduled program, enable
auditing of “A job has failed to run” on the Job Server, and “Communication
with a running instance is lost” on the Crystal Management Server.
• Auditing is enabled independently on each server. If you want to audit all
actions of a given type, enable identical audit actions on every server that
supports those actions. Otherwise your audit record will be incomplete. For
example, if you want to track the total number of concurrent logons to your
Crystal Enterprise system, you must enable logging of concurrent logons on
every Crystal Management Server in your system.
Controlling synchronization of audit actions
The CMS controls the synchronization of audit actions that occur on different
machines. The CMS periodically broadcasts its system time to the auditees in UTC
(Coordinated Universal Time). The auditees compare this time to their internal
clocks, and then make the appropriate correction to the time stamp (in UTC) they
record for subsequent audit actions. This correction affects only the time stamp
that the auditee records in its audit log file. The auditee does not adjust the system
time of the machine on which it is running.
By default, the CMS broadcasts its system time every 60 minutes. You can change
the interval using the command-line option
-AuditeeTimeSyncInterval minutes
You can turn off this option by setting minutes to zero. For more information, see
“Crystal Management Server” in “Server Command Lines” on page 425.
This built-in method of time synchronization will be accurate enough for most
applications. For more accurate and robust time synchronization, configure the
auditee and auditor machines to use an NTP (Network Time Protocol) client, and
then turn off internal synchronization by setting
-AuditeeTimeSyncInterval 0
Tip: If you have a CMS cluster, apply the same command-line options to each
server. Only one CMS in the cluster acts as the auditor. However, if this CMS fails,
another CMS takes over auditing. This CMS will apply its own command-line
options. If these options are different than those of the original auditor, audit
behavior may not be what you expect.
Crystal Enterprise Administrator’s Guide
337
Optimizing system performance while auditing
Optimizing system performance while auditing
Enabling auditing should have minimal effect on the performance of Crystal
Enterprise. However, you can optimize system performance by fine-tuning these
command-line options:
• -AuditInterval minutes, where minutes is between 1 and 15. (The default
value is 5.) The CMS requests audit records from each audited server every
audit interval.
• -AuditBatchSize number, where number is between 50 and 500. (The default
value is 200.) The CMS requests this fixed number of records from each
audited server, every time interval.
• -auditMaxEventsPerFile number (number has a default value of 500 and must be
greater than 0). The maximum number of records that an audited server will
store in a single audit log file. When this maximum value is exceeded, the
server opens a new log file.
Note: Log files remain on the audited server until all records have been requested
by the CMS.
Changing each of these options has a different impact on system performance. For
example, increasing the audit interval reduces frequency with which the CMS
writes events to the auditing database. Decreasing the audit batch size decreases
the rate at which records are moved from the audit log files on the audited servers
to the auditing database, thereby increasing the length of time that it takes these
records to get transferred to the central auditing database. Increasing the
maximum number of audit events stored in each audit log file reduces the number
of file open and close operations performed by audited servers.
You can use these options to optimize audit performance to meet your needs. For
example, if you frequently need up-to-date information about audited actions, you
can choose a short audit interval and a large audit batch size. In this case, all audit
records are quickly transferred to the auditing database, and you can always
report accurately on the latest audit actions. However, choosing these options may
have an impact on the performance of Crystal Enterprise.
Alternatively, you may only need to review audit results periodically (weekly, for
example). In this case you can choose to increase the audit interval, and to decrease
the number of audit records in each batch. Choosing these options minimizes the
impact that auditing has on the performance of Crystal Enterprise. However,
depending upon activity levels in your system, these options can create a backlog
of records stored in audit log files. This backlog is cleared at times of low system
activity (such as overnight, or over a weekend), but means that at times your audit
reports may not contain records of the most recent audit actions.
For more information on changing command-line options, see “Server Command
Lines” on page 425.
338
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
Reporting on audit results
Using sample audit reports
Crystal Enterprise ships with several sample audit reports created using Crystal
Reports. They are available on your product CD.
To use these sample reports, first publish them to Crystal Enterprise. Next configure
an auditing database, and then enable auditing of the user and server actions needed
to provide data for the sample reports. Finally, ensure that the sample reports are
configured to use database connection information valid for your auditing database.
You can now use the sample reports to view auditing data collected about user and
system actions on your installation of Crystal Enterprise.
Note: If you have recently enabled auditing, the sample audit reports may contain
little or no data the first time you view them.
To use sample audit reports
1 Create a folder called “admin reports” inside the Report Samples folder to
hold the sample auditing reports.
Note: To create this folder, go to the Folders management area of the Crystal
Management Console (CMC). Click Report Samples, and then click New Folder.
2 Publish the sample audit reports to the “admin reports” folder within Crystal
Enterprise. (The sample audit reports are in Samples > Reports >
AdminReports on your product CD.)
For more information about publishing, see “Publishing Objects to Crystal
Enterprise” on page 115.
3 Configure your auditing database. See “Configuring the auditing database” on
page 334 for instructions.
The sample audit reports were created using a ODBC connection to a database
server named AuditData (that is, the DSN was AuditData), and a database
called CE10. You can create an auditing database that uses these names, or you
can use a database server name and database name of your choice.
4 Go to the Servers management area of the CMC. Enable auditing of the actions
that are included in the sample audit report. See “Enabling auditing of user
and system actions” on page 335 for instructions.
Note: The description of the sample reports indicates which audit actions to
enable for each report.
Crystal Enterprise will now begin to collect data on audit actions.
5 From the Crystal Enterprise Admin Launchpad, select the Crystal
Management Console (CMC).
6 Go to the Folders management area of the CMC.
Crystal Enterprise Administrator’s Guide
339
Reporting on audit results
7 Click Report Samples, then admin reports to display the list of sample audit
reports.
8 Click the name of a report that you want to use; then, from the Process tab,
click the Database link.
9 If the server name, database name, or database logon information for your
auditing database are different than the values originally specified for the
sample report, click “Use custom database logon information specified here.”
10 Type the Server name (DSN) and Database name that you specified for your
auditing database. Make sure you select the same database driver that you
used when configuring the auditing database.
11 Type a User name and Password for a user with administrative rights to the
auditing database.
12 Click Specify a custom table prefix, and then type DatabaseName.dbo. in the
box, where DatabaseName is the name of the database that you specified above.
13 Click Update.
340
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
The sample audit report is now configured to use your auditing database as its
data source.
14 From the Process tab, click the Parameters link.
15 Click the value of any parameter to specify a default value for that parameter,
or to indicate that the user should be prompted for a parameter value when
the report is run. Click Submit.
16 You may now view the report using Crystal Enterprise, or the Crystal
Management Console.
Creating custom audit reports
This section contains information to help you understand the auditing database
and the information it records about audit actions. With this information, you can
use Crystal Reports to create custom audit reports of user and system actions.
See your Crystal Reports User’s Guide for full instructions on creating reports.
Auditing database schema reference
For every audit action that it records, Crystal Enterprise collects the set of
information outlined here. Not every field will be recorded for each audit action;
for example, there is no object ID associated with a successful user logon.
Note: Crystal Enterprise uses the LVARCHAR data type on Informix databases,
rather than NVARCHAR.
.
Field
Type
Detail
EventID
VARCHAR(64)
String that uniquely identifies each audit
record in the database. Primary key for
table.
AuditID
DECIMAL 9(10,0)
Number that uniquely identifies the type
of action the entry represents. See the
“AuditID and AuditString reference” on
page 343 for details.
Crystal Enterprise Administrator’s Guide
341
Reporting on audit results
Field
Type
Detail
NVARCHAR(255)
Machine name of the server that
produced the action.
FriendlyName
NVARCHAR(255)
Friendly name of the server that produced
the action. The server’s friendly name is the
name displayed in the CMC. The default
friendly name is hostname.servertype.
UserID
DECIMAL 9(10,0)
Info Object ID of user who performed the
action. This number uniquely identifies a
user.
UserName
NVARCHAR(255)
Name of user who performed the action.
UserGroups
NVARCHAR(255)
Group or groups that the user belongs to.
If user belongs to more than one group,
the names are separated by the |
character.
ObjectID
DECIMAL 9(10,0)
Info Object ID of object associated with
the action. This number uniquely
identifies an object. This field may be
empty if there is no object associated with
an audit action.
ObjectName
NVARCHAR(255)
Name of the object. For example, if the
object is a report, this field will hold the
name of the report.
ObjectType
NVARCHAR(255)
Type of object. For example an object may
be a report, a folder, an object package or
a program object.
ObjectPath
NVARCHAR(255)
Path to object. The path is included
because the object name may not be
unique.
SessionID
DECIMAL 9(10,0)
Each time a user logs on, they are granted
a session ID. This field may be empty if the
action being audited is not associated with
a user session. For example, a user can
schedule a job to run overnight, when they
are not logged onto Crystal Enterprise. The
audit record showing the success or failure
of this job will not have a session ID.
Timestamp
VARCHAR(64)
Time of action in UTC (Coordinated
Universal Time) to the nearest
millisecond. The time stamp is created by
the server recording the action in its log
file, and includes any correction
necessary to synchronize with CMS time.
You may want to correct this time to your
local time zone when creating audit reports.
MachineName
342
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
Field
Type
Detail
Version
VARCHAR(16)
Version of Crystal Enterprise on server
that produced the action.
Language
NVARCHAR(32)
Language of Crystal Enterprise server
that produced the action.
SrcPrefix
NVARCHAR(32)
String representing the type of server that
produced the action.
Possible values: cms, jobserver,
eventserver, cacheserver, rptappserver.
AuditString
NTEXT (16)
Text string that describes audit action. See
“AuditID and AuditString reference” on
page 343 for a complete list of audit strings.
AuditID and AuditString reference
The auditing database collects records of all auditable actions that occur in your
Crystal Enterprise system. There are two ways of identifying which kind of action
each database record represents: the numeric AuditID and the text-based AuditString.
This section lists the AuditIDs and AuditStrings that are generated by Crystal
Enterprise, along with their meanings. Knowing the audit IDs and the exact audit
strings can help you construct queries for particular actions in your custom reports.
Some audit strings are the same every time they are generated. For example, if a
user changes their password, the audit string is always “User password has been
changed.” Other audit strings vary because they include additional information
about the action. For example, if a user logon fails, the audit string includes a
section that describes the reason for the failure. When a logon fails because the user
mistyped a user name, the complete audit string is “User logon failed. Reason:
Unknown user.” If a logon fails because the user entered the wrong password, the
complete audit string is “User logon failed. Reason: Invalid password.”
In the tables listing AuditStrings, the strings are described as having constant and
variable segments. If an AuditString has a segment that varies with the exact
nature of the audit action, the variable segment is indicated using a variable name
like VariableString.
CMS
AuditID
AuditStrings (constant)
65537
Concurrent user logon
succeeded.
The user logged on successfully,
using a concurrent user license.
65538
Named user logon
succeeded.
The user logged on successfully,
using a named user license.
65540
User logged off.
Crystal Enterprise Administrator’s Guide
AuditStrings (variable)
Notes
343
Reporting on audit results
AuditID
AuditStrings (constant)
65541
User password has been
changed.
65539
User logon failed.
Reason: VariableString
AuditStrings (variable)
Notes
No valid license key
found.
Logon failed because there was
no valid license key available.
Only guest and
In Standard mode, the only
administrator can logon valid user names are guest and
in Standard mode.
administrator. The logon failed
because the user attempted to
log on using a different user ID.
65542
New folder created.
65543
Folder VariableString1
deleted from path
VariableString2
Unknown user.
Logon failed because the user
entered a user name that is not
valid on this system.
User account disabled.
Logon failed because the user’s
account is disabled.
Concurrent user limit
reached.
Logon failed because all
concurrent user licenses are
already in use.
Invalid password.
Logon failed because the user
entered an invalid password.
A new folder is created, or an
existing folder is copied.
Note that this audit string will
not be recorded when a new
user account is created, even
though creating a user creates a
user folder.
VariableString1
contains the folder
name
VariableString2
contains the folder’s
path
65544
344
Folder modified.
A folder is deleted.
Note that this audit string will
be recorded when a user account
(and therefore the user’s folder)
is deleted.
The name, location, or
description of the folder was
changed.
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
AuditID
AuditStrings (constant)
AuditStrings (variable)
Notes
65545
Job failed. Reason:
unresponsive Job
Server Child process.
A scheduled report or scheduled
program failed to run because
communication with the
running instance was lost, and
the scheduled time for running
the job expired.
VariableString
Note: This action must be
audited by the CMS as Job
Servers are not aware of losing
communications with a job.
Cache Server
AuditID
AuditStrings (constant)
AuditStrings (variable)
Notes
196609
Report with
saved
User successfully viewed a
report that has saved data.
viewed successfully.
live
User successfully viewed a
report that has live data.
Report viewed
unsuccessfully. Reason
Many options
User attempted to view a report
object, but was not successful for
the reason listed in the variable
section of the audit string.
VariableString data
196610
VariableString
Report Job Server / Program Job Server
AuditID
AuditStrings (constant)
AuditStrings (variable) Notes
327681
Job successful. Elapsed
time: VariableString
seconds.
Elapsed time in
seconds
327682
Job failed Elapsed time:
VariableString
seconds.
327683
Job failed. Elapsed time:
VariableString
seconds. Job will be
retried by the CMS.
Crystal Enterprise Administrator’s Guide
The object ran as scheduled and the
job completed successfully within
the indicated time.
The scheduled job did not
complete successfully. The attempt
took the indicated amount of time.
The scheduled job did not
complete successfully. The attempt
took the indicated amount of time.
The job will will be retried by the
CMS at a later time. For more
information on scheduling jobs, see
“Scheduling objects” on page 220.
345
Reporting on audit results
Event Server
AuditStrings
(variable)
AuditID
AuditStrings (constant)
Notes
262145
Event registered
User creates a file-based event that can
be used to schedule objects.
262146
Event unregistered
User deletes a file-based event.
262147
Event updated
Event object was modified by a user, or
by the system. Events are updated
when a user modifies the name or
description of the file-based event.
262148
Event triggered
File-based event was initiated.
Report Application Server
AuditID
AuditStrings (constant)
458753
Report was opened for
viewing and/or
modification
346
AuditStrings
(variable)
Notes
User opened a report for viewing or
modification.
Note: In a few cases, this audit string
may be generated when the report
opens but cannot be viewed. This may
occur when:
• There are problems with the
database setup for the report. For
example, you may see this message
when the database driver for the report
is not present on the client machine
• A processing extension associated
with the report aborts viewing, or fails.
• The report used Business Views and
the user did not have permissions to
refresh the underlying data
connections.
• The machine running the RAS ran
out of space in its temporary directory.
Crystal Enterprise Administrator’s Guide
16: Managing Auditing
AuditStrings
(variable)
AuditID
AuditStrings (constant)
458754
Report was saved to the
CMS.
An existing report was saved.
Report was created and
saved to the CMS
A new report was created and saved.
458755
458756
458757
Notes
Note: This AuditID is generated when
a custom application created using the
RAS SDK saves a report (using the
Save method). Consult your RAS SDK
documentation for details.
Note:
• This AuditID is generated when a
custom application created using the
RAS SDK saves a new report (using the
Save As method). Consult your RAS
SDK documentation for details.
• This AuditID is also generated
when an existing report is saved using
the Web Design Report Wizard.
Many options
VariableString
The report could not be opened by the
RAS, for the reason listed in the
variable section of the audit string.
Many options
Report could not be
saved to the CMS.
Reason: VariableString
An existing report could not be saved
by RAS, for the reason listed in the
variable section of the audit string.
Report could not be
opened. Reason:
Note: This AuditID is generated when
a custom application created using the
RAS SDK cannot save a new report
(using the Save As method). Consult
your RAS SDK documentation for
details.
458758
Many options
Report could not be
created in the CMS.
Reason: VariableString
A newly created report could not be
saved by RAS, for the reason listed in
the variable section of the audit string.
Note: This AuditID is also generated
when an existing report fails to save
from the Web Design Report Wizard.
Crystal Enterprise Administrator’s Guide
347
Reporting on audit results
348
Crystal Enterprise Administrator’s Guide
Managing Server Groups
17
This chapter shows how to create server groups and
subgroups. It also shows how to modify the group
membership of an individual server.
Crystal Enterprise Administrator’s Guide
349
Server group overview
Server group overview
Server groups provide a way of organizing your Crystal Enterprise servers to
make them easier to manage. That is, when you manage a group of servers, you
need only view a subset of all the servers on your system. More importantly, server
groups are a powerful way of customizing Crystal Enterprise to optimize your
system for users in different locations, or for objects of different types.
If you group your servers by region, you can easily set up default processing
settings, recurrent schedules, and schedule destinations that are appropriate to
users who work in a particular regional office. You can associate an object with a
single server group, so the object is always processed by the same servers. And you
can associate scheduled objects with a particular server group to ensure that
scheduled objects are sent to the correct printers, file servers, and so on. Thus,
server groups prove especially useful when maintaining systems that span
multiple locations and multiple time zones.
If you group your servers by type, you can configure objects to be processed by
servers that have been optimized for those objects. For example, processing servers
need to communicate frequently with the database containing data for published
reports. Placing processing servers close to the database server that they need to
access improves system performance and minimizes network traffic. Therefore, if you
had a number of reports that ran against a DB2 database, you might want to create a
group of Page Servers that process reports only against the DB2 database server. If
you then configured the appropriate reports to always use this Page Server group for
viewing, you would optimize system performance for viewing these reports.
After creating server groups, configure objects to use specific server groups for
scheduling, or for viewing and modifying reports. For details, see “Specifying
servers for scheduling” on page 212 or “Specifying servers for viewing and
modification” on page 187. You can change the status, obtain metrics, and
configure your servers in the Server Groups management area—just as you would
in the Servers management area. The only difference is that you see only the
servers that you added to the server group.
Creating a server group
To create a server group, you need to specify the name and description of the
group, and then add servers to the group.
To create a server group
1 Go to the Server Groups management area of the CMC.
2 Click New Server Group.
350
Crystal Enterprise Administrator’s Guide
17: Managing Server Groups
The New Server Group Properties tab appears.
3 In the Server Group Name field, type a name for the new group of servers.
4 Use the Description field to include additional information about the group.
5 Click OK.
6 On the Servers tab, click Add/Remove Servers.
7 Select the servers that you want to add to this group; then click the > arrow.
Tip: Use CTRL+click to select multiple servers.
This example adds the servers running on BARACUS to a server group called
Northern Office Servers.
8 Click OK.
You are returned to the Servers tab, which now lists all the servers that you
added to the group. You can now change the status, view server metrics, and
change the properties of the servers in the group. For more information, see
“Server management overview” on page 270.
Crystal Enterprise Administrator’s Guide
351
Working with server subgroups
Working with server subgroups
Subgroups of servers provide you with a way of further organizing your servers.
A subgroup is just a server group that is a member of another server group.
For example, if you group servers by region and by country, then each regional
group becomes a subgroup of a country group. To organize servers in this way,
first create a group for each region, and add the appropriate servers to each
regional group. Then, create a group for each country, and add each regional
group to the corresponding country group.
There are two ways to set up subgroups: you can modify the subgroups of a server
group, or you can make one server group a member of another. The results are the
same, so use whichever method proves most convenient.
To add subgroups to a server group
1 Go to the Server Groups management area of the CMC.
2 Click the group that you want to add subgroups to.
This group is the parent group.
3 On the Subgroups tab, click Add/Remove Groups.
4 In the Available server groups list, select the server groups that you want to
add as subgroups; then click the > arrow.
5 Click OK.
You are returned to the Subgroups tab, which now lists all the server groups
that you added to the parent group.
To make one server group a member of another
1 Go to the Server Groups management area of the CMC.
2 Click the group that you want to add to another group.
3 On the Member of tab, click the Member of button.
4 In the Available server groups list, select the server groups that should
include your group as a member; then click the > arrow.
352
Crystal Enterprise Administrator’s Guide
17: Managing Server Groups
This example makes the Job Servers group a member subgroup of the Northern
Office Servers group.
5 Click OK.
You are returned to the “Member of” tab, which now lists all the server groups
that the initial group is now a member of.
Modifying the group membership of a server
You can modify a server’s group membership to quickly add the server to (or
remove it from) any group or subgroup that you have already created on the system.
For example, suppose that you created server groups for a number of regions. You
might want to use a single Web Component Server (WCS) for multiple regions.
Instead of having to add the WCS individually to each regional server group, you
can click the server’s “Member of” link to add it to all three regions at once.
To modify a server’s group membership
1 Go to the Servers management area of the CMC.
2 Locate the server whose membership information you want to change.
3 In the Server Group column, click the server’s Member of link.
The “Member of” page lists any server groups that the server currently belongs to.
4 Click the Member of button.
The “Modify Member Of” page appears.
5 Move server groups from one list to another to specify which groups the
server is a member of.
6 Click OK.
Crystal Enterprise Administrator’s Guide
353
Modifying the group membership of a server
354
Crystal Enterprise Administrator’s Guide
Scaling Your System
18
This chapter details the common ways in which you should
begin to scale, or expand, your Crystal Enterprise system. The
chapter also provides general scalability considerations, and
shows how to add server components to your installation.
Crystal Enterprise Administrator’s Guide
355
Scalability overview
Scalability overview
The Crystal Enterprise architecture is scalable in that it allows for a multitude of server
configurations, ranging from stand-alone, single-machine environments, to largescale deployments supporting global organizations. The flexibility offered by the
product’s architecture allows you to set up a system that suits your current reporting
requirements, without limiting the possibilities for future growth and expansion.
This chapter details common scalability scenarios for administrators who want to
expand beyond a stand-alone installation of Crystal Enterprise. These three
scenarios have received the most testing, and are recommended for the majority of
deployments. For details, see “Common configurations” on page 356.
It must be emphasized, however, that the optimal configuration for your
deployment will vary depending upon your hardware configuration, your
database software, and your reporting requirements. It is recommended that you
contact your Crystal Decisions sales representative and request information about
the Crystal Enterprise Sizing Guide. A Crystal Services consultant can then assess
your reporting environment and assist in determining the configuration that will
best integrate with your current environment.
Note: If you customize or expand your system beyond these common configurations
without first contacting Crystal Services, your deployment may not be officially
supported.
This chapter also provides the related procedures for adding and deleting servers
from your Crystal Enterprise installation. Follow these steps when you need to add
server components to a machine that is already running Crystal Enterprise.
Tip: If you are adding new hardware to Crystal Enterprise by installing server
components on additional machines, run the Crystal Enterprise installation and
setup program. The setup program allows you to perform an Expand installation.
During the Expand installation, you specify the existing CMS whose system you
want to expand, and you select the components that want to install on the local
machine. For details, see the Crystal Enterprise Installation Guide.
Common configurations
This section details the common ways in which you should begin to scale, or
expand, your Crystal Enterprise system. The scenarios described are those that
have been most thoroughly tested by Crystal Decisions, Inc. As a baseline, this
section assumes that you have not yet distributed the Crystal Enterprise servers
across multiple machines; however, this section does assume familiarity with the
Crystal Enterprise architecture, installation, and server configuration. For
preliminary installation information, see the Crystal Enterprise Installation Guide.
Tip: If you are deploying multi-processor machines, you may also want to run one
or more Crystal Enterprise servers in multiple instances on that machine. For
details, see “Adding a server” on page 365.
356
Crystal Enterprise Administrator’s Guide
18: Scaling Your System
One-machine setup
This basic configuration separates the Crystal Enterprise servers from the rest of
your reporting environment and from your web server, and installs all Crystal
Enterprise servers on a single machine. This grants the Crystal Enterprise servers
their own set of processing resources, which they do not have to share with
database and web server processes. These are the general steps to setting up this
configuration for the default Windows installation of Crystal Enterprise:
• Install all of the Crystal Enterprise servers on a single, dedicated machine.
• Install and configure the Web Connector on your web server machine.
• Run the CMS database on your database server.
If you are still using the MSDE CMS database on Windows, migrate the CMS
database to a supported database server. See the Platforms.txt file included
with your product distribution for a list of supported database servers.
For a UNIX installation (or for a Windows installation that uses the Crystal
Enterprise Java SDK), install your Crystal Enterprise servers on the same machine
as your Java web application server and the Web Component Adapter.
Three-machine setup
This second configuration divides the Crystal Enterprise processing load in a
logical manner, based on the types of work performed by each server. In this way,
you prevent the server components from having to compete with each other for the
same hardware and processing resources. In addition, this scenario prepares your
system for further expansion to provide redundancy.
Note: It is recommended that you use three multi-processor machines (dual-CPU
or better), with at least 2 GB RAM installed on each machine.
These are the general steps to setting up this configuration for the default
Windows installation of Crystal Enterprise:
• Install the CMS and the Event Server on one machine.
Tip: Here, the Event Server is installed on the same machine as the CMS. In
general, however, the Event Server should be installed on the machine where
your monitored, file-based events occur.
• Install the WCS and the Cache Server on the second machine.
• Install the Page Server, the Job Server, the Report Application Server (RAS),
and the Input and Output File Repository Servers on the third machine.
For a UNIX installation (or for a Windows installation that uses the Crystal
Enterprise Java SDK), install the Java web application server and the Web
Component Adapter on the same machine as your Cache Server.
Note: As with the one-machine setup, install your Crystal Enterprise servers on
machines that are separate from your web server and database servers. This
grants the Crystal Enterprise servers their own set of processing resources, which
they do not have to share with database and web server processes.
Crystal Enterprise Administrator’s Guide
357
Common configurations
Six-machine setup
This third configuration mirrors the three-machine setup. You maintain the logical
breakdown of processing based on the types of work performed by each server,
but you increase the number of available machines and servers for redundancy
and fault-tolerance. For instance, if a server stops responding, or if you need to take
one or two machines offline completely, you need not interrupt Crystal Enterprise
requests in order to service the system.
This tested configuration is designed to meet the reporting requirements of 85% of
all deployment scenarios. If you have further requirements or more advanced
configuration needs, contact your Crystal Decisions sales representative for
additional assistance.
Note: It is recommended that you use six multi-processor machines (dual-CPU or
better), with at least 2 GB RAM installed on each machine.
These are the general steps to setting up this configuration for the default
Windows installation of Crystal Enterprise:
• Install the three-machine setup first. Verify that Crystal Enterprise is functioning
correctly.
• Install a second CMS/Event Server pair on the fourth machine. This machine
must have a fast network connection (minimum 10 Mbps) to the CMS that you
have already installed.
Cluster the two CMS services, so they share the task of maintaining the CMS
database. Ensure that each CMS accesses the CMS database in exactly the same
manner (the same database client software, the same database user name and
password, and so on).
Tip: Here, the Event Server is installed on the same machine as the CMS. In
general, however, the Event Server should be installed on the machine where
your monitored, file-based events occur.
• Install a second WCS/Cache Server pair on the fifth machine.
Modify your Web Connector configuration to ensure that the Web Connector
communicates with the two distinct WCS hosts.
or
Install a second Java web application server and Web Component Adapter on
the fifth machine, along with a second Cache Server. Consult your web
application server documentation for information on load-balancing and
clustering your application servers.
Ensure that the web.xml file is configured correctly for each WCA.
• Install a second Page Server, Job Server, and RAS on the remaining machine,
along with a pair of Input and Output File Repository Servers.
Ensure that all Page Servers and Job Servers can access your reporting database
in exactly the same manner. Install and configure any required database client
software similarly on each machine, along with any ODBC DSNs that are
required for your reports.
358
Crystal Enterprise Administrator’s Guide
18: Scaling Your System
Note: As with the one-machine setup, install your Crystal Enterprise servers on
machines that are separate from your web server and database servers. This
grants the Crystal Enterprise servers their own set of processing resources, which
they do not have to share with database and web server processes.
General scalability considerations
This section provides information about system scalability and the Crystal
Enterprise servers that are responsible for particular aspects of your system. Each
subsection focuses on one aspect of your system’s capacity, discusses the relevant
components, and provides a number of ways in which you might modify your
configuration accordingly.
Before modifying these aspects of your system, it is strongly recommended that
you contact your Crystal Decisions sales representative and request information
about the Crystal Enterprise Sizing Guide. A Crystal Services consultant can then
assess your reporting environment and assist in determining the configuration
that will best integrate with your current environment.
Increasing overall system capacity
As the number of report objects and users on your system increases, you can
increase the overall system capacity by clustering two (or more) Crystal
Management Servers (CMS). You can install multiple CMS services/daemons on
the same machine. However, to provide server redundancy and fault-tolerance,
you should ideally install each cluster member on its own machine.
CMS clusters can improve overall system performance because every Crystal
Enterprise request results, at some point, in a server component querying the CMS
for information that is stored in the CMS database. When you cluster two CMS
machines, you instruct the new CMS to share in the task of maintaining and
querying the CMS database.
For more information, see “Clustering Crystal Management Servers” on page 284.
Increasing scheduled reporting capacity
All Crystal reports that are scheduled are eventually processed by a Report Job
Server. You can expand Crystal Enterprise by running individual Report Job
Servers on multiple machines, or by running multiple Report Job Servers on a
single multi-processor machine.
If the majority of your reports are scheduled to run on a regular basis, there are
several strategies you can adopt to maximize your system’s processing capacity:
• Install the Report Job Server in close proximity to (but not on the same
machine as) the database server against which the reports run. Ensure also that
the File Repository Servers are readily accessible to all Report Job Servers (so
Crystal Enterprise Administrator’s Guide
359
General scalability considerations
•
•
•
•
they can read report objects from the Input FRS and write report instances to
the Output FRS quickly). Depending upon your network configuration, these
strategies may improve the Report Job Server’s processing speeds, because
there is less distance for data to travel over your corporate network.
Verify the efficiency of your reports. When designing reports in Crystal
Reports, there are a number of ways in which you can improve the
performance of the report itself, by modifying record selection formulas, using
the database server’s resources to group data, incorporating parameter fields,
and so on. For more information, see the “Designing Optimized Web Reports”
section in the Crystal Reports User’s Guide (version 8.5 and later).
Use event-based scheduling to create dependencies between large or complex
reports. For instance, if you run several very complex reports on a regular,
nightly basis, you can use Schedule events to ensure that the reports are
processed sequentially. This is a useful way of minimizing the processing load
that your database server is subject to at any given point in time.
If some reports are much larger or more complex than others, consider
distributing the processing load through the use of server groups. For
instance, you might create two server groups, each containing one or more
Report Job Servers. Then, when you schedule recurrent reports, you can
specify that it be processed by a particular server group to ensure that
especially large reports are distributed evenly across resources.
Increase the hardware resources that are available to a Report Job Server. If the
Report Job Server is currently running on a machine along with other Crystal
Enterprise components, consider moving the Report Job Server to a dedicated
machine. If the new machine has multiple CPUs, you can install multiple
Report Job Servers on the same machine (typically no more than one service/
daemon per CPU).
Increasing on-demand viewing capacity
When you provide many users with View On Demand access to reports, you allow
each user to view live report data by refreshing reports against your database
server. For most requests, the Page Server retrieves the data and performs the
report processing, and the Cache Server stores recently viewed report pages for
possible reuse. However, if users use the Advanced DHTML viewer, the Report
Application Server (RAS) processes the request.
If your reporting requirements demand that users have continual access to the
latest data, you can increase capacity in the following ways:
• Increase the maximum allowed size of the cache. For details, see “Modifying
Cache Server performance settings” on page 301.
• Verify the efficiency of your reports. When designing reports in Crystal
Reports, there are a number of ways in which you can improve the
performance of the report itself, by modifying record selection formulas, using
the database server’s resources to group data, incorporating parameter fields,
360
Crystal Enterprise Administrator’s Guide
18: Scaling Your System
and so on. For more information, see the “Designing Optimized Web Reports”
section in the Crystal Reports User’s Guide (version 8.5 and later).
• Increase the number of Page Servers that service requests on behalf of any single
Cache Server. You can install additional Page Servers on multiple machines, or
you can run multiple Page Servers on a single multi-processor machine
(typically no more than one service/daemon per CPU).
• Increase the number of Page Servers, Cache Servers, and Report Application
Servers on the system, and then distribute the processing load through the use of
server groups. For instance, you might create two server groups, each
containing one or more Cache Server/Page Server pairs along with one or more
Report Application Servers. You can then specify individual reports that should
always be processed by a particular server group.
Enhancing custom web applications
If you are developing your own custom desktops or administrative tools with the
Crystal Enterprise Software Development Kit (SDK), be sure to review the libraries
and APIs. You can now, for instance, incorporate complete security and scheduling
options into your own web applications. You can also modify server settings from
within your own code in order to further integrate Crystal Enterprise with your
existing intranet tools and overall reporting environment.
To improve the scalability of your system, consider distributing administrative
efforts by developing web applications for delegated content administration. You
can grant select users the ability to manage particular Crystal Enterprise folders,
content, users, and groups on behalf of their team, department, or regional office.
In addition, be sure to check the developer documentation available on your Crystal
Enterprise product CD for performance tips and other scalability considerations.
The query optimization section in particular provides some preliminary steps to
ensuring that custom applications make efficient use of the query language.
Improving web response speeds
Because all user interaction with Crystal Enterprise occurs over the Web, you may
need to investigate a number of areas to determine exactly where you can improve
web response speeds. These are some common aspects of your deployment that
you should consider before deciding how to expand Crystal Enterprise:
• Assess your web server’s ability to serve the number of users who connect
regularly to Crystal Enterprise. Use the administrative tools provided with
your web server software (or with your operating system) to determine how
well your web server performs. If the web server is indeed limiting web
response speeds, consider increasing the web server’s hardware and/or setting
up a “web farm” (multiple web servers responding to web requests to a single
IP address). See “Configuring your web farm for load balancing” on page 362.
Crystal Enterprise Administrator’s Guide
361
General scalability considerations
• If web response speeds are slowed only by report viewing activities, see
“Increasing scheduled reporting capacity” on page 359 and “Increasing ondemand viewing capacity” on page 360.
• Take into account the number of users who regularly access your system. If
you are running a large deployment, ensure that you have set up a CMS
cluster. For details, see “Increasing overall system capacity” on page 359.
If you find that a single application server (that is, the WCS or the Java web
application server) inadequately services the number of scripting requests made
by users who access your system on a regular basis, consider the following options:
• Increase the hardware resources that are available to the application server. If
the application server is currently running on the web server, or on a single
machine with other Crystal Enterprise components, consider moving the
application server to a dedicated machine. If the new machine has multiple
CPUs, you can install multiple WCS services/daemons or Java application
servers on the same machine (typically no more than one per CPU).
• If you are using the default Windows installation of Crystal Enterprise, set up
two (or more) WCS machines to take advantage of the dynamic load balancing
that is built into the Web Connector components. The Web Connector
distributes the processing load evenly across WCS hosts: each new Crystal
Enterprise session is sent to the least used WCS. This also provides you with
the benefits of being able to take one WCS machine offline for service, without
bringing down the entire system.
• If you are using the UNIX installation of Crystal Enterprise (or have
configured your Windows installation to use the Crystal Enterprise Java SDK),
consider setting up two (or more) Java application servers. Consult the
documentation for your Java web application server for information on loadbalancing, clustering, and scalability.
Note: Crystal Enterprise does not support the session-replication functionality
provided by some Java web application servers.
Configuring your web farm for load balancing
A web farm is a group of two or more web servers working together to handle
browser requests. If you are using the default installation of Crystal Enterprise on
Windows, the Web Connectors that reside on each of the web servers need to be
configured so they are aware of the Web Component Servers they should
communicate with.
Note: Crystal Enterprise supports web farms with and without affinity masks.
After the connectors have been configured, they can load-balance requests between
the Web Component Servers. When a web server establishes a connection with a
Web Component Server, it uses a round robin algorithm to identify the next available
Web Component Server. The only exceptions to this occur when a web server uses a
CGI web connector, or if a session state was created on a previous request to the Web
362
Crystal Enterprise Administrator’s Guide
18: Scaling Your System
Component Server. The CGI web connector uses a random algorithm instead of a
round robin algorithm because the connector doesn’t have knowledge of the last
Web Component Server it communicated with. Requests that had a session set up
previously, must return to the same Web Component Server each time to ensure that
subsequent requests have access to the previously set session state.
Tip: Consult the documentation for your Java web application server for
information on load-balancing, clustering, and scalability of these servers.
To configure a web farm for Crystal Enterprise
1 When you install the Web Connector along with the Crystal Enterprise “web
content” on each of your web servers, select the same installation directory on
each machine.
2 When you install multiple Web Component Servers, select the same
installation directory on each machine.
3 Verify that the virtual directory mappings and the application mappings are
configured identically on each web server.
4 Configure each Web Connector to communicate with all of your Web
Component Servers.
For instance, if you are running two web servers and three Web Component
Servers, configure the virtual path mappings similarly for both Web
Connectors, so they can both communicate with all three WCS hosts.
For complete details on installing and configuring Web Connectors for your web
server, and for troubleshooting steps related to path mappings, see the Crystal
Enterprise Installation Guide.
Getting the most from existing resources
One of the most effective ways to improve the performance and scalability of your
system is to ensure that you get the most from the resources that you allocate to
Crystal Enterprise.
Optimizing network speed and database efficiency
When thinking about the overall performance and scalability of Crystal Enterprise,
don’t forget that Crystal Enterprise depends upon your existing IT infrastructure.
Crystal Enterprise uses your network for communication between servers and for
communication between Crystal Enterprise and client machines on your network.
Make sure that your network has the bandwidth and speed necessary to provide
Crystal Enterprise users with acceptable levels of performance. Consult your
network administrator for more information.
Crystal Enterprise processes reports against your database servers. If your databases
are not optimized for the reports you need to run, then the performance of Crystal
Enterprise may suffer. Consult your database administrator for more information.
Crystal Enterprise Administrator’s Guide
363
Adding and deleting servers
Using the appropriate processing server
When users view a report using the Advanced DHTML viewer, the report is
processed by the Report Application Server rather than the Page Server and Cache
Server. The Report Application Server is optimized for report modification. For
simple report viewing you can achieve better system performance if users select
the DHTML viewer, the Active X viewer, or the Java viewer. These report viewers
process reports against the Page Server.
If the ability to modify reports is not needed at your site, you can disable the
Advanced DHTML viewer for all users of Crystal Enterprise.
Disabling the Advanced DHTML Viewer
1 In the Crystal Management Console, select Crystal Applications.
2 Select Web Desktop.
3 On the Preferences tab, go to the Viewers area. Clear the option labeled Allow
users to use the Advanced DHTML Viewer.
4 Click Update.
Optimizing Crystal Enterprise for report viewing
Crystal 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.
For details on data sharing options for reports, see “Setting report viewing
options” on page 186. For more information on configuring Crystal Enterprise to
optimize report viewing in your system, see the planning chapter in the Crystal
Enterprise Installation Guide.
Adding and deleting servers
This section shows how to add and delete servers from a machine that is already
running Crystal Enterprise components.
Tip: If you are adding new hardware to Crystal Enterprise by installing server
components on new, additional machines, run the Crystal Enterprise installation
and setup program from your product distribution. The setup program allows you
to perform an Expand installation. During the Expand installation, you specify the
existing CMS whose system you want to expand, and you select the components
that you want to install on the local machine. For details, see the Crystal Enterprise
Installation Guide.
364
Crystal Enterprise Administrator’s Guide
18: Scaling Your System
Adding a server
These steps add a new instance of a server to the local machine. You can run
multiple instances of the same Crystal Enterprise server on the same machine.
To add a Windows server
Note: To complete this procedure, you must log on as an Administrator of the
local machine.
1 Start the CCM on the Crystal Enterprise machine upon which you want to
install a new server.
2 On the toolbar, click Add Server.
The Add Crystal Server Wizard displays its Welcome dialog box.
3 Click Next.
The “Server Type and Display Name Configuration” dialog box appears.
4 Click the Server Type list and select the kind of server you want to add.
5 Change the default Display Name field if you want a different name to appear
in the list of servers in the CCM.
Note: The display name for each server on the local machine must be unique.
6 Change the default Server Name field if required.
Each server on the system must have a unique name. The default naming
convention is HOSTNAME.servertype (a number is appended if there is more than
one server of the same type on the same host machine). This Server Name is
displayed when you manage servers over the Web in the Crystal Management
Console (CMC).
When you add Input or Output File Repository Servers, the wizard always
precedes the server name you type with an “Input.” or “Output.” prefix. So, if you
Crystal Enterprise Administrator’s Guide
365
Adding and deleting servers
add an Input FRS with the name SERVER02, the CCM actually names the server
Input.SERVER02. This “Input.” prefix is required by the system. If you subsequently
modify the server’s name through its command line, do not remove the prefix.
7 Click Next.
The “Set Configuration for this server” dialog box appears. The contents of this
dialog vary slightly, depending upon the type of server that you are installing.
8 Type the name of the CMS that you want the server to communicate with.
If your CMS is not listening on the default port (6400), include the appropriate
port number, as in CMSname:port#
9 Click Next to accept any other default values, or modify them to suit your
environment.
Note: If port number options are displayed in this dialog box, do not modify
them. Instead, change ports through each server’s command line. For details,
see “Changing the default server port numbers” on page 321.
10 Confirm the summary information is correct; then click Finish.
The new server appears in the list, but it is neither started nor enabled automatically.
11 Use the CCM (or the CMC) to start and then to enable the new server when
you want it to begin responding to Crystal Enterprise requests. For details, see
“Viewing and changing the current status of servers” on page 274.
Tip: Auditing in Crystal Enterprise is enabled on a per server basis. If you add a
new server to your Crystal Enterprise installation you must enable auditing of
actions on each new server. If you do not, the actions performed on the new server
will not be audited. See “Enabling auditing of user and system actions” on
page 335 for more information.
To add a UNIX server
Use the serverconfig.sh script. For reference, see “serverconfig.sh” on page 439.
Deleting a server
To delete a Windows server
1 Start the CCM on the Crystal Enterprise machine that you want to delete a
server from.
2 Stop the server that you want to delete from the system.
3 With the server selected, click Delete Server on the toolbar.
4 When prompted for confirmation, click Yes.
To delete a UNIX server
Use the serverconfig.sh script. For reference, see “serverconfig.sh” on page 439.
366
Crystal Enterprise Administrator’s Guide
Working with Firewalls
19
This chapter describes how Crystal Enterprise works with
firewall systems. After providing some background
information on the supported types of firewalls, this
chapter explains how to configure firewalls and Crystal
Enterprise to work together.
Crystal Enterprise Administrator’s Guide
367
Firewalls overview
Firewalls overview
Crystal Enterprise works with firewall systems to provide reporting across
intranets and the Internet without compromising network security. This chapter
provides general information about firewalls, packet filtering, Network Address
Translation (NAT), and SOCKS proxy server firewalls. It then explains how to
configure these firewalls and Crystal Enterprise to work together.
If you are already familiar with firewalls and the configuration used in your
network, proceed directly to “Understanding Crystal Enterprise and firewall
integration” on page 371.
What is a firewall?
A firewall is a security system that protects one or more computers from
unauthorized network access. A firewall restricts people to entering and leaving
your network at a carefully controlled point. It also prevents attackers from getting
close to your other defenses. Typically, a firewall protects a company’s intranet
from being improperly accessed through the Internet. A firewall can enforce a
security policy, log Internet activity, and be a focus for security decisions. A firewall
can’t protect against malicious insiders or connections that don’t go through it. A
firewall also can’t set itself up correctly or protect against completely new threats.
To help explain how firewalls work, some basic networking terms—TCP/IP,
packets, and ports—are described here.
If you are already familiar with these topics see “Understanding Crystal Enterprise
and firewall integration” on page 371.
TCP/IP and packets
TCP/IP (Transmission Control Protocol/Internet Protocol) is the communications
protocol used on the Internet. The units of data transmitted through a TCP/IP
network are called packets. Packets are typically too small to contain all the data
that is sent at any one time, so multiple packets are required, each containing a
portion of the overall data. When data is sent by TCP/IP, the packets are
constructed such that a layer for each protocol is wrapped around each packet.
Typically, TCP/IP packets have the following layers:
• Application layer (for example, FTP, telnet, and HTTP).
• Transport layer (TCP or UDP).
• Internet layer (IP).
• Network Access layer (for example, ethernet and ATM).
At the application layer, the packet consists simply of the data to be transferred. As
the packet moves through the layers, each layer adds a header to the packet,
preserving the data from the previous level. These headers are used to determine
the packet’s destination and to ensure that it arrives intact. When the packet
368
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
reaches its destination, the process is reversed: the layers are sequentially removed
until the transferred data is available to the destination application.
Ports
Ports are logical connection points that a computer uses to send and receive
packets. With TCP/IP, ports allow a client program to specify a particular server
program on a computer in a network. High-level applications that use TCP/IP
have ports with pre-assigned numbers. For instance, when you visit a typical
HTTP site over the Web, you communicate with the web server on port 80, which
is the pre-assigned port for HTTP communication.
Other application processes are given port numbers dynamically for each
connection. When a service or daemon initially is started, it binds to its designated
port number. When any client program wants to use that server, it must also
request to bind to the designated port number. Valid port numbers range from 0
to 65536, but ports 0 to 1024 are reserved for use by certain privileged services.
Firewall types
Firewalls primarily function using at least one of three methods: packet filtering,
Network Address Translation (NAT), and proxy services. Crystal Enterprise
works with these firewall types. Packet filtering rejects TCP/IP packets from
unauthorized hosts and rejects connection attempts to unauthorized services. NAT
translates the IP addresses of internal hosts to hide them from outside monitoring.
NAT is also called IP masquerading. Proxy services make high-level application
connections on behalf of internal hosts to completely break the network layer
connection between internal and external hosts.
Packet filtering
Packet filtering deletes packets before they are delivered to the destination
computer. Packet filtering can delete packets based on the following:
• The address the data is coming from.
• The address the data is going to.
• The session and application ports being used to transfer the data.
• The data contained within the packet.
Typically there are two types of packet filtering: stateful and stateless. Stateful
packet filters remember the state of connections at the network and session layers
by recording the established session information that passes through the filter
gateway. The filter then uses that information to discriminate valid return packets
from invalid connection attempts. Stateless packet filters do not retain information
about connections in use; instead, they make determinations packet-by-packet
based only on the information contained within the packet. Firewalls that employ
packet filtering will work with Crystal Enterprise.
Crystal Enterprise Administrator’s Guide
369
Firewalls overview
Network Address Translation
Network Address Translation (NAT) converts private IP addresses in a private
network to globally unique, public IP addresses for use external to that network.
The main purpose of NAT is to hide internal hosts. As outgoing packets are routed
through the firewall, NAT hides internal hosts by converting their IP addresses to
an external address. Once the translation is complete, the firewall sends the data
payload on to its original destination; thus, NAT makes it appear that all traffic
from your site comes from one (or more) external IP addresses.
The firewall maintains a translation table to keep track of the address conversions
that it has performed. When an incoming response arrives at the firewall, the
firewall uses this translation table to determine which internal host should receive
the response. Because this type of firewall essentially sends and receives data on
behalf of internal hosts, NAT can also be described as a simple proxy.
There are two basic types of NAT:
• Static translation (port forwarding) grants a specific internal host a fixed
translation that never changes. For example, if you run an email server inside a
firewall, you can establish a static route through the firewall for that service.
• Dynamic translation (automatic, hide mode, or IP masquerade) shares a small
group of external IP addresses amongst a large group of internal clients for the
purpose of expanding the internal network address space. Because a translation
entry does not exist until an internal client establishes a connection out through
the firewall, external computers have no way to address an internal host that is
protected using a dynamically translated IP address.
Note: Some protocols do not function correctly when the port is changed.
These protocols will not work through a dynamically translated connection.
Crystal Enterprise and static translation NAT can be configured so that they work
together.
SOCKS proxy servers
SOCKS is a networking protocol that enables computers on one side of a SOCKS
server to access computers on the other side of a SOCKS server without requiring
a direct IP connection. A SOCKS server redirects connection requests from
computers on one side of it to computers on the other side of it. A SOCKS server
typically authenticates and authorizes requests, establishes a proxy connection,
and relays data between the internal and external networks. Crystal Enterprise
supports and works with SOCKS servers.
SOCKS servers work by listening for service requests from internal clients. When
an external request is made, the SOCKS server sends the requests to the internal
network as if the SOCKS server itself was the originating client. When the SOCKS
server receives a response from the internal server, it returns that response to the
original client as if it were the originating external server. This effectively hides the
identity and the number of clients on the internal network from examination by
anyone on the external network.
370
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Understanding Crystal Enterprise and firewall
integration
This section gives a conceptual overview of internal communications between
Crystal Enterprise servers and the implications for firewall configuration. It also
reviews the most common firewall scenarios.
For detailed step-by-step instructions on how to configure your system to work in
a firewalled environment, see “Configuring Crystal Enterprise to work with
firewalls” on page 374.
Communication between Crystal Enterprise servers
It is helpful to understand the basics of internal communications between Crystal
Enterprise servers before configuring your Crystal Enterprise system to work with
firewalls.
Some examples also apply to communications between a Crystal Enterprise server
and the Crystal Enterprise SDK (or other Crystal Enterprise SDKs, such as the
Report Application Server SDK or the Viewer SDK). Where applicable, these
examples are indicated in the descriptions.
Connections when servers use the CMS directory listing
service
The Crystal Management Server (CMS) manages a directory listing service for the Web
Component Server and the servers in the Intelligence Tier and the Processing Tier. (See
“Architecture overview and diagram” on page 28 for a listing of these servers.)
When a Crystal Enterprise server first connects to the Crystal Enterprise
framework, it registers its IP address and port number with the CMS. By default
this port number is dynamically chosen.
When one Crystal Enterprise server needs to communicate with another, it
contacts the directory listing service on the CMS to obtain the connection
information. The first server then uses this information to communicate directly
with the second server.
For example, before running a scheduled report, the Report Job Server must
communicate with the Input File Repository Server (FRS) to obtain the report
object. To do so:
• The Report Job Server contacts the CMS and requests connection information
for the Input FRS.
• The CMS replies to the Report Job Server with the IP address and port number
of the Input FRS.
Crystal Enterprise Administrator’s Guide
371
Understanding Crystal Enterprise and firewall integration
• The Report Job Server uses this information to connect directly to the Input
FRS. All subsequent communications between the two servers continues using
the same address and port.
Note:
• This communication model is also used when a Crystal SDK or the WCA
communicates directly with a server in the Intelligence Tier or the Processing
Tier.
• The CMS includes a directory listing for the WCS, but communications
between the CMS and WCS (or the CMS and the Crystal Enterprise SDK and
WCA) follow another model. See “Connections between the Web Connector
and WCS, or between the application tier and CMS” on page 372.
• Using the -requestport command, you can configure any Crystal Enterprise
server to register a fixed port number with the CMS, rather than using one that
is dynamically selected.
Connections between the Web Connector and WCS, or
between the application tier and CMS
Not all Crystal Enterprise components use the directory listing service on the CMS
to make their initial connections with other elements of Crystal Enterprise.
The Web Connector (WC) contacts the Web Component Server (WCS) using a predefined address and port number. The WCS replies to the WC with its address and
a second port number, which by default is selected dynamically. This address and
second port number is used for all subsequent communications between the two
components.
Communications between the WCS and CMS (or a Crystal SDK and the CMS)
follows the same pattern as WC - WCS communications. The WCS contacts the
CMS using a pre-defined address and port number. The CMS replies with its
address and a second port number, which by default is selected dynamically.
Subsequent communications continue using this address and second port number.
You can use the -requestport command to configure the WCS or CMS to reply
with a fixed port number for subsequent communications, rather than one that is
dynamically selected. Using the -port option, you can also customize the WCS or
the CMS to listen on a specific port for initial communications, rather than using
the pre-defined default values (port 6401 for the WCS, and port 6400 for the CMS).
Note:
• Before changing the default port numbers, see “Changing the default server
port numbers” on page 321 for additional configuration information.
• You may also change the default port that the CMS or WCS uses to listen for
initial communications from the Configuration tab of the Properties dialog in
the Crystal Configuration Manager.
372
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Overview of Crystal Enterprise and firewall configuration
By default Crystal Enterprise uses dynamically chosen port numbers for
communications between components. You must change this default when you
place a stateful firewall that uses packet filtering or Network Address Translation
(NAT) between Crystal Enterprise components because these firewalls provide
protection by permitting communications from outside the firewall with only
specified addresses and ports inside the firewall.
To enable Crystal Enterprise to communicate across such a firewall, you must
configure its components to use fixed addresses and ports. Then you must
configure your firewall to allow communications to the services behind the
firewall using these addresses and ports.
The process is similar when you configure your Crystal Enterprise system to
communicate across SOCKS proxy filters. But Crystal Enterprise provides direct
support for SOCKS proxy filters, so you need only configure each component to be
aware of the location and type of the proxies that they communicate with.
Note: When this section mentions firewalling different Crystal Enterprise
components, it assumes that the components reside on separate computers. If the
components reside on the same computer, their communication is uninterrupted
by firewalls, and no additional configuration is required.
Typical firewall scenarios
If all users of your Crystal Enterprise system are on your internal network, there is no
need to perform any special configuration of your firewalls or of Crystal Enterprise.
Simply place all Crystal Enterprise components on computers inside your firewall.
However, if you need to provide access to Crystal Enterprise to external users, you
must consider where to place each Crystal Enterprise component, and how to
configure both Crystal Enterprise and your firewalls in order to provide this access.
This section outlines in general terms the three most common firewall scenarios.
These scenarios are general cases: once you understand the firewalling issues
involved, you should be able to support Crystal Enterprise in wide variety of contexts.
Web Connector separated from the WCS by a firewall
In most cases, clients access protected information through a web server running
in a Demilitarized Zone (DMZ). A DMZ is a network area that is neither part of the
internal network nor directly part of the Internet. Typically, the DMZ is set up
between two firewalls: an outer firewall and an inner firewall.
The only Crystal Enterprise component that needs to provide direct service to
external clients is the Web Connector, which must be installed on the web server.
The most logical and secure way to position the web server and the Web Connector
is to place them in the DMZ. All the other Crystal Enterprise components can then
be placed on the internal network.
Crystal Enterprise Administrator’s Guide
373
Configuring Crystal Enterprise to work with firewalls
Note: The Web Connector is not used in any installation of Crystal Enterprise that
uses the Crystal Enterprise Java SDK. See “Application tier” on page 31 for more
information.
Application tier separated from the CMS by a firewall
You may chose to place your application server in the Demilitarized Zone (DMZ),
while placing the Crystal Management Server (CMS) and all other Crystal Enterprise
servers on the internal network. Crystal Enterprise requires that the CMS and the
remaining server components are not separated from one another by firewalls.
In a Windows installation of Crystal Enterprise, the Web Component Server (WCS)
acts as an application server. So this scenario also covers the case where the WCS
is in the DMZ.
Note:
• Placing your application server in the DMZ is less secure than placing it on
your internal network. For maximum security, you may prefer to place your
Crystal Enterprise application server on your internal network.
• The issues raised by separating the web server (and Web Connector) from the
WCS by a firewall are independent of the issues raised by firewalling the WCS
from the CMS. If you have a firewall in each location, you must consider the
configuration issues for each firewall independently, and perform both sets of
configuration.
Thick client separated from the CMS by a firewall
You can publish reports or analytic objects to Crystal Enterprise by saving these
objects to Crystal Enterprise from within Crystal Reports or Crystal Analysis, or by
using the Crystal Import Wizard or Crystal Publishing Wizard. However, if there
is a firewall between the computer running one of these thick clients and the
Crystal Management Server (CMS), this operation fails. You must configure your
CMS, your File Repository Servers, and your firewall if you want to support this
network configuration.
Configuring Crystal Enterprise to work with firewalls
This section gives practical step -by-step instructions for configuring your Crystal
Enterprise system to work in a firewalled environment. For a conceptual overview
of communications between Crystal Enterprise components and of supported
firewall configurations, see “Understanding Crystal Enterprise and firewall
integration” on page 371.
Note: If you have multiple Crystal Enterprise servers of a given type, the overall
procedure for configuring your system to work with firewalls will not change.
Configure each server as described in the section that describes your firewall
environment, and then specify a firewall rule for the server.
374
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Configuring for Network Address Translation
If you use Network Address Translation (NAT) only on the outer firewall of the
DMZ, then no special configuration is required for Crystal Enterprise to
communicate properly. However, if you separate Crystal Enterprise components
using NAT, you need to configure these components to communicate properly
through the firewall.
Note: You can configure Crystal Enterprise to communicate properly across NAT
firewalls that use static IP translation; however, Crystal Enterprise cannot
communicate across a firewall whose IP translation is dynamic.
Web Connector separated from the WCS by NAT
When the Web Connector (WC) is in the DMZ, you must configure the Web
Connector to make initial contact with the Web Component Server (WCS) using a
specific hostname and port number.
Next you must configure the WCS to respond appropriately to communications
from the Web Connector. This is accomplished using the following command
-port FQDN:6401 -requestport fixed
The -port command configures the WCS to listen for contact from the WC on the
specified port (6401 is the default value). If a value is specified, -port also
configures the WCS to send the WC an externally routable, fully qualified domain
name (FQDN) for the WC to use when communicating with the WCS in subsequent
interchanges. You must specify this FQDN when the Web Connector and the WCS
are separated by a firewall that uses Network Address Translation. Otherwise the
WCS sends the WC an internal address for subsequent communications, and the
WC cannot communicate with the WCS through the firewall.
The -requestport command is used to configure the WCS to use a fixed port
number for all subsequent communications with the WC. When the WC and WCS
are separated by a firewall that uses NAT, you must specify this port number. You
can use any free port number for fixed.
Finally, you must configure your firewall to allow communications that use the
addresses and ports that you’ve specified.
To configure the Web Connector on Windows
1 Start the CCM.
2 Stop the World Wide Web Publishing Service.
3 On the toolbar, click Configure web connector.
4 In the Web Component Servers area, click Add.
If your WCS Host Name is already listed, select it and click Edit.
5 In the WCS Host Name field, type the name of the machine that is running the
WCS. This machine must be routable from the web server that is running the
Web Connector.
Crystal Enterprise Administrator’s Guide
375
Configuring Crystal Enterprise to work with firewalls
6 If you have customized the WCS so that it listens on a port other than the default,
type your new port number in the Port field. Otherwise, ensure that the default
port number (6401) appears.
7 Click OK twice to return to the CCM.
8 Start the World Wide Web Publishing Service.
To configure the Web Connector on UNIX
If your web server is running on UNIX, stop the web server and then set the WCSHOST
or WCSHosts variable to the name of the machine that is running the WCS. This
machine must be routable from the web server that is running the Web Connector.
The WCSHOST or WCSHosts variable is defined in the configuration file that corresponds
to your web server. For details about each configuration file, see Crystal Enterprise
Installation Guide.
To configure the WCS
1 Start the CCM.
2 Stop the Crystal Web Component Server.
3 On the toolbar, click Properties.
4 In the Command box, add the following option:
-port FQDN:6401 -requestport portnum
For the -port command, replace FQDN with either the fully qualified domain
name of the machine that is running the WCS. This machine must be routable
from the web server that is running the Web Connector.
In the -requestport command, substitute any valid free port number for portnum.
5 If you want to customize the WCS so that it listens on a port other than the
default, substitute your new port number for the default value of 6401.
Tip: If you change the default port number of the WCS you must perform
additional system configuration. Before changing the port number, see
“Changing the default server port numbers” on page 321.
6 Click OK to return to the CCM.
7 Start the Crystal Web Component Server.
Specifying firewall rules when the WC is separated from the
WCS by NAT
For stateful firewalls (either packet filtering or NAT) that separate the Web
Connector and the WCS, you need only specify inbound firewall rules. For details
of how to specify these rules, consult your firewall documentation.
The fixed port number specified in the chart is the port number you specify for the
WCS using -requestport. See “To configure the WCS” on page 376 for details.
376
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Inbound Rules
Source
Computer
Destination
Port
Action
Computer
Port
Web Server (WC)
Any
WCS
6401
Allow
Web Server (WC)
Any
WCS
fixed
Allow
Any
Any
WCS
Any
Reject
Application tier separated from the CMS by NAT
The nature of communications between Crystal Enterprise components makes
configuring your Crystal Enterprise system relatively complex when you separate
the application server running your Crystal Enterprise Java SDK (or the WCS) from
your Crystal Management Server (CMS) using Network Address Translation (NAT).
In order to service client requests, the application server (or WCS) needs to
communicate with Crystal Enterprise servers. To initiate communications with a
Crystal Enterprise server, the application server (or WCS) first contacts the directory
listing service on the CMS. The CMS responds on a second port with the address
and port number of the requested service. The application server (or WCS) then uses
this address and port number to communicate directly with the requested service.
If the application server (or WCS) is separated from the CMS and other Crystal
Enterprise servers by NAT, we must ensure that whenever a Crystal Enterprise
server passes an address across the firewall to the application server (or WCS), it
passes a fully qualified domain name (FQDN) that is routable by the firewall.
To configure the CMS, use the following command
-port FQDN:6400 -requestport fixed
The -port command configures the CMS to listen for contact from the application
server (or WCS) on the specified port (6400 is the default value). If specified, -port
also configures the CMS to send the application server (or WCS) an externally
routable, fully qualified domain name (FQDN) for the application server to use
when communicating with the CMS in subsequent interchanges.
The -requestport command is used to configure the CMS to use a fixed port
number for all subsequent communications with the application server (or WCS).
You must specify this port number when the application server and CMS are
separated by a firewall using NAT. You can use any free port number for fixed.
Next you must ensure that the application server (or WCS) is able to communicate
with the other Crystal Enterprise servers. Because the application server (or WCS)
retrieves contact information for these servers from the CMS, you must force all
servers which may communicate with the WCS to register an externally routable
FQDN and a fixed port number with the CMS directory listing service. Enter the
command
-port FQDN -requestport fixed
Crystal Enterprise Administrator’s Guide
377
Configuring Crystal Enterprise to work with firewalls
on each server. Specify only a FQDN for the -port command. Do not specify a port
number. In the -requestport command, you can substitute any free port number for
fixed. If more than one Crystal Enterprise server is installed on a machine, you must
specify a unique port number for each Crystal Enterprise server on that machine.
Now you can configure the firewall rules to recognize and pass the traffic between the
application server (or WCS) and the Crystal Enterprise servers behind the firewall.
This does not finish the necessary configuration. Not all communications between
Crystal Enterprise components pass through the firewall. Servers behind the
firewall communicate with the CMS and with each other. However, once we
configure these servers to register an externally routable FQDN with the CMS, the
servers try to use these addresses to communicate with one another. Normally
these addresses are not routable on the internal network behind the firewall, so
these communications attempts will fail.
To work around this issue you must configure the hosts file on each machine to
recognize the hostname of every machine running a Crystal Enterprise server
behind the firewall. Alternately, you can set up a separate DNS server behind the
firewall that recognizes the FQDN and translates them to internal addresses.
Ports
In the simplest version of this scenario, all client applications are installed on a
single application server in the DMZ. These applications may include the Crystal
Enterprise web desktop, the Crystal Management Console (CMC), and your own
custom applications. In this case, the application layer must be able to
communicate with every Crystal Enterprise server behind the firewall. You must
open a port on the firewall for each server.
You may wish to limit the number of ports that you open on your firewall. One
way to do this is to place fewer client applications in the DMZ. An client
application that supports only report viewing needs to communicate with the:
• Cache Server
• Crystal Management Server (CMS)
• Input File Repository Server (FRS)
• Output FRS
• Report Application Server (if users can access the Advanced DHTML viewer)
The CMC must be able to access every Crystal Enterprise server. Therefore, if the
application server hosting the CMC is separated from the CMS by a firewall, you
must open a port on the firewall for each server.
Configuring the CMS
To configure the CMS on Windows
1 Start the CCM.
2 Stop the Crystal Management Server.
378
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
3 On the toolbar, click Properties.
4 In the Command box, add the following option:
-port FQDN:6400 -requestport portnum
For the -port command, replace FQDN with the fully qualified domain name of
the machine that is running the CMS. This machine must be routable from the
application server or WCS.
For the -requestport command, substitute any valid free port number for portnum.
5 If you want to customize the CMS so that it listens on a port other than the
default, substitute your new port number for the default value of 6400.
Tip: If you change the default port number of the CMS you must perform
additional system configuration. Before changing the port number, see
“Changing the default server port numbers” on page 321.
6 Click OK to return to the CCM.
7 Start the Crystal Management Server.
To configure the CMS on UNIX
1 Run ccm.sh.
By default the script and the ccm.config file are installed in the Crystal install
directory, for example /export/home/crystal.
2 Stop the Crystal Management Server.
3 Edit the ccm.config file to insert the following command line:
-port FQDN:6400 -requestport portnum
For the -port command, replace FQDN with the fully qualified domain name of
the machine that is running the CMS. This machine must be routable from the
application server.
For the -requestport command, substitute any valid free port number for portnum.
4 Use ccm.sh to start the Crystal Management Server.
Configuring the Crystal Enterprise servers behind the firewall
To configure Crystal Enterprise servers on Windows
1 Start the CCM.
2 Stop the server.
3 On the toolbar, click Properties.
4 In the Command box, add the following option:
-port FQDN -requestport portnum
For the -port command, replace FQDN with the fully qualified domain name of
the machine that is running the server. This machine must be routable from the
application server or WCS.
Crystal Enterprise Administrator’s Guide
379
Configuring Crystal Enterprise to work with firewalls
For the -requestport command, substitute any valid free port number for
portnum. If more than one server is installed on the same machine, each server
on that machine must use a unique port number.
5 Click OK to return to the CCM.
6 Start the server.
7 Repeat for each Crystal Enterprise server.
To configure other Crystal Enterprise servers on UNIX
1 Run ccm.sh.
By default the script and the ccm.config file are installed in the Crystal install
directory, for example /export/home/crystal.
2 Stop the server.
3 Edit the ccm.config file to insert the following command line:
-port FQDN -requestport portnum
For the -port command, replace FQDN with the fully qualified domain name of
the machine that is running the server. This machine must be routable from the
application server.
For the -requestport command, substitute any valid free port number for
portnum. If more than one server is installed on the same machine, each server
on that machine must use a unique port number.
4 Use ccm.sh to start the server.
5 Repeat for each Crystal Enterprise server.
Configuring the hosts file of Crystal Enterprise servers
To configure the hosts files on Windows
You must configure the hosts file on every machine running a Crystal Enterprise
server so that the server can map the externally routable FQDN it receives from the
Crystal Management Server (CMS) to an internally routable IP address. This is
necessary to enable communications between servers inside the firewall.
1 Open the hosts file using a text editor like Notepad. The hosts file is located at
\WINNT\system32\drivers\etc\hosts.
2 Follow the instructions in the hosts file to add an entry for each machine
behind the firewall that is running a Crystal Enterprise server or servers. Use
the internally routable IP address of the machine and its externally routable
fully qualified domain name.
3 Save the hosts file.
To configure the hosts files on UNIX
You must configure the hosts file on every machine running a Crystal Enterprise
server so that the server can map the externally routable FQDN it receives from the
380
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Crystal Management Server (CMS) to an internally routable IP address. This is
necessary to enable communications between servers inside the firewall.
Note: Your UNIX operating system must be configured to first consult the hosts
file to resolve domain names, before consulting DNS. Consult your UNIX systems
documentation for details.
1 Open the hosts file using an editor like vi. The hosts file is located at \etc\hosts.
2 Add an entry for each machine behind the firewall that is running a Crystal
Enterprise server or servers. Use the internally routable IP address of the
machine and its externally routable fully qualified domain name.
3 Save the hosts file.
Specifying firewall rules when the application tier is separated
from the CMS by NAT
Stateful firewalls (packet filtering or NAT) need inbound access rules when there
is a firewall between the Application Tier (application server running the Crystal
Enterprise Java SDK or the WCS) and the other Crystal Enterprise servers. One
outbound rule is also needed because the WCS may register listeners on the servers
behind the firewall. These listeners may initiate communication with the WCS.
For details of how to specify these rules, consult your firewall documentation.
The fixed port numbers specified in the chart are the port numbers you specify for
servers using -requestport. See “Configuring the CMS” on page 378, and
“Configuring the Crystal Enterprise servers behind the firewall” on page 379 for
details.
Inbound Rules
Source
Destination
Action
Computer
Port
Computer
Port
WCS or application
server
Any
CMS
6400
Allow
WCS or application
server
Any
CMS
fixed
Allow
WCS or application
server
Any
fixed
Other Crystal
Enterprise server
Allow
Any
Any
CMS
Any
Reject
Any
Any
Other Crystal
Any
Enterprise Server
Reject
Note: There must be one inbound firewall rule for each Crystal Enterprise server
behind the firewall. Whenever more than one server is installed on the same
machine, each server on that machine must use a unique port number.
Crystal Enterprise Administrator’s Guide
381
Configuring Crystal Enterprise to work with firewalls
Outbound Rules
Source
Computer
Destination
Port
Machines hosting
Any
Crystal Enterprise server
Computer
Action
Port
WCS or
Any
application server
Allow
This outbound rule is needed because the WCS may register listeners on servers
behind the firewall. These listeners may initiate communication with the WCS.
Thick client separated from the CMS by NAT
You can publish reports or analytic objects to Crystal Enterprise by saving these
objects to Crystal Enterprise from within Crystal Reports or Crystal Analysis, or by
using the Crystal Import or Publishing Wizards. However, if there is a firewall
between the computer running one of these thick clients and the Crystal
Management Server (CMS), this operation fails.
Configuring your Crystal Enterprise system to support this configuration when
the firewall uses Network Address Translation (NAT) is very similar to
configuring your system to support a NAT firewall between the application tier
and the Crystal Management Server (CMS).
First you must configure the CMS and the Input File Repository Serve to use
externally routable fully qualified domain names (FQDN) and fixed port numbers
for communications. Next you must configure the hosts file on every machine
behind the firewall that runs a Crystal Enterprise server so that the servers can map
these externally routable FQDN to internally routable IP addresses (including the
application server, if it is on the same side of the firewall as the CMS). Finally you
must alter your firewall rules to facilitate communication across the firewall using
the fixed addresses and ports that you have specified.
Note: Instead of configuring the hosts files, you may wish to set up a separate
DNS server behind the firewall to recognize the FQDN and translate them to
internal addresses.
For full instructions, follow the detailed steps in “Application tier separated from
the CMS by a firewall” on page 374 but:
• Configure only the Crystal Management Server and the Input File Repository
Server.
• Establish inbound firewall rules for communication between the Crystal
Reports or Crystal Analysis machine and the CMS and Input File Repository
Server. You do not need to establish an outbound firewall rule.
382
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Configuring for packet filtering
If you use packet filtering only on the outer firewall of the DMZ, then no special
configuration is required for Crystal Enterprise to communicate properly.
However, if you separate Crystal Enterprise components using packet filtering,
you need to configure them to communicate properly through the firewall.
Web Connector separated from the WCS by packet filtering
When the Web Connector is in the DMZ, you must configure the Web Connector
to make initial contact with the Web Component Server (WCS) using a specific
hostname and port number.
Next you must configure the WCS to respond appropriately to communications
from the Web Connector (WC). This is accomplished using the following command:
-requestport fixed
The -requestport command is used to configure the WCS to use a fixed port
number for all subsequent communications with the WC. When the WC and WCS
are separated by a firewall that uses packet filtering, you must specify this port
number. You can use any free port number for fixed.
Finally, you must configure your firewall to allow communications using the
addresses and ports that you’ve specified.
To configure the Web Connector on Windows
1 Start the CCM.
2 Stop the World Wide Web Publishing Service.
3 On the toolbar, click Configure web connector.
4 In the Web Component Servers area, click Add.
If your WCS Host Name is already listed, select it and click Edit.
5 In the WCS Host Name field, type the name of the machine that is running the
WCS. This machine must be routable from the web server that is running the
Web Connector.
6 If you have customized the WCS so that it listens on a port other than the default,
type your new port number in the Port field. Otherwise, ensure that the default
port number (6401) appears.
7 Click OK twice to return to the CCM.
8 Start the World Wide Web Publishing Service.
Crystal Enterprise Administrator’s Guide
383
Configuring Crystal Enterprise to work with firewalls
To configure the Web Connector on UNIX
If your web server is running on UNIX, stop the web server and then set the WCSHOST
or WCSHosts variable to the name of the machine that is running the WCS. This
machine must be routable from the web server that is running the Web Connector.
The WCSHOST or WCSHosts variable is defined in the configuration file that
corresponds to your web server. For details about each configuration file, see
Crystal Enterprise Installation Guide.
To configure the WCS
1 Start the CCM.
2 Stop the Crystal Web Component Server.
3 On the toolbar, click Properties.
4 In the Command box, add the following option:
-requestport portnum
Substitute any free port number for portnum.
5 Click OK to return to the CCM.
6 Start the Crystal Web Component Server.
Specifying firewall rules when the WC is separated from the
WCS by packet filtering
Stateful firewalls (packet filtering or NAT) need only inbound access rules to allow
the Web Connector and the WCS to communicate. For details of how to specify
these rules, consult your firewall documentation.
The fixed port number specified in the chart is the port number you specify for the
WCS using -requestport. See “To configure the WCS” on page 384 for details.
Inbound Rules
Source
Computer
384
Destination
Port
Action
Computer
Port
Web Server (WC)
Any
WCS
6401
Allow
Web Server (WC)
Any
WCS
fixed
Allow
Any
Any
Any
Any
Reject
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Application Tier separated from CMS by packet filtering
If your firewall performs packet filtering, you must configure every server inside
the inner firewall to respond to communications from the WCS or application
server on a fixed port. This means configuring the CMS, and every other Crystal
Enterprise server, with the following command line:
-requestport portnum
The argument of the -requestport command must specify a fixed port number. You
can specify any free port number for portnum. If more than one server is installed
on the same machine, each server on that machine must use a unique port number.
You must then configure your packet filtering firewall to pass traffic to the default
CMS port (6400), and each of the communications ports you specified using
-requestport.
To configure Crystal Enterprise servers on Windows
1 Start the CCM.
2 Stop the first server.
3 On the toolbar, click Properties.
4 In the Command box, add the following option:
-requestport portnum
For the -requestport command, substitute any valid free port number for
portnum. If more than one server is installed on the same machine, each server
on that machine must use a unique port number.
Tip: If you want to customize the CMS so that it listens on a port other than the
default, also add -port 6400 to the command line, substituting your new port
number for the default value of 6400.
If you change the default port number of the CMS you must perform additional
system configuration. Before changing the port number, see “Changing the
default server port numbers” on page 321.
5 Click OK to return to the CCM.
6 Start the server.
7 Repeat for each Crystal Enterprise server behind the firewall.
To configure other Crystal Enterprise servers on UNIX
1 Run ccm.sh.
By default the script and the ccm.config file are installed in the Crystal install
directory, for example /export/home/crystal.
2 Stop the server.
Crystal Enterprise Administrator’s Guide
385
Configuring Crystal Enterprise to work with firewalls
3 Edit the ccm.config file to insert the following command line:
-requestport portnum
For the -requestport command, substitute any valid free port number for
portnum. If more than one server is installed on the same machine, each server
on that machine must use a unique port number.
Tip: If you want to customize the CMS so that it listens on a port other than the
default, also add -port 6400 to the command line, substituting your new port
number for the default value of 6400.
If you change the default port number of the CMS you must perform additional
system configuration. Before changing the port number, see “Changing the
default server port numbers” on page 321.
4 Use ccm.sh to start the server.
5 Repeat for each Crystal Enterprise server.
Specifying firewall rules when the application server is separated
from the CMS by packet filtering
Stateful firewalls (packet filtering or NAT) need the following inbound access rules
when there is a firewall between the Application Tier (WCS or application server)
and the rest of the Crystal Enterprise servers. Note that the WCS may register
listeners with any of the CE servers, so one outbound access rule is also needed.
For details of how to specify these rules, consult your firewall documentation.
The fixed port numbers specified in the chart are the port numbers you specify for
the CMS and other Crystal Enterprise servers using -requestport. See “Application
Tier separated from CMS by packet filtering” on page 385 for details.
Inbound Rules
Source
Computer
Destination
Port
Action
Computer
Port
WCS or application server
Any
CMS
6400
Allow
WCS or application server
Any
CMS
fixed
Allow
WCS or application server
Any
Other Crystal
Enterprise server
fixed
Allow
Any
Any
CMS
Any
Reject
Any
Any
Other Crystal
Enterprise servers
Any
Reject
Note: There must be an inbound firewall rule for each Crystal Enterprise server
behind the firewall. Whenever more than one server is installed on the same
machine, each server on that machine must use a unique port number.
386
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
Outbound Rules
Source
Destination
Action
Computer
Port
Computer
Port
Machines hosting Crystal
Enterprise server
Any
WCS or application Any
server
Allow
This outbound rule is needed because the WCS may register listeners on servers
behind the firewall. These listeners may initiate communication with the WCS.
Thick client separated from the CMS by packet filtering
You can publish reports or analytic objects to Crystal Enterprise by saving these objects
to Crystal Enterprise from within Crystal Reports or Crystal Analysis, or by using the
Crystal Import or Publishing Wizards. However, if there is a firewall between the
computer running one of these thick clients and the CMS, this operation fails.
Configuring your Crystal Enterprise system to support this configuration when
the firewall uses packet filtering is very similar to configuring your system to
support a packet filtering firewall between the application tier and the Crystal
Management Server (CMS).
First you must configure the CMS and the Input File Repository Server to use fixed
port numbers for communications. Next you must alter your firewall rules to facilitate
communication across the firewall using the fixed ports that you have specified.
For full instructions, follow the detailed steps in “Application Tier separated from
CMS by packet filtering” on page 385 but:
• Configure only the Crystal Management Server and the Input File Repository
Server.
• Establish inbound firewall rules for communication between the Crystal
Reports or Crystal Analysis machine and the CMS and Input File Repository
Server. You do not need to establish an outbound firewall rule.
Configuring for SOCKS servers
Crystal Enterprise provides direct support for SOCKS proxy server firewalls on
Windows installations that use the Crystal Enterprise COM SDK. The required
configuration depends on the location of your SOCKS server. Your SOCKS server(s)
may separate the Web Connector from the Web Component Server (WCS) and/or
they may separate the WCS from the Crystal Management Server (CMS).
There is limited support of SOCKS for the UNIX installation of Crystal Enterprise,
or for a Windows installation that uses the Crystal Enterprise Java SDK. You can
configure the Web Component Adapter to communicate through a SOCKS server,
but the Java SDK has no support for SOCKS. Therefore you may be able to
configure your system to support a custom CSP application and SOCKS, but you
cannot use JSP pages through a SOCKS firewall.
Crystal Enterprise Administrator’s Guide
387
Configuring Crystal Enterprise to work with firewalls
This list describes when to use the procedures that are provided in the remainder
of this section:
• Configuring the WCS for SOCKS servers
If your installation includes a WCS, complete these steps regardless of the
location of your SOCKS server(s).
• Configuring the Web Connector for SOCKS servers
Complete these steps if one or more SOCKS servers separate the Web Connector
from the WCS.
• Configuring the CMS for SOCKS Servers
Complete these steps if one or more SOCKS servers separate the WCS (or WCA)
from the CMS.
• Configuring the WCA for SOCKS servers
When configuring your WCA for SOCKS, complete these steps regardless of
the location of your SOCKS server(s).
Crystal Enterprise requires that the CMS and the remaining server components are
not separated from one another by firewalls. The remaining server components
automatically obtain their SOCKS configuration from the CMS, as required, so you
don’t need to configure them separately.
Configuring the WCS for SOCKS servers
Complete these steps if one or more SOCKS servers separate the WCS from the
Web Connector, from the CMS, or from both. These steps provide the WCS with
the required information about each SOCKS server, in order, from the outermost
to the innermost.
The outermost SOCKS server is the one closest to the Web Connector. The
innermost SOCKS server depends on whether or not a SOCKS server separates the
WCS from the CMS:
• If no SOCKS servers separate the WCS from the CMS, then the innermost
SOCKS server is the first SOCKS server that the WCS connects to when
communicating with the Web Connector.
• If a SOCKS server separates the WCS and the CMS, then the innermost SOCKS
server is the last SOCKS server the WCS communicates with before the CMS.
To configure the WCS on Windows
1 Start the CCM.
2 Stop the Web Component Server.
3 Select the Web Component Server and, on the toolbar, click Properties.
4 On the Configuration tab, click Specify SOCKS; then click Add.
5 In the SOCKS Proxy dialog box, type the Server Name or IP Address of your
SOCKS server.
388
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
6 In the Server Port field, type the number of the port that the SOCKS server is
listening on.
7 Select the SOCKS version that you are running (Ver 4 or Ver 5).
If you are using version 5 and you would like to secure access to the server, select
the authentication check box, and then enter your user name and password.
8 Click OK.
If you have more than one SOCKS server, repeat steps 4 to 8 for each additional
server. Then click Up and Down to order the SOCKS servers from the
outermost (closest to the Web Connector) to the innermost (closest to the CMS).
9 Click OK in all three dialog boxes to return to the CCM.
10 Start the Web Component Server.
Configuring the Web Connector for SOCKS servers
Complete these steps if the Web Connector must communicate through a SOCKS
server when it sends information to the WCS. (You must also configure the WCS
to communicate through the SOCKS server. See “Configuring the WCS for SOCKS
servers” on page 388.)
To configure the Web Connector on Windows
1 Start the CCM.
2 Stop the World Wide Web Publishing Service.
3 On the toolbar, click Configure web connector.
4 In the Web Component Servers area, click Add.
If your WCS Host Name is already listed, select it and click Edit.
5 In the WCS Host Name field, type the name of the machine that is running the
WCS.
6 If you have customized the WCS so that it listens on a port other than the default,
type your new port number in the Port field. Otherwise, ensure that the
default port number (6401) appears.
7 Click Specify SOCKS, then click Add.
8 In the SOCKS Proxy dialog box, type the Server Name or IP Address of your
SOCKS server.
9 In the Server Port field, type the number of the port that the SOCKS server is
listening on.
10 Select the SOCKS version that you are running (Ver 4 or Ver 5).
If you are using version 5 and you would like to secure access to the server, select
the authentication check box, and then enter your user name and password.
Crystal Enterprise Administrator’s Guide
389
Configuring Crystal Enterprise to work with firewalls
11 Click OK.
If more than one SOCKS server separates the Web Connector from the WCS,
repeat steps 7 to 11 for each SOCKS server. Then click Up and Down to order
the SOCKS servers. The SOCKS server closest to the Web Connector must
appear at the top of the list, and the SOCKS server closest to the WCS must be
at the bottom of the list.
12 Click OK in all three dialog boxes to return to the CCM.
13 Start the World Wide Web Publishing Service.
To configure the Web Connector on UNIX
If your web server is running on UNIX, you must stop the web server and then
modify the definition of the Crystal Enterprise WCSHOST or WCSHosts variable. This
variable is defined in the configuration file that corresponds to your web server.
Depending on the web server and Web Connector you are using, the environment
variable is typically defined in one of these files:
Web Server
Path
Apache with ASAPI
crystal/enterprise/platform/wcs/conf/asapi.conf
iPlanet 6 with NSAPI
In the iPlanet magnus.conf file.
iPlanet 7 with NSAPI
In the iPlanet init.conf file.
Any web server with CGI
crystal/enterprise/platform/wcs/bin/wcscgi.cgi
For more information about the configuration files for your web server, see the
section on Web Connectors in the Crystal Enterprise Installation Guide.
The syntax that denotes the WCS through a SOCKS server can be considerably
complex. This section shows a complete connection string and then describes its
component parts. The complete connection string for specifying the WCS through
a SOCKS server is as follows:
socks://Version;User:Password@SOCKSServer:Port/WCSmachine:Port
This string consists of two main parts: the SOCKS connection information
(Version;User:Password@SOCKSServer:Port) followed by the WCS destination
(WCSmachine:Port). The variable components in this string are as follows:
• Version is the SOCKS version in use (4 or 5).
• User is a SOCKS user name of length < 256 characters.
• Password is the corresponding password of length < 256 characters.
• SOCKSServer:Port is the name or IP4 of the SOCKS server, along with its port.
• WCSmachine:Port is the name or IP4 of the WCS, along with its port.
For example, suppose that you are running SOCKS version 5 on a server called
socksmachine. You need to provide the user name socksuser and the password
secret to connect to a WCS named sales1. The WCS is listening on its default port
390
Crystal Enterprise Administrator’s Guide
19: Working with Firewalls
(6401). In this case, in the configuration file appropriate to your web server, you
would type the following definition for the WCSHOST or WCSHosts variable:
socks://5;socksuser:secret@socksmachine/sales1:6401
To specify a sequence of SOCKS servers, list them in the connection string by
preceding each additional SOCKS server with the ampersand symbol (&), as follows:
socks://Version;User:Password@SOCKSServer1:Port&Version;User:Password@
SOCKSServer2:Port/WCSmachine:Port
Configuring the CMS for SOCKS Servers
Complete these steps if one or more SOCKS servers separate the application server
or WCS from the CMS. The remaining Crystal Enterprise servers automatically
obtain their SOCKS configuration from the CMS, as required, so you don’t need to
configure them separately.
To configure the CMS on Windows
1 Start the CCM.
2 Stop all of the Crystal servers, including the Crystal Management Server.
3 Select the CMS and, on the toolbar, click Properties.
4 On the Connection tab, click Add.
5 In the SOCKS Proxy dialog box, type the Server Name or IP Address of your
SOCKS server.
6 In the Server Port field, type the number of the port that the SOCKS server is
listening on.
7 Select the SOCKS version that you are running (Ver 4 or Ver 5).
If you are using version 5 and you would like to secure access to the server, select
the authentication check box, and then enter your user name and password.
8 Click OK.
If you have more than one SOCKS server, repeat steps 4 to 8 for each additional
server. Then click Up and Down to order the SOCKS servers from the outermost
(closest to the application server or Web Component Server) to the innermost
(closest to the CMS).
9 Click OK in all three dialog boxes to return to the CCM.
10 Start the Crystal Enterprise server components.
To configure the CMS on UNIX
The UNIX version of Crystal Enterprise includes a utility that allows you to
configure Crystal Enterprise servers to work with SOCKS servers. For details, see
“sockssetup.sh” on page 440.
Crystal Enterprise Administrator’s Guide
391
Configuring Crystal Enterprise to work with firewalls
Configuring the WCA for SOCKS servers
Complete these steps if one or more SOCKS servers separates the Web Component
Adapter (WCA) from the Crystal Management Server (CMS). These steps provide
the WCA with the required information about each SOCKS server, in order, from
the outermost to the innermost.
The outermost SOCKS server is the one closest to the web server. The innermost
SOCKS server is the last SOCKS server that the WCA communicates with before
the CMS.
To configure the WCA on UNIX
The UNIX version of Crystal Enterprise includes a utility that allows you to
configure Crystal Enterprise servers and the WCA to work with SOCKS servers.
For details, see “sockssetup.sh” on page 440.
To configure the WCA on Windows
To configure the WCA, you must edit the web.xml deployment descriptor file
associated with the webcompadapter.war to insert a SOCKS URI (universal resource
identifier). This URI tells your WCA how to contact the CMS through your SOCKS
server(s).
The syntax that denotes the CMS through a SOCKS server can be considerably
complex. For an example of how to construct a SOCKS URI, see “To configure the
Web Connector on UNIX” on page 390.
Then see “Configuring the Web Component Adapter” on page 282 for details on
editing web.xml.
392
Crystal Enterprise Administrator’s Guide
General Troubleshooting
20
This chapter provides general troubleshooting steps and
solutions to some specific configuration problems. For upto-date answers to commonly asked questions, registered
customers can freely download additional technical
documents or knowledge base articles from:
http://support.crystaldecisions.com
For more information on Product Registration and Crystal
Care technical support, see “Crystal Care technical
support” on page 7.
Crystal Enterprise Administrator’s Guide
393
Troubleshooting overview
Troubleshooting overview
Crystal Enterprise is designed to integrate with a multitude of different operating
systems, web servers, network and firewall configurations, database servers, and
reporting environments. Thus, any troubleshooting that you may need to
undertake will likely reflect the particularities of your deployment environment.
This chapter includes general troubleshooting steps along with solutions to some
specific configuration issues.
In general, consider the following key points when troubleshooting:
• Ensure that client and server machines are running supported operating
systems, database servers, database clients, and appropriate server software.
For details, consult the Platforms.txt file, included with your product
distribution.
• Verify that the problem is reproducible, and take note of the exact steps that
cause the problem to recur.
On Windows NT/2000, use the sample reports and sample data included with
the product to confirm whether or not the same problem exists.
• Determine whether the problem is isolated to one machine or is occurring on
multiple machines. For instance, if a report fails to run on one processing
server, see if it runs on another.
If the problem is isolated to one machine, pay close attention to any
configuration differences in the two machines, including operating system
versions, patch levels, and general network integration.
• If the problem relates to connectivity or functionality over the Web, check that
Crystal Enterprise is integrated properly with your web environment. For
details, see Crystal Enterprise Installation Guide and “Web accessibility issues”
on page 396.
• If the problem relates to report viewing or report processing, verify your
database connectivity and functionality from each of the affected machines.
Use Crystal Reports to verify that the report can be viewed properly. If the Job
or Page Servers are running on Windows, open the report in Crystal Reports
on the server machine and check that you can refresh the report against the
database. For details, see “Report viewing and processing issues” on page 398.
• Look for solutions in the documentation included with your product. For
details, see “Documentation resources” on page 395.
• Check out the Crystal Care technical support web site for white papers, files
and updates, user forums, and Knowledge Base articles:
http://support.crystaldecisions.com
394
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
Documentation resources
The Crystal Enterprise Release Notes are provided in two formats (release.pdf
and release.htm) in the root directory of your product distribution, as is the
Platforms.txt file. These documents list supported third-party software along
with any known issues or implementation-specific configuration details.
Crystal Enterprise also includes a number of manuals:
• Crystal Enterprise Getting Started Guide
• Crystal Enterprise Administrator’s Guide
• Crystal Enterprise User’s Guide
• Crystal Enterprise Installation Guide
• Business Views Administrator's Guide
• Crystal Enterprise documentation:
• Crystal Enterprise COM SDK Guide (CE_SDK.chm)
• Report Application Server COM SDK Guide (RAS_SDK.chm)
• Viewer COM SDK Guide (Report_Viewers.chm)
• Crystal Enterprise Java SDK Guide
• Report Application Server Java SDK Guide
• Viewer Java SDK Guide
CHM and PDF files are located in the doc directory of your product distribution.
Online HTML Help versions are installed with the Web Connector and the Web
Component Server. Access the HTML versions from the Crystal Enterprise
Launchpads, or look in the appropriate directory on your Web Connector or Web
Component Server machine:
• On Windows, the files are installed by default below the C:\Program
Files\Crystal Decisions\Web Content\Enterprise10\Help\ directory of your
installation.
• On UNIX, the files are installed below the INSTALL_ROOT/crystal/webcontent/
enterprise10/help/ directory of your installation.
Additional Compiled HTML Help (CHM) files are provided with the following
client tools:
• Crystal Configuration Manager
• Crystal Publishing Wizard
• Crystal Repository Migration Wizard
• Crystal Import Wizard
• Crystal Offline Viewer
Press F1 or click Help to launch the online help from within these applications.
Crystal Enterprise Administrator’s Guide
395
Web accessibility issues
Web accessibility issues
Using an IIS web site other than the default
On Windows, the Crystal Enterprise installation creates virtual directories on the
Internet Information Server (IIS) “Default Web Site.” If you are using a web site
other than the default, you must copy the virtual directory configuration from the
default web site to the web site you are using. Crystal Enterprise also sets up several
application mappings on the default site. These can be viewed and copied from the
default web site to the web site you are using. Restart the web server once you have
made these changes. For more information, see Crystal Enterprise Installation Guide.
UNIX Web Connector cannot access WCS on Windows
If you install any of the Web Connectors on a UNIX web server, and install the Web
Component Server (WCS) on Windows NT/2000, then you must ensure that the WCS
is not configured to use Windows NT Integrated security (NT Challenge/Response).
Until you disable this security, you can access the Crystal Enterprise Launchpads, but
you cannot access the Crystal Management Console (CMC) or the Crystal Enterprise
web desktop.
Note: Ensure also that you can ping the WCS machine by name from the UNIX
web server.
To disable Windows NT Integrated security
1 Start the Crystal Configuration Manager (CCM) on the WCS machine.
2 Stop the Crystal WCS, and then double-click it to view its Properties.
3 On the Configuration tab, clear the Use Windows NT Integrated Security
(NT Challenge/Response) check box; then click OK.
4 Start the Crystal WCS.
If you still cannot access the Crystal Enterprise web desktop or the CMC, check the
mappings between the web server, the Web Connector, and the WCS. For details,
see Crystal Enterprise Installation Guide.
Communication error when accessing the CMC
One of the more common errors encountered over the Web results in the following
error message being displayed in the browser:
Communication Error
Communication failed with all configured Web Component Servers because they
are disabled or not currently running. If this problem continues, please
contact the system administrator.
396
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
This error indicates that the WCS is offline or that the Web Connector is not
configured correctly. First, use the CCM to start the WCS and then enable it. (If the
WCS was already started and enabled, use the CCM to restart it.) If restarting the
WCS does not correct the situation, check the mappings between the web server, the
Web Connector, and the WCS. For details, see Crystal Enterprise Installation Guide.
Unable to connect to CMS when logging on to the CMC
If you attempt to log on to the CMC while the Crystal Management Server (CMS)
is not running, the following error message appears:
Unable to connect to CMS (<servername>) to retrieve cluster members. Logon
can not continue.
Use the CCM to start the CMS. (If the CMS was already started, use the CCM to
restart it.)
Windows NT authentication cannot log you on
When you attempt to log on to the Crystal Management Console (CMC) or to the
Crystal Enterprise web desktop, the following error occurs:
NT Authentication could not log you on. Please make sure your logon
information is correct. If your account is in any domain other than "DOMAIN
NAME" you must enter your user name as DomainName\UserName.
This error may occur for various reasons. Investigate these common solutions:
• Ensure that the specified authentication type corresponds to the user name
and password provided on the log on page. To log on with a Windows NT
user name, verify that the authentication type is set to Windows NT
Authentication and not Enterprise.
• Netscape users must provide a valid Windows NT user name in the form of
Domain\User.
• Microsoft Internet Explorer users must provide a valid Windows NT user
name. It must be in the form of Domain\User if the user account does not reside
in the default domain of the CMS.
• If Windows NT Integrated security (NT Challenge/Response) is enabled in
Internet Information Services (IIS) and in the Web Component Server (WCS),
then users must use Microsoft Internet Explorer. In addition, users must log on
to the client machine with a valid NT domain user account before logging on
to Crystal Enterprise. Users must log on to Crystal Enterprise with a valid
Windows NT user name. It must be in the form of Domain\User if the user
account does not reside in the default domain of the CMS.
• The web server and all Crystal Enterprise components must be running on
Windows NT/2000 for Windows NT authentication to work.
Crystal Enterprise Administrator’s Guide
397
Report viewing and processing issues
Report viewing and processing issues
When troubleshooting reports, it is especially useful to determine whether the
problem is isolated to one machine or is occurring on multiple machines. For
instance, if a report fails to run on one processing server, see if it runs on another.
If the problem is isolated to one machine, pay close attention to any configuration
differences in the two machines, including operating system versions, patch levels,
and general network integration.
In particular, check the database client configurations, the drivers and versions,
and the accounts under which the processing servers are running. If the reports are
based off ODBC data sources, compare the ODBC driver versions, the DSN
configurations, and the versions of the MDAC layer. Check to see if the Page Server
or Job Server is running under an account that has the appropriate access rights to
the report database server. If the report database server is on a remote machine,
change the Page Server or Job Server to use a valid domain account with enough
rights to view or process the report.
If you follow these steps and the problem persists, contact Crystal Care technical
support. Before you call, take note of the database client and version you are
running, the database server version that you are connecting to, and the driver
name and version that you are using to connect. For details, see “Crystal Care
technical support” on page 7.
Troubleshooting reports with Crystal Reports
On Windows, you can install Crystal Reports on all Job Server, Page Server, and
RAS machines in order to speed up the troubleshooting of reports and database
connectivity. In this way, you use Crystal Reports to simulate the steps that are
performed by the Crystal Enterprise processing servers when a scheduled report
is processed, or when a report is viewed on demand over the Web. By locating the
step where Crystal Reports is unable to open, refresh, or save the report, you may
be able to locate the source of the problem.
Note: The exact steps and menu options may differ, depending on your version of
Crystal Reports.
To troubleshoot a report
1 Start Crystal Reports on the appropriate machine:
• If the report runs successfully on demand, but fails when scheduled, start
Crystal Reports on the Job Server.
• If the report fails when viewed on demand, but runs successfully when
scheduled, start Crystal Reports on the Page Server.
• If the report fails when viewed on demand with the Advanced DHTML
viewer, start Crystal Reports on the RAS.
398
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
• If the report fails in all cases, first complete these troubleshooting steps on
one processing server; then verify whether or not the problem is resolved on
all processing servers. If not, repeat the steps on a different processing server.
2 Open the report from the CMS.
On the File menu, click Open. Click Enterprise Folders and log on to your CMS.
If you cannot open the report, verify network connectivity between the server
you are working on, the CMS, and the Input File Repository Server.
3 Test your database connection and authentication.
On the Database menu, click Log On/Off Server. If you cannot log on to the
database server, check the configuration of the database client software and
ensure that the report contains a valid database user name and password.
4 If the report’s parameters or record selection need to be modified by Crystal
Enterprise users when they schedule or view the report, change the parameter
values or record selection formula accordingly. If the values are invalid,
Crystal Reports will report an error.
5 Verify that the tables used in the report match the tables in the database.
On the File menu, clear the “Save Data with Report” check box. On the
Database menu, click Verify Database. Correct any issues reported by Crystal
Reports, and then save the report.
6 Refresh the report and, if current data is not returned from the database, check
these possible causes:
• If the report fails, ensure that the database credentials provide READ rights
to all tables in the report.
• If the database credentials are valid, the report’s SQL statement is evaluated at
this time. Check the join information. Note any ODBC errors that are produced.
• If the SQL statement is valid, data begins to return to Crystal Reports. As
this happens, the temporary files increase in size. Verify resource allocation
in case the machine is running out of memory or disk space.
7 Go to the last page of the report.
Crystal Reports will report any errors that it encounters within the report (such
as formulas, subreports, and other objects).
8 Export the report to Crystal Reports format (or any other desired format).
This step ensures that Crystal Reports is able to create temporary files that are
required in order to complete the processing of a report.
9 If the report now refreshes successfully, save it back to the CMS.
10 Close the report.
11 Close Crystal Reports.
12 Repeat the activity that caused the original report to fail: view the report on
demand over the Web, or schedule the report for processing.
Crystal Enterprise Administrator’s Guide
399
Report viewing and processing issues
Troubleshooting reports and looping database logon prompts
A common issue when viewing reports over the Web is a persistent database logon
prompt that is displayed repeatedly by the user’s browser. Regardless of the
credentials provided by the user, the report will not display. This problem is
typically caused by the configuration of the Page Server or the Report Application
Server (RAS). This section provides a series of troubleshooting steps that should
resolve this problem and others that are specific to reports and database connectivity.
To troubleshoot reports and looping database logon prompts
1 Verify the report with Crystal Reports.
Use Crystal Reports to verify the report. If you have the Crystal Reports
Designer installed on the Page Server, Job Server, or RAS machine, test
database connectivity by opening the report in Crystal Reports on the server.
For details, see “Troubleshooting reports with Crystal Reports” on page 398.
2 Change the server’s logon account.
Crystal Enterprise servers require access to various local and/or remote
resources and to the database server. Experience shows that running the Page
Server, Job Server, RAS, and Web Component Server (WCS) under a Domain
Administrator account allows them to access the components necessary to
connect successfully to data sources. To change a server’s logon account, see
“Configuring Windows processing servers for your data source” on page 313.
Tip: Running a background application under an Administrator account does
not inadvertently grant administrative privileges to another user, because users
cannot impersonate services.
3 Verify the server’s access to ODBC Data Source Names (DSNs).
Base reports off System DSNs (and not File or User DSNs), and set up each
System DSN identically on every Job Server, Page Server, and RAS machine
that will process the report.
If the report is based off an ODBC data source, the processing server must have
permission to access the corresponding DSN configuration. This information is
stored in the Windows registry. The Job Server, Page Server, and RAS require
Full Control or Special Access to the ODBC registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI
Consult your Windows documentation for information about working with the
registry. Additional configuration may be required, depending upon the
database that you are reporting off of. For details, see “Configuring Windows
processing servers for your data source” on page 313.
4 Determine the configuration of the database client software.
If you are not using ODBC, the database client software must be installed on
each machine that will process reports. On Windows, many database clients
store their configuration in the registry below HKEY_LOCAL_MACHINE.
400
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
If your database client stores its configuration below HKEY_CURRENT_USER, the
Crystal Enterprise services cannot use the database client software to
communicate with the database.
5 Verify the NTFS permissions granted to the Job Server, Page Server, and RAS.
Insufficient NTFS rights on the server may cause a number of problems to arise
when you view reports over the Web. As in step 2, changing each server’s logon
account to that of a Domain Administrator account should resolve such
problems. For the minimum set of NTFS permissions required by Crystal
Enterprise, see “Configuring NTFS Permissions” on page 419.
6 Check whether or not NT authentication is performed by the database.
If you report against a database that uses NT authentication for access control
(Microsoft SQL Server, Sybase, and so on), the Job Server, Page Server, and RAS
must run under a Windows NT/2000 domain user account that has access to
the appropriate database tables. (In this scenario, each server’s logon account
determines the level of access it is granted by the database. Crystal Enterprise
does not pass end-users’ NT tokens through to the database server.)
To retain the access control levels that are set up within the database, you can
instead change each ODBC DSN so that it implements SQL Server Login
instead of NT authentication.
7 Check the available environment variables.
Environment variables are used by the operating system to govern and manage
system files for particular users. On Windows, Crystal Enterprise servers are
generally most affected by the TMP and TEMP environment variables. Because the
servers are run as services, they cannot access the User Environment variables
that are created by default. Therefore, it is recommended that you create System
Environment variables if they do not already exist. Consult your Windows
documentation for details.
8 Reference remote data sources with UNC paths.
Ensure that servers have access to remote databases through UNC paths,
instead of through mapped drives. For example, if you design a report off a PC
database that resides on a network drive, ensure that the report references its
data source with the appropriate UNC path. For details, see “Ensuring that
server resources are available on local drives” on page 404.
9 Ensure that you have enough database client licenses.
If all database client licenses are in use, the Crystal Enterprise servers are unable
to retrieve data from the database.
10 Check that database connections are closed in a timely fashion.
If a database connection is not closed quickly, the database may not service
another request until the connection has been closed. To decrease the “Minutes
Before an Idle Job is Closed” setting, see “Modifying Page Server performance
settings” on page 304.
Crystal Enterprise Administrator’s Guide
401
Report viewing and processing issues
11 Use multi-threaded database drivers.
Multi-threaded database drivers allow the processing servers to connect to the
database without having to wait for the database to fulfill initial requests.
ODBC connections are typically recommended because they provide
multithreaded connections to the database. However, Crystal Reports now
includes a number of thread-safe native and OLEDB drivers. A list of these
thread-safe drivers is available in the Crystal Reports Release Notes.
12 Check for problems with particular data sources.
If your report is based on a Lotus Notes database, you may need to perform
additional configuration. Download the latest instructions from the Crystal
Care Knowledge Base.
IBM offers several client applications for connecting to DB2. The recommended
client is IBM DB2 Direct Connect, whose ODBC drivers were written for actual
programmatic interaction with products like Crystal Enterprise. See the Crystal
Care Knowledge Base for discussions of this and other DB2 clients.
If you encounter problems with any other specific data sources, check the
Knowledge Base for the latest information.
Error detected by database driver
When a processing server receives an unknown message from the database driver,
an error message similar to the following appears:
Error Detected By Database DLL
This section provides some common troubleshooting steps for resolving this issue.
Before completing these steps, verify your database connectivity and general
reporting configuration (as described in “Troubleshooting reports and looping
database logon prompts” on page 400).
To troubleshoot database driver errors
1 Verify the database drivers for consistency.
Ensure that the database driver (ODBC or native) used when the report was
designed in Crystal Reports matches the database driver that is installed on the
Job Server, Page Server, and RAS.
If the Job Server or the Page Server is installed on UNIX, then the database
driver will not match exactly (the UNIX version will be a .so file instead of a
.dll). However, the Windows/UNIX versions of each driver should correspond
in regards to version numbers or driver release.
2 Disable the report’s “Use Indexes or Server for Speed” option.
Open the report in Crystal Reports and, on the File menu, click Options. On the
Database tab, clear the “Use Indexes or Server for Speed” option. Disabling this
option may resolve database driver errors.
402
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
3 Verify the report’s SQL statement and ensure that it has not been edited manually.
Open the report in Crystal Reports and, on the Database menu, click Show SQL
Query. Copy the query into a text editor; then use your database server’s query
tool to run the query.
If the option appears in Crystal Reports, click Reset in the Show SQL Query dialog
box. Compare the regenerated query with the version displayed in your text
editor. If the queries differ, save the report so it uses the regenerated SQL query.
Note: If you need to edit a report’s SQL statement, do so with a stored
procedure, rather than by editing it manually. If you have developed a web
application that modifies the SQL statement through code, ensure that only
the WHERE clause is changed.
4 Ensure that null values are not being passed to subreports.
If the report contains one or more subreports, open it in Crystal Reports and, on the
File menu, click Report Options. Select the “Convert Database NULL Values to
Default” check box and the “Convert Other NULL Values to Default” check box.
5 If the report is based off on ODBC driver, enable tracing to obtain more
information about the error.
On Windows, ODBC tracing can be started through the ODBC Data Source
Administrator. On UNIX, similar tracing can be enabled in the system
information file (.odbc.ini).
Once you enable tracing, run the report again from a browser to generate the
tracing log. After you run the report, disable tracing and review the log file for
additional “Error” or “Busy” messages. Tracing may provide additional details
that allow you to troubleshoot the problem.
6 If the report is based off Informix 7.3, check the database driver.
If a report that uses the Informix database driver (Windows version) causes a
database driver error, modify the report to use the Crystal Reports “CR
Informix” driver.
7 Verify the table definition of the database that the report is based off.
If your web application dynamically changes a report’s data source at runtime,
ensure that the schema of each database matches the schema of the database that
the report was originally designed for. Rather than running the same report against
diverse data sources, consider designing a separate report for each database.
8 Verify the data type of parameter values passed through code.
If your web application passes parameter values to a report, ensure that you are
casting the correct data type for the parameter value. It is always a good idea to
cast values to ensure they are of the correct type. For specific details, see the
function reference for your development language.
Crystal Enterprise Administrator’s Guide
403
Report viewing and processing issues
Ensuring that server resources are available on local drives
When the Crystal Enterprise servers are running on Windows, many can be
configured to use specific directories to store files. For example, you can specify the
root directory for each File Repository Server, the temporary directories for the
Cache and Page Servers, or the directory from which the Job Servers load
processing extensions. In all cases, the directory that you specify must be on a local
drive (such as C:\InputFRS or C:\Cache). Do not use Universal Naming Convention
(UNC) paths or mapped drives.
Although some Crystal Enterprise servers can recognize and use UNC paths, do
not configure the servers to access network resources in this manner. Use local
drives instead, because UNC paths can limit performance due to limitations in the
underlying protocol.
Tip: If your report runs against a PC database that resides on a network drive, then
the report itself must reference its data source through a UNC path. In this case, the
service must run under a domain user account with network permissions. For details,
see “Configuring Windows processing servers for your data source” on page 313.
Similarly, if you configure a server to use a mapped drive, the server may appear
to function correctly. However, servers cannot access mapped resources when the
machine is restarted. Drives are mapped according to your user profile when you
log on to Windows NT/2000, but, once a drive is mapped, it is available to the
entire operating system. So, when you log on and map a local or network drive, the
mapped drive is accessible to the LocalSystem account, and hence to the Crystal
Enterprise servers running on the local machine. When you log off the local
machine, the servers may retain access to the mapped drive for some time
(Windows will release the drive mapping if no application maintains a persistent
connection to the mapped resource). However, when you restart the local machine,
the mapped drive is not restored until you log back on.
Note: Changing a server’s log on account from the LocalSystem account to a
Windows NT/2000 user account with network privileges will not resolve the
problem, because the servers do not actually log on to the network with that
account. Instead, the servers perform “account impersonation.” This provides
access to some profile-specific resources (such as printers and email profiles), but
not others (such as ODBC User Data Source Names and mapped drives).
Page Server error when viewing a report
When you attempt to run or preview a report, the following error message appears:
There are no Page Servers connected to the Cache Server or all the connected
Page Servers are disabled. Please try to reconnect later. [On Page Server :
<servername>.Cacheserver]
This error indicates that the Page Server is not started and enabled. Use the CCM
to start the Page Server and then enable it. (If the Page Server was already started
and enabled, use the CCM to restart it.)
404
Crystal Enterprise Administrator’s Guide
20: General Troubleshooting
Crystal Enterprise web desktop considerations
Supporting users in multiple time zones
Avoid granting Schedule access to the default Guest account if you deploy the Crystal
Enterprise web desktop for users in different time zones. Instead, ensure that each
user who is allowed to schedule reports has a dedicated account on the system, and
that each user's Crystal Enterprise web desktop preferences include the appropriate
time-zone setting. To view or modify the time-zone setting for any user account, use
the Preferences Manager, which is available as a Client Sample on the Crystal
Enterprise User Launchpad. Dedicated accounts are recommended because the
default Guest account does not allow users to modify account preferences that would
affect other users. For more information about using specific time-zone properties in
your custom web applications, see the Crystal Enterprise SDK documentation.
Setting default report destinations
By default, a report's destination that is set in the CMC will be the selected
destination when a report is scheduled in the Crystal Enterprise web desktop. A user
can also select alternate destinations in the web desktop by updating the Destination
option. Note that the destination set in the Crystal Enterprise web desktop applies
only to the scheduled instance. Thus, when a user schedules another instance in the
web desktop, the destination that is set in the CMC will be selected, unless the user
changes the Destination option. If the user selects the Default destination setting in
the web desktop, reports are processed on the Job Server and sent to the File
Repository Server. The Default destination setting in the Crystal Enterprise web
desktop is equivalent to the Default destination setting in the CMC.
Setting preferences and report viewers for Crystal Enterprise
web desktop users
The Preferences Manager enables you to set the default Crystal Enterprise
preferences for each user on the system. If users have their own accounts on the
system, they can modify their preferences when they log on to Crystal Enterprise.
If users access Crystal Enterprise anonymously—with the Guest account—you can
use this tool to set preferences, including the default report viewer. Users cannot
change their preferences when they are logged on under the Guest account.
The Preferences Manager is available as a Client Sample on the Crystal Enterprise
User Launchpad.
Crystal Enterprise Administrator’s Guide
405
Crystal Enterprise web desktop considerations
Crystal Enterprise web desktop and Windows Single Sign On
The Crystal Enterprise web desktop provides its own form of “anonymous Single
Sign On,” which uses Enterprise authentication, as opposed to Windows NT or
Windows AD authentication. Design your own web applications accordingly (or
modify the Crystal Enterprise web desktop) if you want to use NT Single Sign On
or AD Single Sign On. By default, when a user launches the Crystal Enterprise web
desktop, he or she will be automatically logged on using the Guest account
(Enterprise authentication). However, even when you disable the Sign Up feature,
the Crystal Enterprise web desktop is designed to display a logon page. With
Single Sign On enabled, the user can select Windows NT or Windows AD from the
Authentication list and click Log On without entering his or her user name or
password. For details about creating web applications that use Single Sign On, see
the developer documentation available on your product CD.
For details on configuring IIS and Crystal Enterprise for Windows NT Single Sign
On, see “Setting up NT Single Sign On” on page 83. For details on configuring IIS
and Crystal Enterprise for Windows AD Single Sign On, see “Using AD Single
Sign On” on page 102.
406
Crystal Enterprise Administrator’s Guide
Licensing Information
21
This chapter describes how to view licensing information
and add license keys with the Crystal Management Console
(CMC). It also shows how to view your current account
activity.
Crystal Enterprise Administrator’s Guide
407
Licensing overview
Licensing overview
Crystal Enterprise is a scalable product that provides you with the ability to add
license keys as the demand for report information increases in your organization.
You can purchase concurrent, named, and processor licenses. RAS Report
Modification licenses are also available.
Concurrent licenses specify the number of people who can connect to Crystal
Enterprise at the same time. This type of licensing is very flexible because a small
concurrent license can support a large user base. For example, a 100 user
concurrent license could support 250, 500, or 700 users depending on the frequency
with which the system is accessed and the number and size of the reports.
Named user licenses are associated with specific users and allow people to access
the system based on their user name and password. This provides named users
with access to the system regardless of how many other people are connected. You
may want to purchase named user licenses for people in your organization who
require access to Crystal Enterprise at all times. For example, you could purchase
a named user license for each of the 25 managers and a concurrent license for 175
general users.
Processor licenses are based on the number of processors that are running Crystal
Enterprise. To determine the number of processor licenses you require, count the
number of processors on any servers running any component of Crystal Enterprise
(except the Web Connector).
Crystal Enterprise Embedded or RAS Report Modification licenses enable the
Report Application Server’s Software Development Kit (SDK) for report-creation,
thereby providing you with tools for building your own web-based reporting and
query tools. In addition, these licenses add standard report-creation and reportmodification wizards to the Crystal Enterprise web desktop, so users can create
and modify reports over the Web in an ad hoc fashion.
Note: If you are upgrading from a trial version of the product, be sure to delete
the Evaluation key prior to adding any new license keys or product activation
keycodes.
For more information about licenses, sessions, and session handling see “Crystal
Enterprise Security Concepts” on page 45.
408
Crystal Enterprise Administrator’s Guide
21: Licensing Information
Accessing license information
The License Keys tab identifies the number of concurrent, named, and processor
licenses associated with each key.
1 Go to the License Keys management area of the CMC.
2 Select a license key.
The details associated with the key appear in the Licensing Information area. To
purchase additional license keys:
• Contact your Crystal Decisions sales representative.
• Call 1-800-877-2340 (US/Canada) or 1-604-681-3435 (International).
• Email [email protected].
Crystal Enterprise Administrator’s Guide
409
Adding a license key
Adding a license key
Note: If you are upgrading from a trial version of the product, be sure to delete
the Evaluation key prior to adding any new license keys or product activation
keycodes.
1 Go to the License Keys management area of the CMC.
2 Type the key in the Add Key field.
Note: Key codes are case-sensitive.
3 Click Add.
The key is added to the list.
Viewing current account activity
1 Go to the Settings management area of the CMC.
2 Click the Metrics tab.
This tab displays current license usage, along with additional job metrics.
410
Crystal Enterprise Administrator’s Guide
21: Licensing Information
Express Edition vs. Professional Edition
This table outlines the key differences between the Express and Professional
editions of Crystal Enterprise.
Feature
Express
Professional
Crystal Repository refresh
X
X
Insert subreport
X
X
Unicode support
X
X
Setting locale of the Report Engine
X
X
New viewer architecture
X
X
Smart Tags
X
X
Exporting page ranges
X
X
New Excel export options
X
X
OLAP integration
X
X
Export drill down views
X
X
Embed URL link to report in email
X
Set database location
X
X
Custom printer settings
X
X
Java SDK
X
.NET SDK
X
RAS support for processing extensions
X
Distributed servers
X
Ability to define users/personalization
X
Concurrent users
X
Third-party authentication support
X
Events
X
X
Object distribution (Destinations)
X
Crystal Enterprise Mobile Desktop
X
X
Server group re-direction
X
X
Crystal Enterprise Administrator’s Guide
411
Express Edition vs. Professional Edition
412
Crystal Enterprise Administrator’s Guide
Rights and Access Levels
A
This appendix maps the rights that are available in the
Crystal Management Console (CMC) to the actual rights
available through the Crystal Enterprise SDK; it also lists
the rights that make up each of the predefined access levels,
and the default rights that are applied to the system’s toplevel folder. This appendix is provided primarily for
reference purposes. For complete details on setting rights,
see “Controlling User Access” on page 141.
Crystal Enterprise Administrator’s Guide
413
Rights
Rights
This table lists the rights available within the Advanced Rights page of the Crystal
Management Console (CMC). Other Crystal Enterprise plug-in components may
in future add their own, object-specific rights to this list. The table matches the
descriptions used in the CMC with the programmatic name that developers use
when assigning rights with the Crystal Enterprise SDK.
Description used in the CMC
Name used in the SDK
Respect current security by inheriting
rights from parent groups
AdvancedInheritGroups
Respect current security by inheriting
rights from parent folders
AdvancedInheritFolders
Add objects to the folder
ceRightAdd
View objects
ceRightView
Edit objects
ceRightEdit
Modify the rights users have to objects
ceRightModifyRights
Schedule the document to run
ceRightSchedule
Delete objects
ceRightDelete
Define server groups to process jobs
ceRightPickMachines
Delete instances
ceRightDeleteInstance
Copy objects to another folder
ceRightCopy
Schedule to destinations
ceRightSetDestination
View document instances
ceRightViewInstance
Pause and Resume document instances
ceRightPauseResumeSchedule
Print the report’s data
ceReportRightPrintReport
Refresh the report’s data
ceReportRightRefreshOnDemand
Report
Export the report’s data
ceReportRightPageServerExport
View objects that the user owns
ceRightOwnerView
Edit objects that the user owns
ceRightOwnerEdit
Modify the rights users have to objects that
the user owns
ceRightOwnerModifyRights
Delete objects that the user owns
ceRightOwnerDelete
Delete instances that the user owns
ceRightOwnerDeleteInstance
View document instances that the user owns ceRightOwnerViewInstance
Pause and resume document instances that
the user owns
414
ceRightOwnerPauseResume
Schedule
Crystal Enterprise Administrator’s Guide
A: Rights and Access Levels
Access levels
This section lists the rights that constitute each of the predefined access levels that
are available through the Advanced Rights page of the Crystal Management
Console (CMC).
Note: There is no predefined access level to grant users the rights required to
create or modify reports through the Report Application Server (RAS). For
details, see “Object rights for the Report Application Server” on page 417.
No Access
This access level ensures that all rights remain unspecified. That is, rights are
neither explicitly granted nor explicitly denied. When rights are unspecified, the
system denies the right by default.
View
Description used in the CMC
Name used in the SDK
View objects
ceRightView
View document instances
ceRightViewInstance
Schedule
Description used in the CMC
Name used in the SDK
View objects
ceRightView
Schedule the document to run
ceRightSchedule
Define server groups to process jobs
ceRightPickMachines
Copy objects to another folder
ceRightCopy
Schedule to destinations
ceRightSetDestination
View document instances
ceRightViewInstance
Print the report’s data
ceReportRightPrintReport
Export the report’s data
ceReportRightPageServerExport
Edit objects that the user owns
ceRightOwnerEdit
Delete instances that the user owns
ceRightOwnerDeleteInstance
Pause and resume document
instances that the user owns
ceRightOwnerPauseResumeSchedule
Crystal Enterprise Administrator’s Guide
415
Access levels
View On Demand
Description used in the CMC
Name used in the SDK
View objects
ceRightView
Schedule the document to run
ceRightSchedule
Define server groups to process jobs
ceRightPickMachines
Copy objects to another folder
ceRightCopy
Schedule to destinations
ceRightSetDestination
View document instances
ceRightViewInstance
Print the report’s data
ceReportRightPrintReport
Refresh the report’s data
ceReportRightRefreshOnDemand
Report
Export the report’s data
ceReportRightPageServerExport
Edit objects that the user owns
ceRightOwnerEdit
Delete instances that the user owns
ceRightOwnerDeleteInstance
Pause and resume document instances
that the user owns
ceRightOwnerPauseResumeSchedule
Description used in the CMC
Name used in the SDK
Full Control
416
Add objects to the folder
ceRightAdd
View objects
ceRightView
Edit objects
ceRightEdit
Modify the rights users have to objects
ceRightModifyRights
Schedule the document to run
ceRightSchedule
Delete objects
ceRightDelete
Define server groups to process jobs
ceRightPickMachines
Delete instances
ceRightDeleteInstance
Copy objects to another folder
ceRightCopy
Schedule to destinations
ceRightSetDestination
View document instances
ceRightViewInstance
Pause and Resume document
instances
ceRightPauseResumeSchedule
Print the report’s data
ceReportRightPrintReport
Crystal Enterprise Administrator’s Guide
A: Rights and Access Levels
Description used in the CMC
Name used in the SDK
Refresh the report’s data
ceReportRightRefreshOnDemand
Report
Export the report’s data
ceReportRightPageServerExport
Default rights on the top-level folder
The top-level Crystal Enterprise folder serves as the root for all other folders and
objects that you add to the system. This folder provides the following rights by
default:
• The Everyone group is granted the Schedule access level.
• The Administrators group is granted the Full Control access level.
Object rights for the Report Application Server
To allow users to create or modify reports over the Web through the Report
Application Server (RAS), you must have RAS Report Modification licenses
available on your system. You must also grant users a minimum set of object
rights. When you grant users these rights to a report object, they can select the
report as a data source for a new report or modify the report directly:
• View objects (or “View document instances”, as appropriate)
• Edit objects
• Refresh the report’s data
• Export the report’s data
User must also have permission to add objects to at least one folder before they can
save new reports back to Crystal Enterprise.
To ensure that users retain the ability to perform additional reporting tasks (such
as copying, scheduling, printing, and so on), it’s recommended that you first
assign the appropriate access level and update your changes. Then, change the
access level to Advanced, and add any of the required rights that are not already
granted. For instance, if users already have View On Demand rights to a report
object, you allow them to modify the report by changing the access level to
Advanced and explicitly granting the additional Edit objects right.
When users view reports through the Advanced DHTML viewer and the RAS, the
View access level is sufficient to display the report, but View On Demand is
required to actually use the advanced search features. The extra Edit objects right
is not required.
Tip: For more information about RAS Report Modification licenses, see “Licensing
overview” on page 408.
Crystal Enterprise Administrator’s Guide
417
Object rights for the Report Application Server
418
Crystal Enterprise Administrator’s Guide
Configuring NTFS Permissions
B
This appendix provides the recommended user account
and NTFS permissions for Crystal Enterprise components.
Crystal Enterprise Administrator’s Guide
419
Configuring NTFS permissions
Configuring NTFS permissions
When you view reports over the Web, insufficient New Technology File System
(NTFS) permissions on the server can cause a number of problems. For example, a
report may not appear in the viewer, even after you repeatedly enter the correct
database logon information.
NTFS provides security for file storage in Microsoft Windows. If a Crystal
Enterprise component is running on a user account that does not have the required
NTFS permissions, users may be unable to access reports over the Web.
To troubleshoot NTFS permissions, ensure that each Crystal Enterprise
component uses an account with the appropriate permissions. You may need to
change the user account or change the NTFS access for particular files and folders.
For details on changing server user accounts, see “Changing the server user
account” on page 326. For information on changing NTFS permissions, see the
Microsoft Windows help.
Configuring NTFS permissions for Crystal Enterprise components
Each component requires a user account with certain NTFS access rights to specific
files and folders. Ensure that each component is running on the correct user
account, and make sure the user account has the required NTFS permissions.
Web Connectors
Web Connectors use the anonymous access account specified by Microsoft Internet
Information Services (IIS). Ensure that this user account—called IUSR_<computername>
by default—has the appropriate NTFS permissions for the following files and folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
• <drive>:\Winnt\system32\ebus-3-3-2.dll
• <drive>:\Winnt\system32\etc-1-0-12.dll
• <drive>:\Winnt\system32\msvcp60.dll
Note:
• Additional problems may occur if there is a firewall between a Web Connector
and the Web Component Server. For more information, see “Configuring for
SOCKS servers” on page 387.
• If the Web Connector and the Web Component Server are on different
machines, you may also encounter problems with virtual application
mapping. For details, see Crystal Enterprise Installation Guide.
420
Crystal Enterprise Administrator’s Guide
B: Configuring NTFS Permissions
Web Component Server
By default, the Crystal Management Server uses the local System account to access
resources and Crystal Enterprise components. Ensure this user account has the
appropriate NTFS permissions for specific folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
• <drive>:\Program Files\Crystal Decisions\Web
Content\enterprise
• <drive>:\Program Files\Crystal
Decisions\WCS\CRImages
• <drive>:\Program Files\Crystal Decisions\WCS
• <drive>:\Program Files\Crystal
Decisions\Enterprise 10\win32_x86
• Write
• <drive>:\Program Files\Crystal
Decisions\WCS\Logging
Note: If your Crystal Enterprise deployment includes Crystal Analysis
Professional (CA Pro), the WCS user account also needs Read permission for the
CA Pro FileStore\Input folder.
File Repository Servers (FRS)
The Input and Output File Repository Servers (Input and Output FRS) use the local
System account by default; these accounts provide sufficient access to files and
folders on the local machine. However, if the Input or Output FRS needs access to
directories on other machines, set its user account to a domain user account with
local administrative access to all computers hosting Crystal Enterprise
components. For details on changing the user account, see “Changing the server
user account” on page 326.
Ensure that the user account for the Input FRS has the appropriate NTFS
permissions for the following folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
• <drive>:\Program Files\Crystal
Decisions\Enterprise 10\FileStore\Input
• Write
• <drive>:\Program Files\Crystal
Decisions\Enterprise 10\FileStore\Input
Crystal Enterprise Administrator’s Guide
421
Configuring NTFS permissions
For the Output FRS, make sure the user account has access to the following folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
• <drive>:\Program Files\Crystal Decisions\
Enterprise 10\FileStore\Output
• Write
• <drive>:\Program Files\Crystal Decisions\
Enterprise 10\FileStore\Output
Note:
• The Input and Output File Repository Servers cannot share the same directories.
• If the Input folder or the Output folder does not exist, the respective FRS
creates it when the service starts.
Crystal Management Server (CMS)
The CMS uses the local System account by default. This account does not need
access to other machines. Ensure that the System account has the appropriate
NTFS permissions for specific files and folders:
NTFS rights
Folders
• Read & Execute
• <drive>:\Winnt\system32\drivers\etc\hosts
• Write
• <drive>:\Program Files\Crystal Decisions\
Enterprise 10\win32_x86\CITemp
Cache Server
The Cache Server uses the local System account by default. If the Cache Server
needs to access Crystal Enterprise components on other machines, you must set its
user account to a domain user account that has local administrative access to all
computers hosting components. For details on changing the user account, see
“Changing the server user account” on page 326.
Ensure that the Cache Server’s user account has the correct NTFS permissions for
the following folders:
422
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
• <drive>:\Program Files\Crystal
Decisions\Enterprise 10\win32_x86
• Write
• <drive>:\Program Files\Crystal Decisions\WCS
Crystal Enterprise Administrator’s Guide
B: Configuring NTFS Permissions
Job Server
The Job Server uses the local System account by default. The Job Server must use a
different user account if it needs to access Crystal Enterprise components on other
machines. If the CMS, the Input FRS, or the Output FRS is not located on the same
machine as the Job Server, set the Job Server’s user account to a domain user
account that has local administrative access to all computers hosting these
components. For details on changing the user account, see “Changing the server
user account” on page 326.
Ensure that the Job Server’s user account has the correct NTFS permissions for the
following folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
•
•
•
•
• Write
• <drive>:\Program Files\Crystal Decisions\WCS
• <drive>:\Program Files\Crystal Decisions\
The system’s temporary directory
<drive>:\Winnt\Crystal
<drive>:\Winnt\Fonts
<drive>:\Program Files\Crystal Decisions\Shared
Enterprise 10\FileStore
Page Server
The Page Server connects to the database to retrieve the information needed to
build the report. For most Crystal Enterprise deployments, the reporting database
is located on a separate machine. If the Page Server is on a different machine from
the database, you must change the Page Server’s user account from the default
local System account to a domain user account with local administrative access to
the computer hosting the reporting database. For details on changing the user
account, see “Changing the server user account” on page 326.
Ensure that the Page Server’s user account has the correct NTFS permissions for
the following folders:
NTFS permissions
Files and folders
• Read
• <drive>:\Winnt\system32
• Read & Execute
•
•
•
•
•
• Write
Crystal Enterprise Administrator’s Guide
The system’s temporary directory
<drive>:\Winnt\Crystal
<drive>:\Winnt\Fonts
<drive>:\Program Files\Crystal Decisions\Shared
<drive>:\Program Files\Crystal Decisions\
Enterprise 10\FileStore\Input
• <drive>:\Program Files\Crystal Decisions\WCS
423
Configuring NTFS permissions
424
Crystal Enterprise Administrator’s Guide
Server Command Lines
C
This appendix lists the command-line options that control
the behavior of each Crystal Enterprise server.
Crystal Enterprise Administrator’s Guide
425
Command lines overview
Command lines overview
When you start or configure a server through the Crystal Management Console
(CMC) or the Crystal Configuration Manager (CCM), the server is started (or
restarted) with a default command line that includes a typical set of options and
values. In the majority of cases, you need not modify the default command lines
directly. Moreover, you can manipulate the most common settings through the
various server configuration screens in the CMC and the CCM. For reference, this
appendix provides a full listing of the command-line options supported by each
server. You can modify each server’s command line directly if you need to further
customize the behavior of Crystal Enterprise.
Throughout this appendix, values provided in square brackets [ ] are optional.
To view or modify a server’s command line
The procedure for viewing or modifying a server’s command line depends upon
your operating system:
• On Windows, use the CCM to stop the server. Then open the server’s Properties
to modify the command line. Start the server again when you have finished.
• On UNIX, run ccm.sh to stop the server. Then edit ccm.config to modify the
server’s command line. Start the server again when you have finished.
Note: On UNIX, each server’s command line is actually passed as an argument
to the crystalrestart.sh script. This script launches the server and monitors it
in case an automatic restart is required. See the ccm.config file and
“crystalrestart.sh” on page 443.
Standard options for all servers
These command-line options apply to all of the Crystal Enterprise servers, unless
otherwise indicated. See the remainder of this appendix for options specific to each
type of server.
Option
Valid Arguments
Behavior
-name
string
Specify the friendly name of the server. The server registers
this name with the Crystal Management Server (CMS), and
the name is displayed in the CMC. The default friendly
name is hostname.servertype
Note:
• Do not modify -name for a CMS.
• If you modify -name for an Input or Output File
Repository Server, you must include “Input.” or “Output.”
as the prefix to the value you type for string (for example,
-name Input.Server01 or -name Output.UK).
426
Crystal Enterprise Administrator’s Guide
C: Server Command Lines
Option
Valid Arguments
Behavior
-ns
cmsname[:port]
Specify the CMS that the server should register with. Add
port if the CMS is not listening on the default (6400). This
option does not apply to the CMS itself.
-requestPort
port
Specify the port that the server listens on. The server
registers this port with the CMS. If unspecified, the server
chooses any free port > 1024.
Note: This port is used for different purposes by different
servers. Before changing, see “Changing the default server
port numbers” on page 321.
-port
[interface:][port] Bind WCS or CMS to the specified port, or to the specified
network interface and port. Binds other servers to the
specified network interface. Useful on multihomed
machines or in certain NAT firewall environments.
Note:
• Use -port port or -port interface:port for WCS and
CMS. Use -port interface for other servers. The port
command is used for different purposes by different servers.
Before changing, see “Changing the default server port
numbers” on page 321.
• If you change the default port value for the CMS, you
must perform additional system configuration. For more
information please see “Changing the default server port
numbers” on page 321.
•
-restart
Server restarts if it exits with an unusual exit code.
-fg
UNIX only. Run the daemon in the foreground. When
passing the server’s command line to the crystalrestart.sh
script, you must use this option (see ccm.config). If you run
the server’s command line directly, do not use this option,
because the foreground process blocks the shell until the
server exits.
UNIX signal handling
On UNIX, the Crystal Enterprise daemons handle the following signals:
• SIGTERM results in a graceful server shutdown (exit code = 0).
• SIGSEGV, SIGBUS, SIGSYS, SIGFPE, and SIGILL result in a rapid shutdown (exit
code = 1).
Crystal Enterprise Administrator’s Guide
427
Crystal Management Server
Crystal Management Server
This section provides the command-line options that are specific to the CMS.
The default path to the server on Windows is:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\CrystalMS.exe
The default path to the server on UNIX is:
INSTALL_ROOT/crystal/enterprise/platform/crystalcmsd
Option
Valid
Arguments
-threads
number
Behavior
Use a thread pool of the specified size. The default is
one thread per request.
-reinitializedb
Cause the CMS to delete the system database and
recreate it with only the default system objects.
-quit
Force the CMS to quit after processing the
-reinitializedb option.
-receiverPool
number
Specify the number of threads the CMS creates to
receive client requests. A client may be another Crystal
server, the Report Publishing Wizard, Crystal Reports,
or a custom client application that you have created.
The default value is 5. Normally you will not need to
increase this value, unless you create a custom
application with many clients.
-maxobjectsincache
number
Specify the maximum number of objects that the CMS
stores in its memory cache. Increasing the number of
objects reduces the number of database calls required
and greatly improves CMS performance. However,
placing too many objects in memory may result in the
CMS having too little memory remaining to process
queries. The upper limit is 100000.
-ndbqthreads
number
Specify the number of CMS worker threads sending
requests to the database. Each thread has a connection
to the database, so you must be careful not to exceed
your database capacity. In most cases, the maximum
value you should set is 10.
-AuditInterval
minutes
Specify interval at which the CMS requests audit
information from audited servers. The default value is 5
minutes. (Maximum value is 15 minutes, and minimum
value is 1 minute.)
-AuditBatchSize
number
Specify the maximum number of audit records that the
CMS requests from each audited server, per audit
interval. The default value is 200 records. (Maximum
value is 500, and minimum value is 50.)
428
Crystal Enterprise Administrator’s Guide
C: Server Command Lines
Option
Valid
Arguments
-auditMaxEventsPerFile
number
Specify the maximum number of records in the audit
log file. The default value is 500. If the number specified
by -auditMaxEventsPerFile is exceeded, the server
opens a new log file.
-AuditeeTimeSyncInterval
minutes
Specify the interval between time synchronization
events. The CMS broadcasts its system time to audited
servers at the interval specified by
-AuditeeTimeSyncInterval. The audited servers
compare their internal clocks to the CMS time, and then
adjust the timestamps they give to all subsequent audit
records so that the time of these records synchronizes
with the CMS time. The default interval is 60 minutes.
(Maximum value is 1 day, or 1440 minutes. Minimum
value is 15 minutes. Setting the interval to 0 turns off
time synchronization.)
Behavior
Web Component Server
This section provides the command-line options that are specific to the WCS.
The default path to the server on Windows is:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\WebCompServer.exe
Option
Valid Arguments
Behavior
-defaultSessionTimeout
minutes
Specify the default session timeout, in minutes. If
unspecified, sessions time out after 20 minutes of
inactivity.
Page Server and Cache Server
The Page Server and the Cache Server are controlled in much the same way from
the command line. The command-line options determine whether the server starts
as a Page Server, a Cache Server, or both. Options that apply only to one server
type are noted below.
The default paths to the servers on Windows are:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\cacheserver.exe
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\pageserver.exe
The default paths to the servers on UNIX are:
INSTALL_ROOT/crystal/enterprise/platform/crystalcachesd
INSTALL_ROOT/crystal/enterprise/platform/crystalpagesd
Crystal Enterprise Administrator’s Guide
429
Page Server and Cache Server
Option
Valid Arguments
-cache
-dir
Behavior
Enable Cache Server functionality.
absolutepath
Specify the cache directory for a Cache Server and
the temp directory for the Page Server. The
directories created are absolutepath/cache and
absolutepath/temp
-deleteCache
Delete the cache directory every time the server
starts and stops.
-psdir
absolutepath
Specify the temp directory for the Page Server.
This option overrides -dir.
-refresh
minutes
Share cached pages for the specified number of
minutes.
-maxDBResultRecords
number
Limit the number of database records that are
returned from the database. The default limit is
20000 records. If a user views an on-demand
report containing more than 20000 records, an
error message indicates that the report contains
too many database records. To increase the
enforced limit, increase number accordingly; to
disable the limit, replace number with 0 (zero).
-noautomaticdbdisconnect
Disable automatic database disconnection for the
Page Server. By default the Page Server will
automatically disconnect from the reporting
database after retrieving data, to free up database
licenses. This may affect performance if your site
uses many reports with on-demand subreports,
or group-by-on-server.
-report_ProcessExtPath
absolutepath
Specify the default directory for processing
extensions. For details, see “Applying processing
extensions to reports” on page 189.
-auditMaxEventsPerFile
number
On the Cache Server, specifies the maximum
number of audit actions recorded in the audit log
file. The default value is 500. If this maximum
number of records is exceeded, the server will
open a new log file.
430
Crystal Enterprise Administrator’s Guide
C: Server Command Lines
Report and Program Job Servers
This section provides the command-line options that are specific to the Report and
Program Job Servers.
The default path to the server on Windows is:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\JobServer.exe
The default path to the server on UNIX is:
INSTALL_ROOT/crystal/enterprise/platform/crystaljobsd
Option
Valid Arguments
Behavior
-dir
absolutepath
Specify the data directory for the Job Server.
-lib
processinglibrary
Specify the processing library to load:
• procReport or
• procProgram
Loading procReport starts the Job Server as a
Report Job Server. Loading procProgram starts
the Job Server as a Program Job Server. This
option is used in conjunction with -objectType.
-objectType
progID
The program ID of the processing library,
which determines the class of object supported
by the Job Server:
• CrystalEnterprise.Report or
• CrystalEnterprise.Program
Used with -lib to specify whether the Job
Server becomes a Report Job Server or a
Program Job Server.
-maxJobs
number
Set the maximum number of concurrent jobs
that the server will handle. The default is five.
-requestJSChildPorts
lowerbound-upperbound
Specify the range of ports that child processes
should use in a firewall environment. For
example, 6800-6805 limits child processes to
six ports.
-report_ProcessExtPath
absolutepath
Specify the default directory for processing
extensions. For details, see “Applying
processing extensions to reports” on page 189.
-auditMaxEventsPerFile
number
Specify the maximum number of records in the
audit log file. The default value is 500. If the
number specified by -auditMaxEventsPerFile is
exceeded, the server opens a new log file.
Crystal Enterprise Administrator’s Guide
431
Report Application Server
Report Application Server
This section provides the command-line options that are specific to the Report
Application Server.
The default path to the server on Windows is:
C:\Program Files\Common Files\Crystal Decisions\2.5\bin\crystalras.exe
The default path to the server on UNIX is:
INSTALL_ROOT/crystal/enterprise/platform/ras/crystalrasd
Option
Valid Arguments
Behavior
-ipport
port
Specify the port number for receiving TCP/IP
requests when running in stand-alone mode
(outside of Crystal Enterprise).
-report_ProcessExtPath
absolutepath
Specify the default directory for processing
extensions. For details, see “Applying processing
extensions to reports” on page 189.
-ProcessAffinityMask
mask
Use a mask to specify exactly which CPUs that
RAS will use when it runs on a multi-processor
machine.
The mask is in the format 0xffffffff, where each f
represents a processor, and the list of processors
reads from right to left (that is, the last f represents
the first processor). For each f, substitute either 0
(use of CPU not permitted) or 1 (use of CPU is
permitted). Convert the resulting binary number
(0110, for example) to hexadecimal. For example, if
you run the RAS on a 4 processor machine and
want it to use the 3rd and 4th processor, use the
mask 0x0000000C. To use the 2nd and 3rd processor,
use 0x00000006.
Note:
• RAS uses the first permitted processors in the
string, up to the maximum specified by your
license. If you have a two processor license,
0x0000000E has the same effect as 0x00000006.
• The default value of the mask is -1, which has
the same meaning as 0x0000000F.
-auditMaxEventsPerFile
432
number
Specify the maximum number of records in the
audit log file. The default value is 500. If the
number specified by -auditMaxEventsPerFile is
exceeded, the server opens a new log file.
Crystal Enterprise Administrator’s Guide
C: Server Command Lines
Input and Output File Repository Servers
This section provides the command-line options that are specific to the Input and
Output File Repository Servers.
The default paths to the servers on Windows are:
C:\Program Files\Crystal Decisions\Enterprise
10\win32_x86\inputfileserver.exe
C:\Program Files\Crystal Decisions\Enterprise
10\win32_x86\outputfileserver.exe
The default path to the program that provides both servers on UNIX is:
INSTALL_ROOT/crystal/enterprise/platform/crystalfilesd
Note: If you modify -name for an Input or Output File Repository Server, you
must include “Input.” or “Output.” as the prefix to the value you type (for
example, -name Input.Server01 or -name Output.UK).
Option
Valid Arguments
Behavior
-rootDir
absolutepath
Set the root directory for the various subfolders and files that are
managed by the server. File paths used to refer to files in the File
Repository Server are interpreted relative to this root directory.
Note: All Input File Repository Servers must share the same root
directory, and all Output File Repository Servers must share the
same root directory (otherwise there is a risk of having
inconsistent instances). Additionally, the input root directory
must not be the same as the output root directory. It is
recommended that you replicate the root directories using a RAID
array or an alternative hardware solution.
-tempDir
absolutepath
Set the location of the temporary directory that the FRS uses to
transfer files. Use this command line option if you want to control
the location of the FRS temporary directory, or if the default
temporary directory name generated by the FRS exceeds the file
system path limit (which will prevent the FRS from starting).
-maxidle
minutes
Specify the number of minutes after which an idle session is
cleaned up.
Crystal Enterprise Administrator’s Guide
433
Event Server
Event Server
This section provides the command-line options that are specific to the Event Server.
The default path to the server on Windows is:
C:\Program Files\Crystal Decisions\Enterprise 10\win32_x86\EventServer.exe
The default path to the server on UNIX is:
INSTALL_ROOT/crystal/enterprise/platform/crystaleventsd
Option
Valid Arguments
Behavior
-poll
seconds
Specify the frequency (in seconds) with which the server
checks for File events.
-cleanup
minutes
Specify the frequency (in minutes) with which the server
cleans up listener proxies.
-auditMaxEvent
sPerFile
number
Specify the maximum number of records in the audit log file.
The default value is 500. If the number specified by
-auditMaxEventsPerFile is exceeded, the server opens a new
log file.
434
Crystal Enterprise Administrator’s Guide
UNIX Tools
D
This appendix details each of the administrative tools and
scripts that are included with the UNIX distribution of
Crystal Enterprise. This appendix is provided primarily for
reference purposes. Concepts and configuration
procedures are discussed in more detail throughout this
guide.
Crystal Enterprise Administrator’s Guide
435
UNIX tools overview
UNIX tools overview
The UNIX distribution of Crystal Enterprise includes a number of scripts that,
together, provide you with all the configuration options that are available in the
Windows version of the Crystal Configuration Manager (CCM). There are a
number of other scripts that provide you with UNIX-specific options or serve as
templates for your own scripts. Also, there are several secondary scripts that are
used by Crystal Enterprise. Each script is described here and the command-line
options are provided where applicable.
Script utilities
This section describes the administrative scripts that assist you in working with
Crystal Enterprise on UNIX. The remainder of this guide discusses the concepts
behind each of the tasks that you can perform with these scripts. This reference
section provides you the main command-line options and their arguments.
ccm.sh
The ccm.sh script is installed to the crystal directory of your installation. This
script provides you with a command-line version of the CCM. This section lists the
command-line options and provides some examples.
Note:
• Arguments in square brackets [ ] are optional.
• By default, servers are named with a hostname.servertype convention. If the
option requires the server name, use servertype as the server name. If the
option requires the fully qualified server name, use hostname.servertype. If you
are unsure of a server’s fully qualified name, look in the ccm.config file, locate
the server’s launch string, and use the value that appears after the -name option.
• Arguments denoted by other authentication information are provided in
the second table.
CCM Option
Valid Arguments
Description
-help
n/a
Display command-line help.
-start
all or servername
Start each server as a process. Use the
short form of the server name.
-stop
all or servername
Stop each server by terminating its
Process ID. Use the short form of the
server name.
-restart
all or servername
Stop each server by terminating its
Process ID; then each server is started.
Use the short form of the server name.
436
Crystal Enterprise Administrator’s Guide
D: UNIX Tools
CCM Option
Valid Arguments
Description
-enable
all or hostname.servertype
Enable a started server so that it registers
with the system and starts listening on the
appropriate port. Use the fully qualified
form of the server name.
all or hostname.servertype
Disable a server so that it stops
responding to Crystal Enterprise requests
but remains started as a process. Use the
fully qualified form of the server name.
-display
server [other authentication
information]
Reports the server’s current status
(enabled or disabled). The CMS must be
running before you can use this option.
-updateobjects
[other authentication
information]
Update objects migrated from a previous
version of Crystal Enterprise into your
current CMS system database. Use this
option after running cmsdbsetup.sh. See
“Completing a CMS database migration”
on page 294 for more information.
[other authentication
information]
-disable
[other authentication
information]
This table describes the options that make up the argument denoted by other
authentication information.
Authentication
Option
Valid arguments
Description
-cms
cmsname:port#
Specify the CMS that you want to log on
to. If not specified, the CCM defaults to
the local machine and the default port
(6400).
-username
username
Specify an account that provides
administrative rights to Crystal
Enterprise. If not specified, the default
Administrator account is attempted.
-password
password
Specify the corresponding password. If
not specified, a blank password is
attempted.
Note: To specify the -password argument,
you must also specify the -username
argument.
-authentication
secEnterprise, secLDAP
Specify the appropriate authentication
type for the administrative account. If not
specified, secEnterprise is attempted.
The CCM reads the server launch strings and other configuration values from the
ccm.config file. For details, see “ccm.config” on page 438.
Crystal Enterprise Administrator’s Guide
437
Script utilities
Examples
These two commands start and enable all the servers. The Crystal Management
Server (CMS) is started on the local machine and the default port (6400):
ccm.sh -start all
ccm.sh -enable all
These two commands start and enable all the servers. The CMS is started on port
6701, rather than on the default port:
ccm.sh -start all
ccm.sh -enable all -cms MACHINE01:6701
These two commands start and enable all the servers with a specified
administrative account named SysAdmin:
ccm.sh -start all
ccm.sh -enable all -cms MACHINE01:6701 -username SysAdmin -password 35%bC5@5
-authentication LDAP
This single command logs on with a specified administrative account to disable a
Job Server that is running on a second machine:
ccm.sh -disable MACHINE02.crystaldecisions.com.reportserver -cms
MACHINE01:6701 -username SysAdmin -password 35%bC5@5 -authentication secLDAP
ccm.config
This configuration file defines the server launch strings and other values that are
used by the CCM when you run its commands. This file is maintained by the CCM
itself, and by the other Crystal Enterprise script utilities. You typically edit this file
only when you need to modify a server’s command line. For details, see
“Command lines overview” on page 426.
cmsdbsetup.sh
The cmsdbsetup.sh script is installed to the crystal directory of your installation.
The script provides a text-based program that enables you to configure the CMS
database, CMS clusters, and to set up the audit database
You can add a CMS to a cluster by selecting a new data source for its CMS
database. You can also delete and recreate (re-initialize) a CMS database, copy data
from another data source, or change the existing cluster name.
Note: Before running this script, back up your current CMS database. Also be
sure to see “Configuring the intelligence tier” on page 284 for additional
information about CMS clusters and configuring the CMS database.
The script will prompt you for the name of your CMS. By default, the CMS name
is hostname.cms. That is, the default name of a CMS installed on a machine called
MACHINE01 is MACHINE01.cms. To check the name of your CMS (or any other server),
view the contents of ccm.config and look for the server’s launch string. The server’s
current name appears after the -name option.
438
Crystal Enterprise Administrator’s Guide
D: UNIX Tools
For more information about configuring the CMS database, see “Configuring the
intelligence tier” on page 284. For more information about setting up the auditing
database, see “Configuring the auditing database” on page 334.
configpatch.sh
The configpatch.sh script is installed to the crystal/enterprise/generic directory
of your installation. Use the configpatch.sh script when installing patches that
require updates to system configuration values. After installing the patch, run
configpatch.sh with the appropriate .cf file name as an argument. The readme.txt
file that accompanies Crystal Enterprise patches tells you when to run
configpatch.sh, and the name of the .cf file to use.
serverconfig.sh
The serverconfig.sh script is installed to the crystal directory of your installation.
This script provides a text-based program that enables you to view server
information and to add and delete servers from your installation. This script adds,
deletes, modifies, and lists information from the ccm.config file.
When you modify a server using serverconfig.sh, you can change the location of
its temporary files. For the Crystal Management Server, you can change its port
number or enable auditing. For the Input File Repository Server or the Output File
Repository Server, you can enter the root directory.
To add/delete/modify/list UNIX servers
1 Go to the crystal directory of your installation.
2 Issue the following command:
./serverconfig.sh
The script prompts you with a list of options:
• 1 - Add a server
• 2 - Delete a server
• 3 - Modify a server
• 4 - List all servers in the config file
3 Type the number that corresponds to the action you want to perform.
4 If you are adding, deleting, or modifying a server, provide the script with any
additional information that it requests.
Tip: The script will prompt you for the name of your CMS. By default, the CMS
name is hostname.cms. That is, the default name of a CMS installed on a machine
called MACHINE01 is MACHINE01.cms. However, in this script you can enter
hostname to check the name of your CMS (or any other server), view the contents
of ccm.config, and look for the server’s launch string. The server’s current name
appears after the -name option.
Crystal Enterprise Administrator’s Guide
439
Script utilities
5 Once you have added or modified a server, use the CCM to ensure that the
server is both started and enabled.
For more information about each of these topics, see “Scalability overview” on
page 356.
sockssetup.sh
The sockssetup.sh script is installed to the crystal directory of your installation.
The script provides a text-based program that enables you to configure the Web
Component Adapter (WCA) and the Crystal Management Server (CMS) when
they must communicate across one or more SOCKS proxy server firewalls. For
technical information about Crystal Enterprise and firewalls, see “Firewalls
overview” on page 368.
This script does not configure the Web Connector to communicate with the WCS
through a SOCKS server. If a SOCKS server separates your web server from the
WCS, you must manually configure the Web Connector configuration file that
corresponds to your web server. For more information, see “Configuring the Web
Connector for SOCKS servers” on page 389.
To modify SOCKS configuration
1 Go to the crystal directory of your installation.
2 Issue the following command:
./sockssetup.sh
3 Type wca to configure the communication between the WCA and the CMS. Or,
type servers to configure SOCKS information between the remaining servers.
The script may prompt you for the name or “friendly name” of the server. By
default, each server’s name is hostname.servertype. To check the name of a
server, view the contents of ccm.config and look for the server’s launch string.
The server’s current name appears after the -name option.
The “friendly name” of the WCA by default is hostname.wca. To check the name
of the WCA, look for the <display-name> of the WCA as listed in the web.xml
file in the WEB-INF directory of the webcompadapter.war archive. (This archive is
found in the crystal_root/enterprise/JavaSDK/applications directory, where
crystal_root is the root directory of your Crystal Enterprise installation.)
4 Specify one of the available actions:
• Type show to display any SOCKS servers that have already been entered
with this script. A blank list is displayed if no servers have been added.
• Type create to add a new SOCKS server to the list.
• Type modify to change one of the SOCKS servers in the list.
• Type delete to remove a SOCKS server from the list.
• Type moveup or movedown to modify the sequence of SOCKS servers.
440
Crystal Enterprise Administrator’s Guide
D: UNIX Tools
5 Proceed through the script and provide any additional information that it
requests:
• If you are creating a new entry in the list, you will typically need to provide
the name or IP address of the SOCKS server, the port number it is listening
on, the version number of the SOCKS server (4 or 5), and any
authentication information that the Crystal Enterprise servers will require
in order to establish a connection with your SOCKS server.
• If you choose to delete, modify, or move an existing entry, you will be
asked to specify the server “by index.” Type the number that corresponds
to the SOCKS server you want to modify.
For details about SOCKS and the importance of the sequence of servers, see
“Configuring for SOCKS servers” on page 387.
uninstallCE.sh
The 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.
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.
• If you performed the “system” installation type, you will also need to delete
the run control scripts from the appropriate /etc/rc# directories.
Crystal Enterprise Administrator’s Guide
441
Script templates
Script templates
These scripts are provided primarily as templates upon which you can base your
own automation scripts.
startservers
The startservers script is installed to the crystal directory of your installation.
This script can be used as a template for your own scripts: it is provided as an
example to show how you could set up your own script that starts the Crystal
Enterprise servers by running a series of CCM commands. For details on writing
CCM commands for your servers, see “ccm.sh” on page 436.
stopservers
The stopservers script is installed to the crystal directory of your installation. This
script can be used as a template for your own scripts: it is provided as an example
to show how you could set up your own script that stops the Crystal Enterprise
servers by running a series of CCM commands. For details on writing CCM
commands for your servers, see “ccm.sh” on page 436.
silentinstall.sh
The silentinstall.sh script is installed to the crystal directory of your
installation. Once you have set up Crystal Enterprise on one machine, you can use
this template to create your own scripts that install Crystal Enterprise
automatically on other machines. Essentially, once you have edited the
silentinstall.sh template accordingly, it defines the required environment
variables, runs the installation and setup scripts, and sets up Crystal Enterprise
according to your specifications, without requiring any further input.
The silent installation is particularly useful when you need to perform multiple
installations and do not want to interrupt people who are currently working on
machines in your system. 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 script parameters, 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 if you need to perform custom
installations. The installation options are simplified and do not allow for the
same level of customization provided in the Crystal Enterprise install script.
442
Crystal Enterprise Administrator’s Guide
D: UNIX Tools
Scripts used by Crystal Enterprise
These secondary scripts are often run in the background when you run the main
Crystal Enterprise script utilities. You need not run these scripts yourself.
crystalrestart.sh
This script is run internally by the CCM when it starts the Crystal Enterprise server
components. If a server process ends abruptly without returning its normal exit
code, this script automatically restarts a new server process in its place. Do not run
this script yourself.
env.sh
The env.sh script is installed to the crystal directory of your installation. This script
sets up the Crystal Enterprise environment variables that are required by some of the
other scripts. Crystal Enterprise scripts run env.sh as required. When you install
Crystal Enterprise on UNIX, you must configure your Java application server to source
this script on startup. See the Crystal Enterprise Installation Guide for more details.
env-locale.sh
The env-locale.sh script is used for converting the script language strings
between different types of encoding (for example, UTF8 or EUC or Shift-JIS). This
script is run by env.sh as needed.
initlaunch.sh
The initlaunch.sh script runs env.sh to set up the Crystal Enterprise
environment variables, and then runs any command that you have added as a
command-line argument for the script. This script is intended primarily for use as
a debugging tool by Crystal Decisions, Inc..
patchlevel.sh
The patchlevel.sh is installed to the crystal/enterprise/generic directory of your
installation. This script reports on the patch level of your UNIX distribution. This
script is intended primarily for use by Crystal Decisions, Inc. support staff.
Option
Valid Arguments
Description
list
n/a
List all the installed patches.
query
patch #
Query the operating system for the presence of
a particular patch by numeric ID.
check
textfile
Check that all the patches listed in textfile
are installed on your operating system.
Crystal Enterprise Administrator’s Guide
443
Scripts used by Crystal Enterprise
postinstall.sh
The postinstall.sh script is installed to the crystal directory of your installation.
This script runs automatically at the end of the installation script and launches the
setup.sh script. You need not run this script yourself.
setup.sh
The setup.sh script is installed to the crystal directory of your installation. This
script provides a text-based program that allows you to set up your Crystal
Enterprise installation. This script is run automatically when you install Crystal
Enterprise. It prompts you for the information that is required in order to set up
Crystal Enterprise for the first time.
For complete details on responding to the setup script when you install Crystal
Enterprise, see the Crystal Enterprise Installation Guide.
setupinit.sh
The setupinit.sh script is installed to the crystal directory of your installation
when you perform a system installation. This script copies the run control scripts
to your rc# directories for automated startup. When you run a system installation
you are directed to run this script after the setup.sh script completes.
Note: You must have root privileges to run this script.
444
Crystal Enterprise Administrator’s Guide
International Deployments
E
From server configuration to report design, this appendix
recommends the best practices for improving your Crystal
Enterprise deployment’s efficiency for a multilingual,
worldwide audience.
Crystal Enterprise Administrator’s Guide
445
International deployments overview
International deployments overview
When you distribute reports to a worldwide audience, you need to accommodate
users working in various languages, time zones, and countries. Crystal Enterprise
and Crystal Reports provide powerful capabilities for presenting data in a number
of languages. This chapter provides recommendations for creating and managing
content deployed through Crystal Enterprise to a multilingual, worldwide
audience.
International deployments require thorough planning, from choosing the best
server configuration to adopting special report design techniques. To support
multiple languages in Crystal Enterprise, you need to ensure that the servers have
the appropriate resources for delivering content in different languages. In Crystal
Reports, you can use parameters and formulas to create flexible reports that allow
users to choose between different languages or formats.
Note: For large Crystal Enterprise deployments, it is good practice to work with
our global team of certified consultants and consulting partners. For more
information, see “Crystal Consulting” on page 8.
Deploying Crystal Enterprise internationally
Deploying a Crystal Enterprise system for an international audience introduces a
unique set of challenges. When you increase support to address a specific user
need such as a new language, you often need to increase the complexity of your
deployment. In many cases, you will need to make significant changes to support
a multilingual environment.
Many problems can be avoided by planning the Crystal Enterprise deployment in
advance. How much multilingual support do your users need? How much support
is realistic from a resource perspective? Do you have the people, processes, hardware,
and software in place to provide an international Crystal Enterprise system?
When you have determined the best approach, you can configure the available
resources to deliver the best possible Crystal Enterprise solution for your users.
Planning an international Crystal Enterprise deployment
To ensure that your deployment is successful, you need to thoroughly plan the
deployment with international considerations in mind.
• Assess the needs of your users. Begin with a comprehensive list of job tasks
and other user requirements.
• Ensure that you have the appropriate resources for delivering Crystal
Enterprise to all of your users, and for maintaining its future growth.
446
Crystal Enterprise Administrator’s Guide
E: International Deployments
Consider this international deployment scenario. Half of your organization speaks
Japanese and the other half speaks English. Because there is significant user need
for both languages, you may want to provide two Crystal Enterprise systems: one
on a Japanese operating system with Japanese reports, web interfaces, and server
components; the other on an equivalent English system.
After these Japanese and English systems are in place, your organization opens
satellite offices in Paris and Venice. For the three employees at the small Paris office,
you could deploy a third Crystal Enterprise system in French. However, it would
be more cost-effective to ask your French staff to publish their French reports to the
English deployment. Some of the components and messages will appear in English,
but they will be able to publish and view French reports on the English system. In
this situation, the costs of implementing and maintaining a full French deployment
are too high; your available resources help determine the best solution.
For the Venice office, deploying an Italian Crystal Enterprise installation is not an
option. Crystal Enterprise is not currently translated into Italian. However, your
Venice employees can publish and view Italian reports using the English Crystal
Enterprise system. They will also receive some English messages while using the
English software to view the Italian reports. Because Crystal Enterprise is not
available in all languages, you may need to develop creative solutions for some of
your users.
This solution responds to changing audience requirements, and provides the best
quality of data access to the most people, within the limits of the available
resources. When you plan an international Crystal Enterprise deployment,
consider these two important factors: the language needs of your users, and the
available server resources.
Languages
A quick survey of your organization should provide enough information to
determine your language requirements. Which languages are used most often
across the organization? Is there a demand for reports in all of these languages?
Which languages does your company currently support on its web site? How
many languages do your report users speak? It may be necessary to provide
reports in only two or three languages.
Make sure you check your language requirements against the list of supported
languages for Crystal Enterprise. Crystal Enterprise software is available in
English, French, German, and Japanese. For these languages, the software itself has
been translated (or localized), with all functions and features available in the
specific language. Crystal Enterprise also accepts content created in other
supported languages: Spanish, Italian, Korean, Simplified Chinese, and
Traditional Chinese. You can publish objects in these languages using one of the
Crystal Enterprise Administrator’s Guide
447
Deploying Crystal Enterprise internationally
localized versions of Crystal Enterprise. Note that the Crystal Enterprise software
is not translated into these languages.
Localized languages
Other supported content
English
Chinese (Simplified and Traditional)
French
Italian
German
Korean
Japanese
Spanish
Resources
After you determine which languages are required, look at the resources required
to implement the different server configurations that will meet the language needs
of your users.
You can provide separate Crystal Enterprise deployments for each language, or
you can ask users to create reports in one language and deliver them using servers
in another language. Do you have the resources and people you need to manage
multiple systems or can you support only one Crystal Enterprise deployment?
For any deployment that involves more than one language, you must account for
additional server requirements. For example, if you run an English version of
Crystal Enterprise on a German operating system, you must ensure that you have
the correct combination of components for both languages.
You should choose the right deployment based on the available resources. For each
server, ensure that you have the appropriate operating system, fonts, and language
files.
• Languages
Install the appropriate languages on all servers. Even if only a few users design
reports in Spanish and Japanese against an English server, Spanish and Japanese
language files must be installed on all servers used in the English deployment.
For information on installing languages, consult your operating system’s
documentation.
• Fonts
If a language requires a special font, install the font files on all machines running
Crystal Enterprise components. For information on installing fonts, consult your
operating system’s documentation.
Note:
• Depending on the languages, data may not be displayed properly. For
example, if you publish reports in a “double-byte” language like Japanese
to an English server, the double-byte characters may not display properly
in chart titles, drill-down tabs, group tree values, and strings in formulas.
These strings use the system font specified by the server to display text.
Unless the system font supports double-byte characters, Crystal Enterprise
will not display the strings properly.
448
Crystal Enterprise Administrator’s Guide
E: International Deployments
• If, after installing the necessary fonts on the various servers, Crystal Enterprise
does not render the report properly, install Crystal Reports on the problematic
servers. Then, open the problem report and refresh it. For more information,
see “Troubleshooting reports with Crystal Reports” on page 398.
• Operating systems
Depending on your language needs, you may need to install a localized operating
system on machines running Crystal Enterprise components. The operating
system may affect certain messages that appear when working with Crystal
Enterprise. To ensure that all messages appear in the language you want, make
sure you install the appropriate version of the operating system, and make sure
it is a language supported by Crystal Enterprise.
For example, if you access French reports from a French client using an English
version of Crystal Enterprise on the server, you must have a French operating
system on the server.
• People
Depending on your configuration, you may need additional people to help
deliver and maintain your Crystal Enterprise system. If you deploy multiple
systems for different languages, you may need another system administrator or
IT professional to configure and maintain the system. When you are working
with localized versions of operating systems and software, it is good practice to
have someone on staff who not only has the technical IT skills, but also the
language skills required to manage the system.
Configuring a solution for multiple languages
After you determine the required languages and available resources, you can
develop a Crystal Enterprise configuration that best suits your needs. Varying
degrees of language support can be achieved using multiple installations, a
combination of components using different languages, or by publishing content
written in different languages. In most international deployments, you will need
to develop a combination of several methods in order to deliver reports for all
languages used in your organization.
Deploying multiple Crystal Enterprise systems
You can install a separate Crystal Enterprise system for each language, with all
components, servers, and software operating in the same language. Crystal
Enterprise is available in English, French, German, and Japanese. If a large number
of your users speak more than one of these languages, consider deploying more
than one Crystal Enterprise system.
By using one language for all components, including the servers, clients, operating
systems, you ensure that users never encounter different languages while
accessing the system. You also reduce the number of potential troubleshooting
issues that can occur when using a combination of languages on the same system.
Crystal Enterprise Administrator’s Guide
449
Deploying Crystal Enterprise internationally
For each deployment, ensure that the operating system uses the same language as
the version of Crystal Enterprise, and that users access client tier components that
also use this language. All supported browsers can be used to access client tier
components such as the Crystal Enterprise web desktop.
For example, if you have an equal number of English- and Japanese-speaking
employees, you can install English and Japanese deployments of Crystal
Enterprise. English employees will access an English client tier, running against
English server components on English operating systems. Japanese employees will
use Japanese clients, server components, and operating systems.
Although multiple Crystal Enterprise deployments resolves many multilingual
configuration issues, this solution also requires more resources and maintenance.
It may be more cost-effective to deploy one Crystal Enterprise system for use with
multiple languages. Also, a multiple deployment solution is possible only for
localized languages.
Note: Separate Crystal Enterprise systems cannot share information. To distribute
an object using more than one system, you must publish the object to each system.
Deploying one Crystal Enterprise system for multiple languages
If you do not have the resources required for multiple deployments, or if the
majority of your users do not speak one of the languages that Crystal Enterprise is
available in (English, French, German, or Japanese), you can deploy one Crystal
Enterprise system for multiple languages. By delivering one system for multiple
languages, you may be able to leverage resources you already have. Depending on
the languages you need, you may be able to provide access to a single server from
clients using different languages. If you need to provide a system for a language
that Crystal Enterprise is not available in, deploying one system for multiple
languages is the best solution.
When you use multiple languages within the same Crystal Enterprise deployment,
you can expect to encounter different languages in the user interface. The
languages used for each component may vary depending on the language defaults
450
Crystal Enterprise Administrator’s Guide
E: International Deployments
and available language files. Some components get language information from the
software itself, while others depend on settings in the browser or operating system.
Most versions of Crystal Enterprise must run on an operating system that uses the
same language. However, the English version of Crystal Enterprise can run on an
operating system that uses any supported language, using client components such
as the web desktop that use the same language, or English. You can run the English
version of Crystal Enterprise on an operating system that uses one of the following
languages: French, German, Japanese, Spanish, Italian, Korean, Simplified
Chinese, or Traditional Chinese. You can access the English client tier components
using a browser with the same language as either the server’s operating system or
the Crystal Enterprise software installed on the server.
Multilingual access to client tier components such as the Crystal Enterprise web
desktop depends on the languages you need. For French, German, and Japanese
versions of Crystal Enterprise, you can install the appropriate version of the web
desktop in a separate directory. For other supported languages (Spanish, Italian,
Korean, Simplified Chinese, and Traditional Chinese), you can customize the Web
interface to display the same language as your server’s operating system. For
details, see “Providing a client tier for multiple languages” on page 453.
In the previous scenario, two Crystal Enterprise systems were deployed: one for
English and one for Japanese. If the company did not have the resources to install
and maintain Crystal Enterprise systems for both English and Japanese, they could
combine the two into one deployment.
With the English version of Crystal Enterprise installed on a Japanese operating
system, you can access the system using English and Japanese web browsers.
To provide Japanese client components, you need to install the Japanese version of
the Crystal Enterprise web desktop or customize your web client. The English
version of Crystal Enterprise will automatically install the English client components
such as the web desktop. For Japanese users, you need to install a Japanese version
of the client components under a different directory than the English version.
Note: This solution currently works only with the English version of Crystal
Enterprise. For example, you cannot run the French version of Crystal Enterprise
on a Japanese operating system.
Crystal Enterprise Administrator’s Guide
451
Deploying Crystal Enterprise internationally
Deploying one system for multiple languages is the best solution for non-localized
languages. If you run English Crystal Enterprise components on an operating
system that uses one of the supported languages, you can access the components
from a browser that uses the same language as the operating system. Because
standard Crystal Enterprise client components are available only in localized
languages, you need to customize them in order to support other languages.
For example, if half of your employees are Italian, and the other half are English,
this deployment displays the appropriate language most of the time for both
Italian and English employees.
This deployment is similar to the English and Japanese system, except that the
client components must be customized to display Italian. For Japanese users, you
were able to install the localized Japanese client components. For Italian users,
however, you must customize the web interface to create your own Italian client.
Publishing reports created in a different language
You can publish reports created in any supported language to any Crystal
Enterprise system. All Crystal Enterprise configurations allow you to publish
reports written in a supported language, even if Crystal Enterprise, the operating
system, or the browser do not use the same language. For the complete list of
supported languages, see “Languages” on page 447.
As long as the required font and language files are installed on the servers in the
system, you can create reports in any supported language and publish them to any
version of Crystal Enterprise. Keep in mind that most of the application will be
displayed in the same language as the operating system, the browser, or the
Crystal Enterprise components.
If only a few people create reports in languages other than those used across most
of your organization, it is more cost-effective if they publish their reports to the
same system. For example, if you hired three new employees in China and Spain,
you could ask those employees to publish their Chinese and Spanish content to an
existing English or Japanese system.
452
Crystal Enterprise Administrator’s Guide
E: International Deployments
Providing a client tier for multiple languages
By default, Crystal Enterprise installs and configures a client tier in the same
language as its server components. For example, the English version of Crystal
Enterprise installs the English version of the Crystal Enterprise web desktop. To
support multiple languages in the Crystal Enterprise web client tier, you must
maintain multiple sites for each language.
If you are using the English version of Crystal Enterprise, and you need to provide
a web desktop in English and another localized language, you can install the
localized version of the client components under a different directory from the
directory that contains the English components.
For example, if you need a Japanese client tier for use in a Japanese browser, install
the Crystal Enterprise web desktop from the Japanese version of Crystal Enterprise.
Make sure the Japanese version is stored in a different subdirectory than the
English version. Provide your Japanese users with the alternate directory URL.
To set up a client tier in Italian, Chinese, Korean, or Spanish that will work with an
English server, you can create your own client components that appear in the
required language.
Crystal Enterprise uses Crystal Server Pages (.csp files) or Java Server Pages (.jsp
files) to display client components such as the Crystal Enterprise web desktop.
Each .csp or .jsp file includes strings that are set as constants at the beginning of the
file. To create a client tier for a non-localized language, copy the .csp or .jsp files
into different subdirectories, with one language for each subdirectory, and edit the
string constants to display the language you want.
Designing reports for an international audience
After deploying and configuring Crystal Enterprise to meet the needs of your
international users, you can establish Crystal report design guidelines that will
help your users create reports that work globally. By following guidelines for
report design, you can make it much easier to deliver content to multilingual users.
When creating a report that must present data in multiple languages, you should
consider the fonts being used, the amount of the report that needs to be translated.
You can use conditional formatting to create a report that accounts for the formatting
requirements of multiple languages, or you can even provide translation directly in
the report.
Conditional formatting for multiple languages
Many report design techniques that account for differences between languages
require a language parameter field that prompts the user to choose a language for
the report. This language parameter field can be used for conditionally formatting
report objects to account for conventions used for different countries or languages.
Crystal Enterprise Administrator’s Guide
453
Designing reports for an international audience
For example, you may need to change fonts in order to display characters for a
different language. Or you may need to change display settings to accommodate
larger words or longer sentences.
If the report contains only a few objects that need translation, you may want to
provide language-specific formatting for individual report objects. For each
characteristic of a text object that you want to change, you must provide a
conditional formula that provides the translation for each supported language.
Alternatively, you can create sections with different formatting and conditionally
suppress them based on the language parameter field. For example, if you need a
report to appear in French and German, you can create a second Details section for
German that contains the same fields displayed in wider object frames to
accommodate longer values. Using conditional formulas, you can suppress the
French or German section based on the language parameter field.
To create a language parameter field
1 In Crystal Reports, on the View menu, click Field Explorer.
2 In the Field Explorer, right-click Parameter Fields and click New.
3 In the Create Parameter Field dialog box, type the parameter name
(reportlanguage, for example) and the prompting text (Choose the language
for the report).
4 Ensure that the Value type is set to String.
5 Click Set default values.
6 In the Set Default Values dialog box, type each language you want and move it
to the Default Values area using the arrow buttons.
7 Click OK.
8 Click OK in the Create Parameter Field dialog box.
Formatting text in multilingual reports
Different languages require different fonts and formatting conventions. You can
conditionally change the text font and formatting using a language parameter field.
Using multiple fonts
Fonts can cause a number of issues when a report is provided in several languages.
Not all fonts support all languages, and some languages require special formatting
conventions for text.
When you have multiple languages in a report, you need to consider whether any
of the languages require special fonts. You can use the same font to display both
French and English in a report. If you need the report in French and Russian,
however, you will need a different font for the Russian characters.
454
Crystal Enterprise Administrator’s Guide
E: International Deployments
Note: Ensure that the required font files are installed on all machines in your
Crystal Enterprise system. For details, see “Resources” on page 448.
If the report contains languages that require different fonts, you need to use
conditional formatting to change the font based on the language chosen by the user.
You must apply conditional formatting to every field that requires font changes.
To specify the language, use a parameter field to prompt the user to choose a
language for the report. You can then insert the parameter field into a conditional
formula that changes the font if the parameter has a particular value.
To change the font using conditional formatting
1 Right-click the field, choose Format Field, and then click the Font tab.
2 Click the conditional formula button next to the Font list.
Note: For details on conditionally formatting fields and using the Format
Formula Editor, see the Crystal Reports Online Help.
3 In the Formula Editor, create a formula to change the font based on the
language parameter (?reportlanguage, for example)
If {?reportlanguage}=”Russian” then “Bukinist”
Else “Arial”
4 Click Save and close, then click OK.
Formatting text based on language
You can also use conditional formatting to account for other formatting differences
between languages. For example, German words are often much larger than
French words. You can conditionally format your text to be a smaller font to
account for larger words, or you can enable the Can Grow setting to ensure that
words will not be clipped.
To format text conditionally
1 Right-click the field, choose Format Field.
2 On the Common tab, create a conditional formula that selects the Can Grow
option if the user chooses a specific language.
{?reportlanguage}=”German”
3 On the Font tab, create a conditional formula for the Size list that displays a
smaller font if the user chooses a specific language
If {?reportlanguage}=”German” then 10
Else 12
4 Click OK.
Crystal Enterprise Administrator’s Guide
455
Designing reports for an international audience
Formatting based on cultural conventions
When you deliver content in multiple languages, you will encounter other
differences that will need to be accounted for. Different languages and countries
have different cultural conventions for currency, dates, time, and punctuation.
For example, in English, the integer portion of a number is separated from the
fractional portion by a period. Most European countries use a comma as the
separating character. The thousands separator is a comma for English, and a
period for German. In English, digits are grouped in threes, but other languages
use other grouping conventions. In Nepal, numbers are formatted with one group
of three numbers to the left of the decimal, and subsequent groups are two digits.
Each language has its own rules and conventions. The best way to ensure that you
meet the reporting needs of users of every language in your organization is
through testing.
The following is a list of other common issues to keep in mind when reporting in
several languages. Ensure that your reports account for these cultural differences.
You can account for many differences by using conditional formatting to change
formats and preferences based on the language parameter field. You can use formulas
such as the ones used in “Formatting text in multilingual reports” on page 454.
• Alphabetical order
Different languages have different alphabets. Check the accuracy of any
alphabetical sorting in your reports.
• Calendars
Different countries have different statutory holidays. For scheduling, you can
create custom calendars to account for different sets of holidays or working
days. For details, see “Managing calendars” on page 214.
• Currency conventions
Different languages and currencies may have different conventions for
formatting currency. For each language, make sure you check the placement of
the currency symbol and the conventions for formatting negative currency.
Note: The Euro symbol does not display properly in many fonts. If you use the
Euro symbol, make sure you test the fonts displayed in your report. If the font
does not display the Euro symbol properly, you may need to change fonts. If
your report displays many different currencies, you can use conditional
formatting to change the font whenever the currency symbol is the Euro.
• Date conventions
Date formats vary between countries. Make sure you adhere to the appropriate
date convention for each language available in your report. For example,
“Thursday, May 14, 2003” is displayed as “Donnerstag, 14. Mai 2003” in
Germany. Notice the different date punctuation and structure.
• Punctuation
Different languages use different punctuation marks. For example, German
and English use different styles of quotation marks.
456
Crystal Enterprise Administrator’s Guide
E: International Deployments
• Time zones
Avoid granting Schedule access to the default Guest account if you deploy the
Crystal Enterprise web desktop for users in different time zones. Instead, ensure
that each user who is allowed to schedule reports has a dedicated account on the
system, and that each user's preferences include the appropriate time-zone setting.
To view or modify the time-zone setting for any user account, use the Preferences
Manager, which is available as a Client Sample on the Crystal Enterprise User
Launchpad. Dedicated accounts are recommended because the default Guest
account does not allow users to modify account preferences that would affect
other users. For more information about using specific time-zone properties in
your custom web applications, see the Crystal Enterprise Web Developer's Guide.
Providing multiple languages in a single report
To provide multiple languages in the same report, you can create multiple text objects
or sections and conditionally suppress them using the language parameter field.
Note: For details on creating a language parameter field, see “Conditional
formatting for multiple languages” on page 453.
Using multiple text objects
If a report contains only a few text objects to be translated, you can provide
translations for individual text objects, and conditionally suppress them using the
language parameter field. For details on creating a language parameter field, see
“Conditional formatting for multiple languages” on page 453.
To maintain the text’s position in the report, you can place text objects for each
language on top of each other. This solution can become illegible; if a report
includes many text objects, consider using suppressed sections for each language.
Using multiple sections
Instead of formatting individual report objects conditionally, you can use the
language parameter field to conditionally suppress sections. You can create sections
for each language and suppress or show them based on the parameter value the
user selects. Creating separate sections for translated versions of report content is
faster and more flexible than creating individual reports for each language.
To suppress a section
1 Create a section for each language you want to appear in your report.
2 Right-click the left boundary of one of the sections and click Section Expert.
3 In the Section Expert, click the Formula button that corresponds to the
Suppress (No Drill-Down) setting.
The Format Formula Editor opens a new formula named Suppress (No DrillDown).
Crystal Enterprise Administrator’s Guide
457
Designing reports for an international audience
4 In the Formula text window, type this formula (which uses Crystal Syntax):
if {?reportlanguage} <> "yourlanguage" then True
where yourlanguage is the language used in the section. It must be a language
that is available as an option in your ?reportlanguage parameter field.
If the user did not choose yourlanguage as the report language, this formula
enables the setting and suppresses the section for that particular language.
5 Create similar formulas for all language-specific sections in the report.
6 Click Save and close.
7 Click OK in the Section Expert.
458
Crystal Enterprise Administrator’s Guide
Creating Accessible Reports
F
This appendix provides design recommendations to help
you create Crystal reports that are accessible to people with
disabilities.
Crystal Enterprise Administrator’s Guide
459
About accessibility
About accessibility
When you create Crystal reports for a large audience across the organization—and
around the world—you need to account for the diverse needs of that audience. Report
designers often create reports for specific languages, countries, job tasks, or work
groups, but it is also important to consider the accessibility requirements of users.
Report users may have physical, sensory, or cognitive limitations that affect their
ability to access the Web. They may not be able to see, move, or hear. They may
have low vision or limited movement. Some people have dyslexia, color-blindness,
or seizure disorders; others have difficulty reading or understanding text. They
may have a combination of disabilities, with varying levels of severity.
People with disabilities often use assistive technologies: products or techniques that
help people perform tasks they cannot perform otherwise. Assistive technologies
include adaptive software programs such as screen readers (which translate text
into audible output), screen magnifiers, and speech-recognition software. People
with disabilities may also use special browsers that allow only text or voice-based
navigation. They may use assistive devices such as refreshable Braille displays, or
alternative keyboards that use “sip-and-puff” switches or “eyegaze” technology.
To meet the reporting needs of people with disabilities, your reports should be
designed to work with as many assistive technologies as possible.
Despite the wide range of potential accessibility issues, you can use the techniques
described in this chapter to create reports that are useful for everyone.
Benefits of accessible reports
As more business and government leaders adopt new standards for delivering
web content to people with disabilities, accessible design is becoming critical to
information management and delivery.
Accessible design provides many benefits:
• Accessible reports are easier for everyone to use.
Many accessibility guidelines result in improved usability. An accessible report
must provide logical and consistent navigation. Its content must be clearly
written and easy to understand.
• Accessible reports are more compatible with a variety of technologies, new
and old.
Accessible content is easier to export to simple formats that are more
compatible with mobile phone browsers, personal digital assistants (PDAs),
and other devices with low-bandwidth connections.
Some people may not have a keyboard or a mouse. They may have a text-only
screen, a small screen, or a slow Internet connection. Accessible design makes
it easier for people with limited technology to access information.
• Accessible content is easier to reuse for other formats.
In the viewers, accessible reports are more accurately copied or exported to
other formats.
460
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
• Accessible reports improve server efficiency.
You may reduce the number of HTTP requests on the server, by providing clear
navigation so people can find what they need faster. Providing text-only
alternatives can reduce the number of graphics, which take up valuable bandwidth.
• Recent initiatives indicate a worldwide trend towards providing accessible
web content.
More companies are making accessibility a requirement for their web content,
especially in the United States, where the government introduced section 508 of
the Rehabilitation Act. Accessibility is quickly becoming an essential part of
web content delivery.
• You may be legally required to provide accessible content.
Each year, more countries introduce anti-discrimination laws that ensure equal
opportunities for people with disabilities. Even if you are not legally required
to meet accessibility guidelines, you may want to do business with an
organization that is required to adhere to them.
• Creating accessible reports is easier than modifying existing reports to make
them accessible.
If you build accessible features into your reports now, it will be significantly
less expensive than to redesign existing reports later.
About the accessibility guidelines
The most comprehensive accessibility guidelines are the Web Content Accessibility
Guidelines (WCAG), developed by the international World Wide Web Consortium
(W3C). The WCAG is widely considered the definitive set of recommendations for
delivering web content to people with disabilities. The WCAG has influenced the
development of similar web content standards around the world.
Organizations and governments worldwide are adopting the accessibility
recommendations of the W3C. In Australia, the Disability Discrimination Act
includes standards for web site accessibility. Similar guidelines have been
introduced in the United Kingdom and throughout Europe. In Canada, all
government web content is now developed according to the Common Look and
Feel (CLF) initiative, which is largely based on the W3C's Web Content
Accessibility Guidelines. Taking web accessibility a step further, the United States
government introduced legislation in the form of Section 508 of the Rehabilitation
Act, which ensures the right to accessible government web content.
Common to all guidelines is a focus on providing web content that is useful for all
people, regardless of disability or impairment. For reports, accessible design is
focused on the same key concepts:
• Content must be easy to understand and navigate.
• Text equivalents or alternatives should be provided for non-text objects.
• Objects should be logically organized to clarify relationships between objects.
Crystal Enterprise Administrator’s Guide
461
Improving report accessibility
• Reports must not rely on any one specific type of hardware, such as a mouse, a
keyboard, or a color screen.
For more information on specific accessibility guidelines, see “Resources” on
page 481.
Accessibility and Crystal products
Crystal products allow you to design accessible reports and deliver them to your
users via the Web. By observing accessibility guidelines, you can use Crystal Reports
to create reports that are accessible to users with disabilities. You can then publish
these reports to Crystal Enterprise, where people with disabilities can view them on
the Web using the Crystal Enterprise web desktop and the DHTML viewers.
The reports in this chapter were created in Crystal Reports and tested using screen
readers (including JAWS 4.5).
However, Crystal Reports does not currently provide complete accessibility for
report designers with disabilities.
Crystal Enterprise's management components, including the Crystal Management
Console (CMC) and the Crystal Configuration Manager (CCM), do not currently
provide access for people with disabilities. The ActiveX and Java viewers are also
not accessible.
In the Crystal Enterprise web desktop, the main user interface for working with
reports through Crystal Enterprise, the ability to log on and view reports is
accessible for most users. However, other areas, such as new account sign up and
scheduling, may not be accessible.
Note: Although you can use many of the same design guidelines to improve the
accessibility of Crystal Analysis Professional reports, Worksheets are difficult to
format for accessibility. Crystal Reports is the recommended option for delivering
reports to people with disabilities.
Improving report accessibility
To begin improving the accessibility of your Crystal reports, start with accessibility
guidelines that are quick and easy to implement. A small change in your design
conventions or company template may have a significant impact on accessibility.
Simple navigation and clearly-written content are critical for accessibility, but they
are easy to implement and useful for all report users.
Placing objects in reports
There are a few general guidelines to keep in mind when you place objects on a report.
462
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
Organizing objects logically
When you place objects on reports, make sure their placement is clear and logical,
especially when you need to imply a relationship between two objects in a report.
For example, if you include a text description of a chart, ensure that it is close
enough to the chart to make the connection clear.
Many assistive technologies read from left to right and from top to bottom;
therefore, if you include a text description and title for a chart, you should decide
which one you want the user to read first. This will ensure that the objects in a
report are read in the correct order.
Placing objects in order
When you publish a report to Crystal Enterprise, the HTML version organizes the
objects in the report according to the consecutive order that you added them in
Crystal Reports, not according to where they were positioned on the report. The
report appears the same on the screen, but the underlying HTML code lists the
reports objects in the order they were inserted. Instead of reading the report from
right to left and top to bottom, screen readers and other assistive devices may
follow the order specified in the HTML. To make a report accessible, you must add
objects to reports in the order that you want a screen reader to read them.
For example, you place Quarter, Year, and Invoice fields in the Details section and
then add the report title “Invoices by Quarter” to the Report Header. When you
publish the report to Crystal Enterprise, it looks the same as it did in Crystal
Reports, but the underlying HTML displays the database field headings first,
followed by the title. Instead of reading the report title first, a screen reader reads
the headings first: “Quarter, Year, Invoice, Invoices by Quarter.”
To avoid this, insert the “Invoices by Quarter” title first. Before you add the data table,
you could provide an introductory text object that describes the table. Finally, add the
fields to the Details section. The report will now make more sense in a screen reader,
which will read “Invoices by Quarter”. The following table lists our invoices for each
quarter. Quarter, Year, Invoice.” followed by the data. (For details on providing
accessible data tables, see “Improving data table accessibility” on page 473.)
Therefore, to create accessible reports, you must plan the order of your report
before you begin working in Crystal Reports. Plan it on paper. Make sure you
know which objects you want to add and where you want them. Include all
calculations, images, and charts on your plan. When you create a new report based
on your plan, you can start adding objects from the upper left corner and work
your way to the bottom right corner of the report. Once the objects are placed, you
can make changes to them afterwards without affecting their order.
Note: If you create a text-only alternative of your report, add it to your report as a
subreport and, most importantly, add the subreport before you add any other
object to your report. For further details, see “Text” on page 464.
Crystal Enterprise Administrator’s Guide
463
Improving report accessibility
After you add all objects to the report, you can test their placement order by
tabbing through the objects.
To test the placement order of objects in a report
1 Make sure no objects in the report are selected.
2 Press the Tab key.
Crystal Reports selects the object that was placed on the report first.
3 Tab through the remaining objects.
The order that Crystal Reports uses to tab through the objects is the same order
adopted by a screen reader that views the published version of the report.
Text
The most common accessibility issue encountered by report designers is also one
of the easiest to resolve: providing text-only versions of non-text objects. A non-text
object is an object that conveys meaning through a picture or sound. Non-text
objects include pictures, charts, graphical buttons, graphical representations of
text, sounds, animations, and audio or video clips.
People who use assistive technologies are accustomed to text-only substitutes and,
therefore, will respond well to the text-only alternatives you provide.
There are a number of ways you can use text to substantially improve your reports’
accessibility:
• Provide text equivalents for objects in reports.
• Provide text alternatives for reports.
• Ensure that text is written and formatted clearly.
Text is a useful tool for creating accessible reports. Most assistive technologies
require text input, including screen readers, speech synthesizers, and Braille
displays. You can easily resize and format text, and text is the most flexible
medium for import and export.
Providing text equivalents
When you create reports, there are many opportunities to use text equivalents to
clarify non-text objects.
• Place a descriptive text object next to a non-text object, and be sure to add them
to the report in consecutive order (for more details see “Placing objects in
order” on page 463).
Whenever possible, a text equivalent should communicate the same information
as its corresponding object in the report. If a report displays data in a pie chart,
for example, include a text box next to the chart that summarizes its contents.
Describe the purpose of the non-text object. For example, if an image performs
an action when you click it, describe the action. For a button that opens your
web site, provide a text box labeled “Click to view our web site.”
464
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
• If a report includes audio links, provide a transcript for significant audio clips.
• If a report links to a multimedia or video presentation, provide a transcript.
You may also want to provide captioning for the audio portion and an audio
description of the visual portion. Captioning should be synchronized with the
audio.
Providing text-only alternatives
If there are too many non-text objects on a report, or if you do not have the
resources to integrate accessible design into all of your reports, then you can
provide complete text-only alternatives. For reports that represent data using only
charts and graphics, for example, you can provide a link to a text-only alternative
that provides the same data in data tables and text objects.
Whenever possible, a text-only alternative should provide the same information as
the original report. The information conveyed through images in the main report
should also be described using text objects on the alternative report.
Note: If you cannot produce a complete text-only version of the report, you can
still improve accessibility by providing a descriptive summary of key information
or conclusions illustrated by the report.
It is good practice to provide the text-only alternative on a subreport, linked from
the top left corner of the main report, so the user has the opportunity to switch to
the text-only version as soon as possible. Add the subreport to the report before any
other object to ensure that a screen reader will read it first. If you want the subreport
link to appear only for people using screen readers or similar software, you can
create a subreport link that is the same color as the background color. The link will
appear as a small blank space, but a screen reader will read the text for the link.
To add a text-only alternative to a subreport
1 Create a text-only version of the report and save it.
2 Open a new report.
3 On the Insert menu, click Subreport.
4 In the Insert Subreport dialog box, select Choose an existing report and click
Browse to locate the report you created in step 1.
5 Click the subreport, then choose Format Subreport from the Format menu.
6 In the Format Editor, on the Subreport tab, select On-demand Subreport.
7 To hide the subreport link, on the Font tab, choose the color that matches the
background color of the report.
Note: Instead of hiding the subreport link, you can conditionally suppress the
section that contains the subreport. For details, see “Accessibility and
subreports” on page 472.
Crystal Enterprise Administrator’s Guide
465
Improving report accessibility
Using punctuation
To improve the logical flow of spoken text, you may need to add extra punctuation
to create pauses. Without extra punctuation, screen readers may read several text
objects as one continuous sentence, making the content difficult to understand. For
example, information in data tables may be read without stop. To prevent this, you
can break up information in data tables by inserting periods between fields.
Certain punctuation marks are read aloud, which may be distracting if used too
frequently. For example, when a screen reader reads a colon “:”, it may read it
aloud as “colon” instead of a pause. You can change the amount of spoken
punctuation in your screen reader's settings.
To troubleshoot your report's punctuation, it is good practice to read the report
using a screen reader. Do objects run together too quickly? Or are there too many
pauses? Are any punctuation marks read aloud? Does this improve or deter from
the usability of the report?
Formatting text
After you create text equivalents or alternatives for non-text objects, ensure that the
text is clearly written and easy to read. Observe the following design guidelines:
• Use a larger font.
Although people with visual impairments can use the Zoom feature to increase
the size of the report, they will not need to magnify the report as much if the
font size is larger. For example, chart labels or legends can appear in a small
font by default. For general legibility, it is good practice to use a font larger than
8 point. For accessibility, ensure that text is larger than 11 point.
• Use a “sans serif” font.
Simple fonts such as Arial and Helvetica can be easier to read than serif fonts
like Times or Palatino.
• Choose left or justified alignment.
Left-aligned or justified text is easier to read than centered or right-aligned text.
• Ensure that text follows the guidelines for color usage. For details, see “Color”
on page 467.
Note: You can allow users to choose different font settings using a parameter and
conditional formatting. For details, see “Accessibility and conditional formatting”
on page 471.
Finding the right balance between text and non-text objects
Text equivalents are very flexible and often the best solution for accessibility, but
they are not always necessary or preferred.
Not all non-text objects require text equivalents. You need to include text
alternatives only for non-text objects that provide information or navigation
elements that the user cannot do without. Images used for decorative purposes do
466
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
not need a text description. If a report has a watermark image that acts as a
background for the data, you do not need to provide a text equivalent. Adding text
descriptions for decorative objects can produce unnecessary clutter.
Text versions of visual or auditory objects in reports should be used as a
complement to the object—not as a replacement. You do not need to remove nontext objects. Visual objects in reports can be very helpful, especially for people with
learning disabilities such as attention deficit disorder, or for people who are deaf.
People with hearing impairments may be accustomed to visual communication
such as sign language, and may find images more useful than text.
No one presentation method can meet the needs of all users. Audio clips can be
very useful for people with visual impairments, but people with hearing
impairments will be unable to use them. To help both groups, provide a
combination of audio and text. Multimedia presentations may provide audio
information for people with visual impairments, as well as video information for
people who are deaf or hard of hearing. Multimedia presentations are particularly
effective for people with attention deficit disorder. However, people with certain
mental health disabilities may be distracted by visual or audio objects.
The best approach is to communicate the same information with both text and nontext objects. Add descriptive text to support the images, and add images that
support the text.
If text objects begin to overwhelm your report, you may want to provide a
complete text-only version in a separate report or a subreport. For details, see
“Providing text-only alternatives” on page 465.
To learn more strategies on how to choose presentation methods that meet the
needs of a variety of audiences, see “Designing for flexibility” on page 470.
Color
The colors you choose for objects in reports can have a significant impact on
accessibility for people with visual impairments, low vision, or color blindness.
Ensure that your reports can be understood when viewed without color.
Contrasting colors
Users with limited vision may be unable to distinguish between colors. To test the
color contrast in your report, print or view a black and white copy. You should be
able to distinguish between values or fields displayed in different colors (in a pie
chart, for example).
If you cannot distinguish between colors on the report, try different colors or use
gray shading. If this does not resolve the issue, you can change other characteristics.
For text, use the Format Editor to change the font, size, or style. You can add borders,
underlining, or background shading to differentiate text objects from each other.
Crystal Enterprise Administrator’s Guide
467
Improving report accessibility
For charts, use a combination of shading and patterns. You can automatically
convert a color chart to a black and white one using the Chart Expert, or you can
select values individually and choose your own patterns.
To convert a chart into black and white
1 Select the chart and choose Chart Expert from the Format menu.
2 In the Chart Expert, click the Options tab.
3 In the “Chart color” area, select Black and white, then click OK.
The chart colors convert to a variety of high-contrast pattern and color fills.
To change the fill for a chart value
1 Select the chart, then click the shaded area you want to change.
2 On the Chart menu, point to Chart Options, and then click Selected Item.
3 In the Formatting dialog box, on the Fill tab, choose a color and click Pattern.
4 In the Choose A Pattern dialog box, click a pattern, then click OK.
Note: You can also select a texture, gradient, or picture as a fill for the chart value.
See the Chart Help for more information.
Using color to convey information
Do not use color as the only identifying characteristic for critical information in a
report.
For example, a text object may instruct users to “click the green button” to open a
subreport. Users with limited vision cannot tell which button is green. The button
should be recognizable by another defining characteristic besides its color. For
example, you can change the button graphic to a shape that is not used elsewhere
on the report, and instruct users to “click the green arrow button”. This solution
provides color information for people who can distinguish colors, and extra
information for people who cannot.
Other common situations where color may be used to provide important
information include:
• Highlighting
To highlight particular values in a table, do not change only the color of the
value. If you highlight outstanding invoices in red, for example, they may look
the same as the paid invoices to someone with limited vision. In the Highlighting
Expert dialog box, change a font characteristic other than color, such as font style.
• Hyperlinks
Using color as the only method for identifying hyperlinks may also cause
problems for color-blind users. When you print your report in black and white,
check the hyperlinks to ensure that they are still visible.
468
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
• Identifying important areas of the report
Do not organize a report by using color as a background or as a separator
between different sections or areas. Instead of using color to identify sections,
establish clear and consistent navigation for the entire report.
Navigation
As with other aspects of accessible design, providing several alternative
navigation methods can help you meet the reporting needs of more people. The
W3C recommends including several different navigation methods. On the other
hand, simplicity is critical for intuitive navigation. Section 508 recommends simple
navigation that uses the least number of navigation links possible. Either approach
can be effective for your reports, as long as you maintain clarity and consistency.
You may want to use report parts to navigate a report (or to connect several
reports). If you provide a series of links in a page header, keep in mind that screenreading software will reread the navigation information every time the user
refreshes the page or views a new page. In this case, simple navigation is preferable.
For a large report, you could provide a list of navigation links as a table of contents
in the report header. More extensive navigation can be useful when you have a
large volume of data. To allow users to skip the list, you could start with a “Skip
the table of contents” link that jumps ahead to the first page header.
In general, report navigation should follow these guidelines:
• Identify the target of each link.
• Provide information at the start of the report that describes the layout and
navigation.
• Use navigation consistently.
• Provide the opportunity to skip repetitive navigation links.
Parameter fields
When you include parameter fields in a report, make sure they are clear and
simple. Although parameter fields can be a useful tool for providing accessible
content, they can also introduce several accessibility concerns. It is important to
test all parameter fields for accessibility.
Parameter fields should follow these guidelines:
• Provide a list of default values for the user to choose from.
Avoid requiring the user to type a value for a parameter. When users provide
their own values, they need to make sure the format of the value will be
recognized by the parameter field. A list of default values is easier to use, and
it ensures that the user chooses from values with valid formats.
• Try to avoid complex parameter fields.
A complex parameter field may be more accessible when it is broken down into
multiple parameters. When you test the accessibility of your parameter fields,
Crystal Enterprise Administrator’s Guide
469
Designing for flexibility
pay particular attention to parameters that require a range. It may be easier to
understand if you provide two parameter fields that prompt for discrete values
for the top and bottom of the range, rather than ask the user to choose both
values in the same parameter field.
• For date fields, do not allow users to choose their own values.
The calendar used to select date values is not currently accessible. Provide a
pick-list of default date values. Using a list of default values also helps avoid
invalid date formats.
Designing for flexibility
Flexibility is the key to providing accessible reports. Because different users
require different levels of accessibility, it is good practice to provide a variety of
presentation styles and methods to meet the needs of as many people as possible.
For a detailed report, however, you may not be able to provide multiple
presentation styles without cluttering the report with extra objects.
To address this problem, plan the degree to which you want to integrate accessible
formats into your reports. You can provide accessible formatting for each object,
for each section, or as a subreport. You can then allow users to choose their own
accessibility options using a parameter field that prompts them to choose whether
or not to display accessible formats.
Using this parameter field, you can conditionally format objects, or conditionally
suppress sections that address different access needs. Or you can provide different
display options by using subreports.
To create an accessibility parameter field
1 In Crystal Reports, on the View menu, click Field Explorer.
2 In the Field Explorer, right-click Parameter Fields and click New.
3 In the Create Parameter Field dialog box, type the parameter name (Access, for
example) and the prompting text (Do you want to enable accessible
formatting for this report?).
4 Ensure that the Value type is set to String.
5 Click Set default values.
6 In the Set Default Values dialog box, create Yes and No values and move them
to the Default Values area using the arrow buttons.
7 Click OK.
8 Click OK in the Create Parameter Field dialog box.
470
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
Accessibility and conditional formatting
Using the accessibility parameter field in simple formulas, you can provide
multiple formats for any object in a report. If a user chooses “Yes” when prompted
by the parameter, the conditional formulas will ensure that the objects are modified
with accessible formatting conventions. If a user chooses “No”, then the report
appears without accessible formatting, perhaps in the standard company template.
For accessible text formatting, you can follow the guidelines suggested by this
chapter and by the W3C, or you can survey your report users to determine the
formats that work best for them. After you determine the formatting options you
want to use, you can create conditional formulas that define the options. For
example, you can display all database fields in a large Arial font, in white text on
a black background, with the Can Grow option enabled.
The following procedure creates a conditional formatting formula based on the
?Access parameter field. The formula increases the font size if the ?Access
parameter field is set to “Yes”. You can use similar formulas to change colors, add
borders, or enable the Can Grow setting. For complete instructions on
conditionally formatting fields and using the Format Formula Editor, see the
Crystal Reports Online Help.
Note: If text objects are too small to accommodate the enlarged font, you can use a
similar conditional formatting formula to enable the Can Grow setting, which
appears on the Common tab of the Format Editor.
To apply accessible settings to font size conditionally
1 Open the report in the Design tab of Crystal Reports.
2 In the Details section, right-click the field you want to conditionally format,
and select Format Field.
3 In the Format Editor, click the Font tab.
4 Click the Formula button that corresponds to the Size list.
The Format Formula Editor opens a new formula named Font Size.
5 In the Formula text window, type this formula (which uses Crystal Syntax):
if {?Access} = "Yes"
then 20
else 10
This formula ensures that the font size for the currently selected field is increased
from 10 point to 20 point when the user chooses to display accessible formatting.
6 Click Save and close.
Crystal Enterprise Administrator’s Guide
471
Designing for flexibility
Accessibility and suppressing sections
Instead of formatting individual objects conditionally, you can create separate
sections for accessible versions of the report content, then use the accessibility
parameter field to conditionally suppress sections. The accessible and non-accessible
sections can be suppressed or shown, based on the parameter value the user selects.
Creating separate sections for accessible versions of report content may be more
time-consuming, but there are a few situations where suppressing sections
conditionally can be more practical than formatting on the object level:
• If a report contains many objects, suppressing sections may require fewer
conditional formulas.
• Not all settings and features can be formatted conditionally. By suppressing
sections, however, you can make any formatting changes you want.
• You may want to provide completely different types of information for people
viewing the accessible version of the report. For example, you may want to
split visual and audio objects into two different sections and conditionally
suppress them based on the parameter value the user chooses.
To suppress an accessible section
1 Right-click the left boundary of the section you want to suppress
conditionally, and click Section Expert.
2 In the Section Expert, click the Formula button that corresponds to the
Suppress (No Drill-Down) setting.
The Format Formula Editor opens a new formula named Suppress (No DrillDown).
3 In the Formula text window, type this formula (which uses Crystal Syntax):
if {?Access} = "No" then True
This formula selects the Suppress option if the user chooses not to view
accessible report content.
4 Click Save and close.
5 Click OK in the Section Expert.
Accessibility and subreports
Accessible report design may become too cumbersome using conditionally
formatted objects and suppressed sections. Two situations in particular may be
problematic:
• To make the report accessible, you may need to change the overall organization
of the report sections, or you may need to provide different objects.
• If the report contains a large number of objects or sections, it may take too
much time to create conditional formulas for all of them.
472
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
For example, if a report contains many non-text objects displayed in a complex
series of groups and sections, you may want to provide a text-only version that uses
different objects and a simplified group structure to meet accessibility guidelines.
The easiest way to address this problem is to create a subreport that displays the
accessible version of the report and place the subreport at the beginning of the main
report. For details on creating a text-only accessible subreport, see “Providing textonly alternatives” on page 465.
If you want only screen readers to be able to see the subreport, you can hide it by
changing the subreport link to the same color as the background. Alternatively,
you can use the ?Access parameter field to allow users to choose whether or not
the subreport appears in the report. Place the subreport in its own section and
conditionally suppress the section based on the ?Access parameter field. For
details, see “Accessibility and suppressing sections” on page 472.
Improving data table accessibility
Large tables of data can be difficult to interpret if a person is using a non-visual
means of accessing the web, such as a screen reader. People using screen
magnifiers or the Zoom feature may also find data tables hard to navigate because
they cannot see the table headings at all times. It can easily become difficult to
associate the value that a screen reader is reading with the corresponding column
and row headings. Users need to be able to understand the data value's position in
the table and its relationship to other values.
To improve data table navigation, you can use text objects to provide contextual
information with each value. Using conditional formatting or suppression, you can
create a report that displays these objects only if the user chooses to view them.
Other design guidelines can help make large tables of data easier to understand,
such as providing summary paragraphs and expanded column headings.
Note: This chapter uses terminology consistent with the W3C accessibility
guidelines. In these guidelines, the term data table refers to values arranged in
columns and rows. In Crystal Reports, data tables take the form of group or page
headings combined with database fields in the Details section. Do not confuse
data tables with database tables, which are data sources used by Crystal Reports.
Text objects and data table values
You can make a large table easier to understand and navigate by adding text
objects that provide information about each value in the table.
Include whatever information is necessary to establish the meaning and context of
the value displayed. When appropriate, include information that describes column
headings or neighboring fields. For example, if a report displays employee names
and salaries, you can add a text object before the Salary database field that reads
“{Last Name}'s salary is “. The user can determine the context and meaning of the
value by reading the accompanying text object.
Crystal Enterprise Administrator’s Guide
473
Improving data table accessibility
Ensure that your text objects use punctuation that will make the content easier to
understand when read aloud by a screen reader. Without accessibility-orientated
punctuation, data tables may be read as one long sentence, making navigation and
interpretation very difficult. For example, you can add periods after values so a
screen reader will pause between columns and rows. For details, see “Using
punctuation” on page 466.
As with all objects in reports, the order in which you place text objects on the report
can affect accessibility. Screen readers read the objects in the order they were
originally added. (For details, see “Placing objects in order” on page 463.) The
correct placement order is critical when you add a text object that identifies the
contents of a particular column in a data table. If you add the text objects at the end
of the design process, they may be read after the columns that they refer to. When
you add text objects that describe values in a report, ensure that you place them on
the report in the order that you want them to be read.
Before you can create an accessible data table, you must plan your report in
advance, determining which objects and database fields you want to include.
Because objects must be placed in the order you want them to be read, planning
your content for accessibility is essential. As part of this planning, it is good
practice to choose how you will use text objects to identify data table values. You
can simply add text objects before each database field. Or you can conditionally
suppress text objects or use formulas to combine text objects and values.
Labelling data tables with text objects
Before each field, add a text object that describes the field's position in the table. In
the following example, the text box provides information about the Employee ID
number. When the report is read with a screen reader, each number is preceded by
the brief explanation in the text box.
474
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
Providing extra information for each value can make a data table appear cluttered
for people without vision impairments, so you may want to hide the extra text
objects by changing the font color to the same color as the background. The extra
text is invisible, but is still detected and read by screen readers.
Labelling data tables conditionally
Although adding text objects is relatively easy to implement, it does not address
all accessibility concerns. Invisible text is read by screen readers, but does not help
people with limited vision. You can allow the user to choose whether or not to
display text descriptions in the data table by conditionally formatting or
suppressing text objects.
Make sure your report includes an accessibility parameter field. For instructions
on how to create the ?Access accessibility parameter field, see “Designing for
flexibility” on page 470.
You can use the parameter field to suppress the text objects conditionally. While it
has the same effect as changing the font color to the background color,
conditionally-suppressed text also allows you to use the parameter field to specify
other formatting options such as font size and style.
To display the text objects only when the user chooses Yes for the ?Access
parameter field, the following report uses a simple conditional formula to enable
the Suppress option on the Common tab of the Format Editor.
{?Access}="No"
The formula must be added for each text object you want to suppress.
Crystal Enterprise Administrator’s Guide
475
Improving data table accessibility
When the user chooses Yes for the ?Access parameter field, the text objects are not
suppressed; the data table displays text descriptions.
Note: The report shown also uses the ?Access parameter field to enable the Can
Grow option (also on the Common tab of the Format Editor) and increase the font
size for people with visual impairments.
When the user chooses No for the ?Access parameter field, the conditional formula
suppresses the text objects, leaving spaces in the report in place of the text objects.
Labelling data tables with formulas
Another method for adding explanatory text to a data table is to create formulas
that combine text, database fields, and conditional formatting. By adding the text
and the database fields together in a conditional formula based on the ?Access
parameter, you can provide optional text for values in a table without leaving
blank spaces in the report. Using formulas also reduces the number of objects on
the report, making it easier to maintain the proper placement order.
Note: Do not use this method if the report has summary fields or calculated fields.
Although formulas provide the best display of data, they can interfere with
calculations because the data is converted to text.
The following report uses formulas placed in the Details section that combine the
database fields and the extra text. When the user chooses Yes for the ?Access parameter
field, each formula builds a string that includes the description and the value.
476
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
This report uses the following formulas:
@Employee ID
If {?Access}="Yes" then "Employee ID "
+ ToText({Employee.Employee ID},0) + ". "
else ToText({Employee.Employee ID},0)
@Last Name
If {?Access}="Yes" then "Employee last name is "
+ {Employee.Last Name} + "."
else {Employee.Last Name}
@Salary
If {?Access}="Yes" then {Employee.Last Name} + "'s Salary is " +
ToText({Employee.Salary}) + "."
else ToText({Employee.Salary})
Notice the added punctuation. The periods at the end of each formula improve
screen reader legibility by creating a pause between fields.
Note:
• The report also uses the ?Access parameter field to enable the Can Grow
option and increase the font size.
• In @Employee ID, ?Access parameter field has been set to “0” to enable the
Can Grow option and increase the font size.
When the user chooses No for the ?Access parameter field, the formula returns only
the data. The report does not display blank spaces in place of the conditional text
objects. Both versions of the report are easy to read.
Crystal Enterprise Administrator’s Guide
477
Accessibility and Crystal Enterprise
Other data table design considerations
In addition to labelling data values with text objects, other report design techniques
can help you create data tables that are easier to understand and navigate.
• Include an introductory paragraph that summarizes the content of the table.
The summary should be brief: one or two sentences if possible.
• Ensure that headings provide enough information to clearly identify the
values that they label.
• To test a table's accessibility, read its headings and values in a linear fashion
from left to right and from top to bottom. For example, if a report displays last
and first name fields for each customer, it may read better if it displays first
name followed by last name. Whenever possible, test the report using assistive
technologies such as screen reading software.
The final accessible report includes a summary of the data table.
To display the table summary conditionally, the report designer divided the Page
Header into two sections. The first page header is suppressed when the ?Access
parameter field is set to No. The second page header is suppressed if the user
chooses Yes. For details, see “Accessibility and suppressing sections” on page 472.
Accessibility and Crystal Enterprise
Designing accessible reports is only part of the solution. You need to make sure
that you deliver reports through an accessible interface that follows the same
design guidelines.
Although the administrative components and scheduling functionality of Crystal
Enterprise are not currently accessible to everyone, the Crystal Enterprise web
desktop and the DHTML viewer allow for accessible access to reports over the Web.
Several enhancements have been made to Crystal Enterprise to account for
accessibility issues. Text descriptions are now provided in ALT tags for the toolbar
buttons and other images. Descriptions for text boxes are clearer, and shortcut links are
provided in the DHTML viewer so you can navigate past the toolbar and group tree.
478
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
Setting accessible preferences for Crystal Enterprise
For the best accessibility support in Crystal Enterprise, you need to set certain
display preferences.
For the Crystal Enterprise web desktop, display objects in the Action view. The
Action view is more accessible because it provides a text list of the available reports
and does not use shortcut menus for report commands. Depending on your users’
needs, you may also want to reduce the number of reports displayed on each page.
For viewing reports, choose the DHTML viewer as the default viewer in your
preferences.
If you administer accounts for other users, you can set their Crystal Enterprise
preferences as well. To change another user’s preferences, use the Preferences
Manager, which is located in the Client Samples area of the Crystal Enterprise User
Launchpad.
Note: You must have your own account on the system in order to set preferences.
To set accessible preferences for Crystal Enterprise
1 Log on to Crystal Enterprise.
2 On the title bar, click Preferences.
3 On the General Preferences page, in the “On my desktop, show me” area,
select Action view.
4 To reduce the number of reports displayed on each page, type a number in the
text box next to the Action view option.
5 Click the Crystal Report Preferences link.
6 In the “View my reports using the” area, select the DHTML viewer.
7 Click Apply.
Accessibility and customization
When you customize Crystal reports or the Crystal Enterprise web desktop, or if
you incorporate Crystal Enterprise into an existing web site, ensure that your
changes follow the accessibility guidelines set forth by the U.S. Access Board in
section 508, or the W3C's Web Accessibility Initiative.
If you customize Crystal reports or the Crystal Enterprise web desktop
extensively, you may encounter other accessibility issues. For online resources that
provide comprehensive accessibility guidelines, see “Resources” on page 481.
Crystal Enterprise Administrator’s Guide
479
Accessibility and customization
The following list provides some common accessibility issues that may cause
problems when you customize Crystal Reports or Crystal Enterprise content.
• Frames
Frames should be clearly labelled, for easier identification and navigation.
Provide text at the top of the frame that describes its purpose. For example, if a
frame provides a list of links to different countries, you can clarify its purpose
by adding text to the frame, such as a title (“Countries”) or short instructions
(“Click a country for details”).
• Style sheets
If you have a visual impairment, you can create a style sheet with specific
viewing preferences to accommodate the disability. For example, you could
create a style sheet that displays all web pages in a large font with white
characters on a black background. Users cannot apply personalized style sheets
to Crystal reports, but the viewers provide a Zoom button that enables people
with visual impairments to increase the magnification to suit their needs. You
can also allow users to choose from different formatting options using
conditional formatting. For details, see “Accessibility and conditional
formatting” on page 471.
• Scripts
If you modify Crystal content to include a script that displays content or an
interactive object, ensure that the script is identified by text that conveys the
purpose of the script. Make sure that pages with scripts are still usable when the
scripts are turned off or unsupported. For more information about scripts and
accessibility, see “Resources” on page 481.
• Image maps
Server-side image maps identify active regions using coordinates, which are
not meaningful to a screen reader. Client-side image maps provide better
accessibility because you can assign a link or URL to each active region within
the image map.
• Electronic forms
Electronic forms can present difficulties for screen readers, and must be set up
carefully. When you label a component in a form, ensure the label is clearly
located next to the form component. For example, for a Search box, ensure that
the “Search” title appears alongside the appropriate text box.
• Applets and plug-ins
If a report needs an applet, plug-in, or other application on the client machine
in order to interpret page content, the plug-in or applet must follow
accessibility guidelines.
If you attach multimedia or other additional resource files to your report, such
as PDF or Real Audio files, provide a link to install the required plug-ins or
software, and ensure that the required software also meets accessibility design
standards.
480
Crystal Enterprise Administrator’s Guide
F: Creating Accessible Reports
• Flickering
Flickering images can trigger seizures for people with seizure disorders. The
W3C recommends to avoid use of images that flicker or flash between four and
59 times per second.
• Search engine placement
Do not use hidden text to enhance your web site’s placement in search engines.
Hidden text reduces readability, because it is read by the screen readers. Also,
hidden text is actively discouraged by popular search engines such as Google,
and thus offers little benefit.
Resources
This chapter focuses on how you can create and distribute accessible reports with
Crystal software. The report design techniques in the chapter were tested using
JAWS 4.5. It is good practice to test all accessible reports using JAWS and other
assistive technologies whenever possible.
To make all of your Web communications accessible, consult the detailed
guidelines available through the W3C or from your government's web site.
• World Wide Web Consortium's Web Accessibility Initiative:
http://www.w3c.org/WAI/
• the United States Access Board's web site for Section 508:
http://www.access-board.gov/sec508/guide/
• the Government of Canada Internet Guide:
http://www.cio-dpi.gc.ca/ig-gi/
Crystal Enterprise Administrator’s Guide
481
Resources
482
Crystal Enterprise Administrator’s Guide
Glossary
Active Server Pages
Active Server Pages are web pages that run under Microsoft’s Internet Information
Server (IIS) version 3.0 and later. Active Server Pages combine HTML, VBScript or
JScript, and ActiveX controls to create dynamic web pages that can be viewed from
most web browsers.
ActiveX Control
A Custom Control for Visual Basic 4.0 and above that incorporates Object Linking
and Embedding (OLE) technology. Formerly known as an OLE Control (OCX).
ActiveX viewer
The ActiveX viewer is a client-side viewer, which is downloaded and installed in
the user’s browser. It is one of the default Crystal Reports Viewers found in the
Crystal Enterprise web desktop. The Active X viewer is downloaded the first time
a user requests a report, and then remains installed on the user’s machine.
AD authentication
AD authentication is a Windows-specific authentication method that enables you to
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 and other Crystal Enterprise applications with their AD user name and
password. This eliminates the need to recreate individual user and group accounts
within Crystal Enterprise.
AD Single Sign On
AD Single Sign On enables users to use various Crystal Enterprise applications
without being prompted to log on. Users need only to enter their AD user name
and password information once at the beginning of the AD session. Note that the
Crystal Enterprise web desktop provides its own form of “anonymous Single Sign
On,” which uses Enterprise authentication, as opposed to Windows NT or
Windows AD authentication.
Crystal Enterprise Administrator’s Guide
483
Advanced DHTML viewer
The Advanced DHTML viewer is a zero-client viewer, which is accessed using a
web browser that supports Dynamic HTML. It is one of the default Crystal Reports
Viewers found in Crystal Enterprise. In addition, the Advanced DHTML viewer
provides an Advanced Search Wizard, which enables you to perform a search on
your report data using Boolean operators. The Advanced DHTML viewer
processes reports against the Report Application Server.
alerts
Alerts are custom messages, created in Crystal Reports, that appear when certain
conditions are met by data in a report. Alert notification highlights critical
information by delivering alerts (when triggered) directly to users' email.
Administrators can specify individuals or distribution lists; they can also configure
notification to provide a link back to the report, along with a set number of records
from the report.
alias
An alias is an alternate name that is assigned to a user to enable him or her to log
on to Crystal Enterprise. For example, a user may have both an Enterprise alias and
an LDAP alias that he or she can access the system with.
auditing
Auditing allows you to monitor and record key facts about your Crystal Enterprise
system. You can use auditing to track the actions of individual users of Crystal
Enterprise as they log in and out of the system, access data, or create file-based
events. You can also monitor system actions like the success or failure of scheduled
objects. The Crystal Management Server acts as the system auditor, collecting
information about audit actions from each of the Crystal Enterprise servers and
recording the information in a central auditing database. Once you have collected
this data, you can use a custom or pre-configured report to view the raw data, or
to answer more complex queries such as “how many concurrent licenses are we
using at a given time?”
Business Views
The Business View Manager is a flexible and reliable multi-tier system that enables
companies to build detailed and specific Business Views that help report designers
and end users access the information they require. Using the Business View
Manager, you can integrate data from disparate sources. You can also bring
together data from multiple data collection platforms and application boundaries
so that the differences in data resolution, coverage, and structure between
collection methods are eliminated.
484
Crystal Enterprise Administrator’s Guide
:
calendars
A calendar is a customized list of run dates for scheduled jobs. When users
schedule objects, they can use a calendar to run the job on a predefined set of dates.
Calendars are particularly useful when you want to run a recurring job on an
irregular schedule, or if you want to provide users with sets of regular scheduling
dates to choose from. Calendars also allow you to create more complex processing
schedules, combining unique scheduling dates with recurring ones.
Cache Server
The Cache Server is responsible for handling all viewing requests from the Web
Component Server (WCS). The Cache Server checks whether or not it can fulfill the
request with a cached report page. If it cannot, it passes the request along to the
Page Server. The Page Server runs the report and returns the results to the Cache
Server. The Cache Server then caches the information and returns the data to the
WCS. By storing report pages in a cache, Crystal Enterprise avoids accessing the
database each and every time a report is requested.
CCM
The Crystal Configuration Manager (CCM) is a server administration tool. It is
provided in two forms. In a Windows environment, the CCM allows you to
manage local and remote servers through its Graphical User Interface (GUI) or
from a command line. In a UNIX environment, the CCM shell script (ccm.sh)
allows you to manage servers from a command line.
CMC
The Crystal Management Console (CMC) web application is the most powerful
administrative tool provided for managing a Crystal Enterprise system. It offers
you a single interface through which you can perform almost every task related to
user management, content management, and server management.
Crystal Analysis
Crystal Analysis is a design tool for creating OLAP applications that allow you to
view and analyze data from different data sources. They can be distributed as
desktop applications, or published on the Web using Crystal Enterprise.
Crystal Configuration Manager
See CCM.
Crystal Enterprise Administrator’s Guide
485
Crystal Import Wizard
The Crystal Import Wizard is a locally installed Windows application that allows
you to migrate existing user accounts, groups, folders, and reports to your new
Crystal Enterprise system. The Crystal Import Wizard runs on Windows, but you
can use it to import information to a new Crystal Enterprise system that is running
on Windows or on UNIX.
Crystal Management Console
See CMC.
Crystal Management Server
The Crystal Management Server (CMS) is responsible for maintaining a database
of information about your Crystal Enterprise system; the other components can
therefore access that data as required. The data stored by the CMS includes
information about users and groups, security levels, Crystal Enterprise content,
and servers. The CMS maintains security and manages objects and servers.
Crystal Publishing Wizard
The Crystal Publishing Wizard is a locally installed, 32-bit Windows application.
The wizard enables administrators and end users to publish Crystal report (.rpt)
files to Crystal Enterprise.
Crystal Server Pages (CSP)
Crystal Server Pages (CSP), which are similar to Active Server Pages (ASP), are
used to provide dynamic responses to users browsing Crystal Enterprise. The
Crystal Enterprise web desktop, for instance, is written in CSP. CSP files contain a
mixture of HTML code and scripting code such as VBScript or JavaScript (also
known as JScript or ECMA Script). CSP pages are text files with a .csp extension,
and they can be developed with a text editor or an application such as Microsoft
FrontPage or Microsoft Visual InterDev. For more information, see the developer
documentation available on your product CD.
Crystal Repository
The Crystal Repository is a database in which you store and manage shared report
elements such as text objects, bitmaps, custom functions, and custom SQL
commands. Crystal Enterprise supports Crystal reports that reference repository
objects. You can refresh a report's repository objects with the latest version from
your Crystal Repository when you publish reports to Crystal Enterprise.
Alternatively, you can refresh a report's repository objects on demand over the Web.
486
Crystal Enterprise Administrator’s Guide
:
custom event
A custom event is an event that is triggered manually by a user through the CMC,
or triggered directly through CSP code. A scheduled report that is dependent on a
custom event will run only when the event is triggered.
data sharing
Data sharing is an administrative option that 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.
data source
A data source is a database, table, query, or stored procedure result set that
provides the data for a report.
database
A database is a bank of related data. Each unit (record) of the database is typically
organized in a fixed format to make it easier to retrieve selected portions of the
data on demand. Each record is made up of one or more data fields, and each data
field can hold one piece of data (known as a value).
Demilitarized Zone (DMZ)
A Demilitarized Zone (DMZ) is a tool that many companies use to improve the
security of their internal networks while providing external users with access to
selected data or services. A DMZ is a network area that is neither part of the
internal network nor directly part of the Internet. Typically, the DMZ is set up
between two firewalls: an outer firewall and an inner firewall. Users from the
external network are allowed access only to data or services hosted on computers
inside the DMZ. Web servers are typically placed in a DMZ.
DHTML viewer
The DHTML viewer is a zero-client viewer, which is accessed using a web browser
that supports Dynamic HTML. It is one of the default Crystal Reports Viewers
found in the Crystal Enterprise web desktop.
Crystal Enterprise Administrator’s Guide
487
Dynamic Link Library (DLL)
A Dynamic Link Library (DLL) is a special kind of file that contains Windows
functions. DLLs are used by developers to extend the capabilities of Windows
applications. The library is activated whenever an application or another DLL calls
a function in the library. DLLs link on the fly, at runtime, whenever an included
function is called. DLL functions are available on an as-needed basis to any
program that can call DLLs; they do not need to be linked to the program via the
compiler. The Crystal Report Engine can be called as a DLL by developers for use
with applications they are developing.
Enterprise authentication
Enterprise authentication is the default authentication method used by Crystal
Enterprise. You can create distinct accounts and groups for use with Crystal
Enterprise. Crystal Enterprise also supports NT authentication and LDAP
authentication.
event
An event is a preset trigger for scheduling and processing objects. Event-based
scheduling provides you with additional control over scheduling reports: you can
set up events so that reports are processed only after a specified event occurs.
Working with events consists of two steps: creating an event and scheduling a
report with events. That is, once you create an event, you can select it as a
dependency when you schedule a report. The scheduled job is then processed only
when the event occurs. You can schedule a report with a file event, a custom event,
and/or a schedule event.
Event Server
The Event Server manages file-based events. When you set up a file-based event
within Crystal Enterprise, the Event Server monitors the directory that you
specified. When the appropriate file appears in the monitored directory, the Event
Server triggers your file-based event: that is, the Event Server notifies the CMS that
the file-based event has occurred. The CMS then starts any jobs that are dependent
upon your file-based event.
file event
A file-based event waits for a particular file (the trigger) to appear before the event
occurs. Before scheduling a report that waits for a file-based event to occur, you
must first create the file-based event in the Events management area of the CMC.
When you define a file-based event, you specify a filename that the Event Server
should monitor for a particular file. When the file appears, the Event Server
triggers the event.
488
Crystal Enterprise Administrator’s Guide
:
File Repository Server
There is typically one Input and one Output File Repository Server in every Crystal
Enterprise implementation. (In larger deployments, there may be multiple Input
and Output File Repository Servers, for redundancy.) The Input File Repository
Server manages all of the report objects that have been published to the system by
administrators or end users (using the Crystal Publishing Wizard, the Crystal
Management Console (CMC), the Crystal Import Wizard, or a Crystal designer
component such as Crystal Reports). The Output File Repository Server manages
all of the report instances generated by the LDAP authentication(s). The File
Repository Servers are responsible for listing files on the server, querying for the
size of a file, querying for the size of the entire file repository, adding files to the
repository, and removing files from the repository.
group
A group is a collection of users who share the same account privileges. For instance,
you can create groups that are based on department, role, or location. Groups
enable you to make changes in one place (a group) instead of modifying each user
account individually. Also, you can assign object rights to a group or groups.
hyperlinks
Crystal Reports lets you use hyperlinks to navigate from one report object to
another. You can move to a Report Part within the report itself, to other report
objects or their parts, or to specific instances of reports or Report Parts. To view
hyperlinked reports, you must publish both the home and destination reports to
the same Crystal Enterprise system. (A home report is one that contains a
hyperlink to another report: the destination report.) This navigation is available
only in the new script-based DHTML viewers (zero-client, server-side viewers)
included in Crystal Enterprise 10.
instance
An instance is a copy or “version” of an object that contains report data that is
retrieved from one or more databases. Each instance contains data that is current
at the time the report, query, or program is processed. In Crystal Enterprise, you
publish objects to the system, and then schedule those objects to generate instances
on a recurring basis.
Input File Repository Server
See File Repository Server.
Crystal Enterprise Administrator’s Guide
489
Java viewer
The Java viewer is a client-side viewer, which is downloaded and installed in the
user’s browser. It is one of the default Crystal Reports Viewers found in the Crystal
Enterprise web desktop. The Java viewer is downloaded and installed once every
user session.
LDAP authentication
Lightweight Directory Access Protocol (LDAP) authentication enables you to use
existing LDAP user accounts and groups (on an LDAP directory server) in Crystal
Enterprise. When you map LDAP accounts to Crystal Enterprise, users are able to
access the Crystal Enterprise web desktop and other Crystal Enterprise
applications with their LDAP user name and password. This eliminates the need
to recreate individual user and group accounts within Crystal Enterprise.
logon token
A logon token is an encoded string that defines its own usage attributes and
contains a user’s session information. The logon token’s usage attributes are
specified when the logon token is generated. These attributes allow restrictions to
be placed upon the logon token to reduce the chance of the logon token being used
by malicious users.
mapping accounts
Mapping an account enables a user with an NT or LDAP account to access Crystal
Enterprise. Typically, you map NT or LDAP user accounts to Crystal Enterprise
through the CMC. When you map an NT or LDAP account, you can choose to create
a new Crystal Enterprise account or link to an existing Crystal Enterprise account.
mobile desktop
The mobile desktop is an included sample which enables users of mobile devices
(such as a WAP-enabled phone, web-enabled PDA, and so on) to access reports, as
long as the web server is configured to support mobile devices.
.NET Server Controls
The .NET Server Controls allow you to rapidly incorporate content and
functionality from Crystal Enterprise into Microsoft Visual Studio.NET
applications. Crystal Enterprise 10 provides visual and non-visual controls that
contain the logic for common operations, such as authentication, folder listing, and
report viewing. You can manipulate these controls in the Visual Studio.NET
environment and insert them seamlessly into applications.
490
Crystal Enterprise Administrator’s Guide
:
notification
You can set scheduling options that automatically send notification when an object
instance succeeds or fails. For example, you may have a large number of reports
that run a new instance every day. You need to check each instance to make sure
it ran properly, and then send out emails to the users who need to know that the
new report is available. With thousands of reports, it would take too much time to
manually check the reports and contact the users who need the information. Using
notification settings in Crystal Enterprise, you can set each object to automatically
notify you when the report fails to run properly, and you can automatically inform
users when new report instances run successfully.
NT authentication
NT authentication is a Windows-specific authentication method that enables you to
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 and other Crystal Enterprise applications with their NT user name and
password. This eliminates the need to recreate individual user and group accounts
within Crystal Enterprise.
NT Single Sign On
NT Single Sign On enables users to use various Crystal Enterprise applications
without being prompted to log on. Users need only to enter their NT user name
and password information once at the beginning of the NT session. Note that the
Crystal Enterprise web desktop provides its own form of “anonymous Single Sign
On,” which uses Enterprise authentication, as opposed to Windows NT or
Windows AD authentication.
object
From an administrative perspective, objects in Crystal Enterprise are the folders
you create on the system and the content you publish to the system. There are
several types of objects that can exist in 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.
object packages
Object packages simplify administration by allowing you to schedule, secure and
manage a set of related reports and programs as a single object. This ensures that
each instance of a package provides a consistent and synchronized snapshot of a
set of related data.
Crystal Enterprise Administrator’s Guide
491
ODBC
ODBC stands for Open Database Connectivity. It is an interface that gives applications
the ability to use SQL to retrieve data from data management systems. Such an
interface allows a developer to develop, compile, and ship applications without
targeting specific database management systems. Also called interoperability.
Output File Repository Server
See File Repository Server.
Page Server
The Page Server’s primary responsibility is to respond to on-demand page
requests from the Cache Server and to generate Encapsulated Page Format (EPF)
pages. The Page Server then returns the EPF pages to the Cache Server. The EPF
pages contain formatting information that defines the layout of the report. The
data for the report is saved with the report or retrieved on demand from the
database.
parameter field
A parameter field is a special kind of field that prompts the user for a value. You
can use parameter fields for report titles, record selection, sorting, and a variety of
other uses. Using parameter fields enables you to create a single report that you
can modify quickly to fit a variety of needs.
processing extension
A processing extension is a dynamically loaded library of code that applies
business logic to particular Crystal Enterprise view requests or schedule requests
before they are processed by the system.
Program Job Server
A Program Job Server processes scheduled program objects, as requested by the
CMS. To run a program, the Program Job Server first retrieves the files from storage
on the Input File Repository Server, and then runs the program. By definition,
program objects are custom applications. Therefore the outcome of running a
program will be dependent upon the particular program object that is run.
program objects
Program objects are executables, scripts, or Java programs that you can schedule
to run regularly or based on an event. Program object features allow you to
automate a wide range of administrative tasks, making Crystal Enterprise a selfmanaging environment. Additionally, you can use program objects to trigger
external processes, thus integrating Crystal Enterprise into a broader work flow.
492
Crystal Enterprise Administrator’s Guide
:
publishing
Publishing is the process of adding objects such as Crystal reports to the Crystal
Enterprise environment and making them available to authorized users. The
objects that you publish may be individual reports created with Crystal Reports,
analytical applications designed with Crystal Analysis, or other objects that you’ve
created using Crystal Enterprise plug-in components.
record
In a database, a record is a complete unit of related information, an electronic file
folder that holds all of the data on a given entity. Each record contains one or more
fields that contain the specific pieces of data of interest. In a customer database, for
example, a record would store all of the data on a single customer. In an inventory
database, a record would store all of the data on a single inventory item. Data from
an individual record is displayed or printed as a row of data on a columnar report.
report
A report is an organized presentation of data. As a management tool, a report is
used to provide management with the insight it needs to run an organization
effectively. In Crystal Enterprise, you publish objects to the system, and then
schedule those objects to generate instances on a recurring basis.
Report Application Server
The Report Application Server (RAS) is a Crystal Enterprise server component that
provides users with report design capability over the Web. It processes reports that
Crystal Enterprise users view with the Advanced DHTML viewer, and it provides
the ad hoc reporting capabilities that allow Crystal Enterprise users to create and
modify reports over the Web.
Report Job Server
The Report Job Server processes scheduled reports, as requested by the Crystal
Management Server, and generates report instances (instances are versions of a
report object that contain saved data). To generate a report instance, the Job Server
communicates with the database to retrieve the current data.
report object
A report object is an object that is created using a Crystal designer component
(such as Crystal Reports or Crystal Analysis). Report objects contain report
information (such as database fields). When you schedule a report, Crystal
Enterprise generates an instance or instances of the object. When you publish a
report object to Crystal Enterprise, only the structure of the report (the template
information) is saved; that is, the published report object contains no saved data.
Crystal Enterprise Administrator’s Guide
493
Report Parts
Report objects displayed by themselves in a viewer—without the rest of the report
page—are referred to as Report Parts. More precisely, however, Report Parts are
hyperlink definitions that point from a home report object to a destination object.
schedule event
Schedule-based events are dependent upon scheduled reports. That is, a schedulebased event is triggered when a particular report has been processed. When you
create this type of event, it can be based on the success or failure of a scheduled
report, or it can be based simply on the completion of the job. A report that is
dependent on a schedule-based event will run only when the schedule-based
event is triggered.
selection formula
A selection formula is a formula that specifies the records, or groups of records,
you want included in your report.
server-side processing
Server-side processing is a feature that allows you to set up reports that perform
the majority of their processing on the database server. These reports push only
relevant details to your computer, thus saving you time and memory.
Sign Up feature
The Sign Up feature in Crystal Enterprise enables users to sign up and create a new
account on Crystal Enterprise. You have the option to disable this feature to
prevent guest users from creating their own accounts.
Single Sign On
Single Sign On enables users to automatically log on to an application without
entering a user name or password. In Crystal Enterprise, there are two forms of
Single Sign On: NT Single Sign On, and Crystal Enterprise’s Single Sign On
feature. With Crystal Enterprise’s Single Sign On feature, users are logged on
automatically under the Guest account (Enterprise authentication).
Software Development Kit
The Crystal Enterprise Software Development Kit (SDK) enables you to develop
your own custom desktops or administrative tools. There are COM, .NET, and
Java SDKs for Crystal Enterprise. For more information, see the developer
documentation available on your product CD.
494
Crystal Enterprise Administrator’s Guide
:
subreport
A subreport is a report within a report. It has all of the characteristics of a report
with one exception: it cannot itself include a subreport. Subreports can be freestanding or they can be linked to the data in the primary report. Using Crystal
Reports, you can insert as many subreports as you wish.
Web Component Adapter
The Web Component Adapter (WCA) has two primary roles: it processes Crystal
Server Pages (.csp files), and it also supports Crystal applications that formerly
relied upon the WCS. These applications include the Crystal Management Console
(CMC) and Crystal report viewers (that are implemented through viewrpt.cwr
requests). The WCA is only used in UNIX installations of Crystal Enterprise, or in
Windows installations that use the Java SDK. In these systems there is no Web
Component Server and no Web Connector. Instead the WCA runs within a Java
web application server and provides all WCS services that are not directly
supported by the Java SDK.
Web Component Server
The Web Component Server (WCS) is the gateway between the Web Connector on
the web server and the rest of the components in Crystal Enterprise. The WCS is
responsible for processing requests from your browser, including Crystal Server
Pages (.csp files), which are used to customize your access to Crystal Enterprise.
As a result, this server also acts as an application server.
Web Connector
To communicate with the different types of web servers, the WCS uses a Web
Connector. Crystal Enterprise includes different Web Connectors for different
operating systems and web servers.
web desktop
The Crystal Enterprise web desktop is a web-based interface that end users access
to view, schedule, and keep track of published reports. Each Crystal Enterprise
request that a user makes in the web desktop is directed by the web server to the
Web Connector, which then forwards the request to the Web Component Server.
Crystal Enterprise Administrator’s Guide
495
496
Crystal Enterprise Administrator’s Guide
Index
A
Access Level column .............................................. 143
access levels ........................................................... 142
administration .................................................. 174
Advanced................................................. 145, 146
available in the CMC ....................................... 415
calendars ......................................................... 220
CMC ................................................................ 173
Crystal Enterprise web desktop......................... 173
enabling and disabling inheritance................... 150
events .............................................................. 267
folders.............................................................. 111
for RAS............................................................. 417
Full Control...................................................... 145
groups.............................................................. 175
inheritance....................................................... 149
No Access........................................................ 144
NTFS................................................................ 420
reference.......................................................... 413
restricting from the top-level folder .................. 171
Schedule .......................................................... 145
server groups.................................................... 176
servers.............................................................. 176
setting .............................................................. 144
specifying on folders ........................................ 111
tutorials............................................................ 154
types of ............................................................ 144
users ................................................................ 175
View ................................................................ 145
View On Demand............................................ 145
when copying/moving folders .......................... 108
accessibility ............................................................ 460
and Crystal Enterprise....................................... 478
and Crystal Reports .......................................... 460
benefits of ........................................................ 460
design considerations....................................... 462
guidelines ........................................................ 461
resources.......................................................... 481
account management ............................................... 64
Active Directory ....................................................... 95
active sessions, viewing .......................................... 273
active trust relationship............................................. 57
ActiveX viewer
modifying options ............................................ 280
activity, viewing current metrics ............................. 271
AD accounts
adding groups .................................................. 101
Crystal Enterprise Administrator’s Guide
aliases
reassigning .................................................. 100
using ............................................................. 99
viewing ....................................................... 101
configuring ........................................................ 95
mapping ............................................................ 95
Single Sign On ................................................. 102
troubleshooting................................................ 101
unmapping ........................................................ 98
users
creating....................................................... 101
disabling ..................................................... 101
AD authentication plug-in ........................................ 55
AD groups
mapping ............................................................ 95
unmapping ........................................................ 98
AD Single Sign On ................................................. 102
AD users
mapping ............................................................ 95
unmapping ........................................................ 98
adding
CMS cluster members ...................................... 284
servers ............................................................. 365
administration .......................................................... 18
configuration tools ........................................... 270
delegating ................................................ 167, 174
events .............................................................. 267
folders.............................................................. 111
over the Web ..................................................... 18
remote UNIX machines...................................... 23
remote Windows machines................................ 22
rights................................................................ 174
servers and server groups ................................. 176
tools................................................................... 18
users and groups .............................................. 175
Administrator, setting password................................ 24
Administrators group, default rights ........................ 417
Advanced access level ........................................... 145
advanced rights ...................................................... 146
and inheritance................................................ 149
priorities affecting ....................................... 154
denied by default ............................................. 154
enabling and disabling inheritance .................. 151
precedence ...................................................... 154
reference.......................................................... 414
setting .............................................................. 146
viewing............................................................ 146
497
Advanced Rights page.............................................146
reference ..........................................................414
affinity, and SSL ........................................................58
alerts, setting notification ........................................192
aliases
AD accounts.......................................................99
LDAP accounts...................................................92
NT accounts .......................................................80
application servers ....................................................32
application tier..........................................................31
applications ..............................................................29
CCM...................................................................30
CMC...................................................................30
Crystal Enterprise web desktop ...........................29
Crystal Import Wizard ........................................31
Crystal Publishing Wizard ..................................30
APS. See CMS
apsdbsetup.sh .........................................................438
architecture...............................................................28
application tier ...................................................31
client tier ............................................................29
data tier ..............................................................39
diagram ..............................................................28
intelligence tier...................................................34
processing tier ....................................................37
areas, management ...................................................19
assistive technology ................................................460
attributes, logon tokens .............................................57
audience, intended .....................................................2
audit actions
enabling auditing of..........................................335
reference list.....................................................331
synchronizing records ......................................337
auditee....................................................................330
AuditID ...................................................................343
auditing ..................................................................330
configuring database ........................................334
database schema ..............................................341
enabling ...........................................................335
information flow...............................................330
notification .......................................................250
optimizing performance ...................................338
reporting results................................................339
synchronizing records ......................................337
user and system actions ....................................331
web activity................................................61, 279
auditing database
AuditID reference .............................................343
configuring .......................................................334
database schema ..............................................341
auditor ....................................................................330
AuditString ..............................................................343
authentication .....................................................46, 66
Crystal Enterprise security plug-in.......................51
Enterprise ...........................................................66
LDAP..................................................................66
498
LDAP security plug-in ........................................ 53
object packages ............................................... 210
primary .............................................................. 47
process described............................................... 47
program objects ............................................... 206
secondary .......................................................... 48
security plug-ins ................................................. 50
troubleshooting log on ..................................... 397
Windows AD security plug-in ............................ 55
Windows NT...................................................... 66
Windows NT Challenge/Response ............... 53, 55
Windows NT security plug-in............................. 52
authentication providers ........................................... 50
authorization ............................................................ 46
effective rights .................................................. 152
process described............................................... 48
authorization. See also object rights
Automated Process Scheduler. See CMS
available rights ....................................................... 149
B
base rights .............................................................. 149
batch programs....................................................... 121
binary programs...................................................... 121
Btrieve .................................................................... 315
business calendars. See calendars
button conventions ..................................................... 8
C
cache files settings .................................................. 301
Cache Server ............................................................ 36
auditable actions .............................................. 332
AuditString reference........................................ 345
command-line options ..................................... 429
configuring....................................................... 301
NTFS ........................................................... 422
metrics ............................................................. 272
performance settings ........................................ 301
viewing with ...................................................... 41
calendars ................................................................ 214
access to .......................................................... 220
add run dates to ............................................... 215
creating ............................................................ 215
deleting ............................................................ 219
scheduling objects with.................................... 231
CCM......................................................................... 30
accessing ........................................................... 22
adding a server................................................. 365
changing
server startup type ....................................... 326
server user account ..................................... 326
Windows server dependencies .................... 325
copying server status ........................................ 278
deleting a server ............................................... 366
enabling and disabling servers ......................... 276
Crystal Enterprise Administrator’s Guide
for UNIX .................................................... 23, 436
for Windows ...................................................... 22
printing server status ........................................ 278
refreshing the list of servers .............................. 279
starting, stopping, and restarting servers ........... 274
working with ..................................................... 22
ccm.sh ................................................................... 436
Help option ....................................................... 23
running .............................................................. 23
characters, setting CMC preferences......................... 20
client side viewers.................................................... 39
client tier.................................................................. 29
clustering, requirements ......................................... 284
clusters........................................................... 284, 286
changing names............................................... 288
viewing details................................................. 273
CMC ........................................................................ 30
access to .......................................................... 173
communication error ....................................... 396
enabling and disabling servers ......................... 276
Glossary definition........................................... 485
logging off ......................................................... 22
logging on ......................................................... 19
logging options ................................................ 279
management areas ............................................. 19
navigating .......................................................... 19
publishing objects with .................................... 125
setting preferences ............................................. 20
setting Query size threshold............................... 21
starting, stopping, and restarting servers ........... 274
unable to connect ............................................ 397
working with ..................................................... 18
CMS ................................................................... 34, 50
adding to a cluster ........................................... 286
and authentication ....................................... 47, 48
and authorization .............................................. 48
and distributed security...................................... 58
and security ....................................................... 50
and security plug-ins.......................................... 50
as nameserver .................................................. 321
auditable actions ............................................. 332
AuditString reference ....................................... 343
base rights and available rights ........................ 149
calculating effective rights ............................... 152
changing cluster name ..................................... 288
clustering ......................................................... 284
command-line options ..................................... 428
configuring .............................................. 298, 321
NAT............................................................ 377
NTFS........................................................... 422
packet filtering ............................................ 385
SOCKS........................................................ 391
copying system database ................................. 289
default port ...................................................... 321
directory listing service .................................... 371
installing a new cluster member ...................... 286
Crystal Enterprise Administrator’s Guide
metrics .............................................................273
requirements for clustering ...............................284
unable to connect.............................................397
when enabling and disabling other servers .......276
CMS database ...........................................................34
changing password...........................................298
configuring .......................................................289
deleting ............................................................298
migrating ..........................................................289
recreating .........................................................298
selecting ...........................................................298
CMS session variables...............................................59
and authentication........................................47, 48
tracking ..............................................................60
color
and accessibility ...............................................467
contrast ............................................................467
COM SDK.................................................................31
command conventions................................................8
command line arguments, program objects.....124, 202
command lines .......................................................426
command-line options
all servers .........................................................426
Cache Server ....................................................429
CMS .................................................................428
Event Server......................................................434
Input and Output File Repository Servers..........433
Page Server.......................................................429
Program Job Server ...........................................431
Report Application Server.................................432
Report Job Server..............................................431
WCS.................................................................429
commands, UNIX reference ....................................435
communication between browser and WCS .............47
communication error ..............................................396
components ..............................................................28
Cache Server ......................................................36
CCM...................................................................30
client tier ............................................................29
CMC...................................................................30
CMS ...................................................................34
communication ..................................................40
configuring servers ...........................................270
Crystal Enterprise web desktop ...........................29
Crystal Import Wizard ........................................31
Crystal Publishing Wizard ..................................30
Event Server........................................................36
File Repository Servers........................................35
information flow.................................................40
intelligence tier...................................................34
Page Server.........................................................38
processing tier ....................................................37
Program Job Server .............................................37
Report Application Server...................................38
Report Job Server................................................37
security management..........................................49
499
servers ....................................................28, 34, 37
WCS...................................................................31
Web Component Adapter...................................33
conditional formatting
for accessibility.................................................471
for multiple languages ......................................454
configuration, common scenarios ...........................356
configuring
auditing database .............................................334
Cache Server ....................................................301
CMS clusters.............................................284, 288
CMS database...........................................289, 298
Event Server......................................................303
executable programs ........................................203
File Repository Servers......................................300
firewalls............................................................374
intelligence tier.................................................284
Job Server .........................................308, 309, 313
NTFS permissions .............................................420
object packages................................................210
Page Server...............................................304, 313
processing tier ..................................................304
server settings ...................................................270
servers ..............................................................270
WCS.........................................................279, 280
connecting to remote Windows machines ................22
content, folders .......................................................106
contrast, color .........................................................467
cookies
and session tracking ...........................................59
logon tokens.......................................................57
copying system data................................................289
copying/moving folders...........................................108
creating
custom audit reports .........................................341
folder administrators.........................................167
folders ..............................................................106
server groups ....................................................350
server subgroups...............................................352
subfolders.........................................................107
credentials, program ...............................................122
Crystal Analysis, saving objects to CMS ..................127
Crystal Configuration Manager. See CCM
Crystal Enterprise
disabling Guest account .....................................25
disabling Sign Up ...............................................24
international deployments ................................446
primary authentication process...........................47
Sign Up ..............................................................52
Single Sign On....................................................52
Crystal Enterprise Embedded ...................................408
Crystal Enterprise Embedded. See also RAS
Crystal Enterprise Java SDK .......................................33
Crystal Enterprise SDK ..................................46, 48, 56
Crystal Enterprise security plug-in .............................51
Crystal Enterprise Sizing Guide ...............................356
500
Crystal Enterprise web desktop ................................. 29
access to .......................................................... 173
authentication .............................................. 46, 66
authentication model ......................................... 46
considerations .................................................. 405
folders .............................................................. 113
in multiple languages ....................................... 453
Java version.......................................... 26, 32, 282
managing ........................................................... 26
scheduling ....................................................... 220
setting users preferences................................... 405
Single Sign On ................................................... 53
troubleshooting ................................................ 405
users and groups ................................................ 64
Crystal Import Wizard....................................... 31, 130
selecting information........................................ 137
specifying source and destination..................... 136
Crystal Launchpad, accessing ................................... 19
Crystal Management Console. See CMC
Crystal Management Server. See CMS
Crystal Publishing Wizard....................................... 117
adding
folders ......................................................... 118
objects ........................................................ 118
changing
default values .............................................. 122
object properties ......................................... 122
creating folder on CMS .................................... 119
database log on ................................................ 123
duplicating folder structure .............................. 118
moving reports between folders ....................... 120
repository refresh ............................................. 121
scheduling objects ........................................... 120
selecting
folder on CMS ............................................. 119
setting parameters ............................................ 124
Crystal Reports
and accessibility............................................... 460
saving objects to CMS ...................................... 127
troubleshooting reports .................................... 398
Crystal Repository................................................... 254
refreshing objects in reports ............................. 258
Crystal Repository Migration Wizard .............. 255, 257
cultural conventions ............................................... 456
custom events................................................. 262, 266
custom web applications, enhancing ...................... 361
customizing
inheritance model ............................................ 154
object rights ..................................................... 146
your configuration............................................ 356
D
daemons, signal handling ....................................... 427
data
allowing users to refresh................................... 117
cache files ........................................................ 301
Crystal Enterprise Administrator’s Guide
choosing live/saved ........................................... 43
formatting for accessibility ............................... 473
live .................................................................... 43
refreshing on a schedule .................................. 117
saved ................................................................. 44
data access, security and management ..................... 12
data sharing............................................................ 270
on Cache Server .............................................. 301
on Page Server ................................................. 304
on RAS ............................................................ 306
data sources
on UNIX .......................................................... 315
on Windows .................................................... 313
data tier.................................................................... 39
databases
changing settings ............................................. 194
configuring servers for ..................................... 313
copying CMS data ........................................... 289
initializing the CMS ......................................... 298
modifying RAS interactions .............................. 306
selecting for the CMS ....................................... 298
troubleshooting
driver errors ................................................ 402
logon .......................................................... 400
DB2 ....................................................................... 314
default settings
authentication.................................................... 51
Enterprise accounts ............................................ 51
groups ............................................................... 64
Administrators............................................... 65
Crystal NT Users ........................................... 66
Everyone....................................................... 65
New Sign-Up Accounts................................. 66
modifying security ............................................. 25
NT account........................................................ 52
object rights..................................................... 413
ports ................................................................ 321
security plug-in .................................................. 51
users .................................................................. 64
Administrator ................................................ 65
Guest ............................................................ 65
delegated administration. See administration
deleting
CMS database .................................................. 298
folders ............................................................. 108
report objects................................................... 180
servers ............................................................. 366
denied rights .......................................................... 154
dependencies of servers on Windows..................... 325
designer, saving objects to CMS ............................. 127
designing reports
and accessibility .............................................. 462
and cultural conventions ................................. 456
in multiple languages............................... 446, 453
destination environment, and importing ................. 136
Crystal Enterprise Administrator’s Guide
destinations.............................................................237
default settings..................................................237
disk, setting default...........................................309
email ................................................................241
FTP...................................................................239
Job Servers, setting default ................................309
printer ..............................................................245
troubleshooting ................................................405
unmanaged disk ...............................................238
DHTML viewer
modifying options.............................................280
directories, publishing.............................................117
directory servers
about LDAP........................................................54
security plug-in...................................................53
disabilities. See accessibility
disabling
Guest account ....................................................25
inheritance .......................................................150
servers ..............................................................276
Sign Up ..............................................................24
DLL. See dynamic-link libraries
documentation, additional ......................................395
drivers, troubleshooting errors.................................402
DSNs on UNIX .......................................................317
dynamic-link libraries
as processing extensions.....................................56
E
effective rights, calculating......................................152
email destination ....................................................241
setting defaults..................................................312
email notification....................................................250
enabling
auditing ............................................................335
inheritance .......................................................150
servers ..............................................................276
encoding logon tokens..............................................57
environment variables
ODBC ..............................................................317
specifying for program objects..........................204
env.sh .....................................................................443
ePortfolio. See Crystal Enterprise web desktop
errors
Page Server.......................................................404
troubleshooting ................................................394
Event Log ........................................................320, 325
Event Server ..............................................................36
auditable actions ..............................................333
AuditString reference ........................................346
command-line options......................................434
configuring .......................................................303
metrics .............................................................272
polling time ......................................................303
501
events .....................................................................262
access to...........................................................267
custom .............................................................266
file-based..........................................................263
importing from Crystal Enterprise......................133
notification .......................................................250
polling time ......................................................303
schedule-based.................................................264
scheduling........................................................234
Everyone group, default rights .................................417
executable programs ...............................................201
configuring .......................................................203
expanding the system..............................................356
Explicitly Denied column........................................146
Explicitly Granted column ......................................146
extensions, processing ..............................................56
F
fail over, Web Connector and WCS ..........................58
failure, notification..................................................249
Favorites folders ......................................................113
fax numbers, registration .............................................6
features, new ..............................................................9
file events .......................................................262, 263
File Repository Servers ..............................................35
command-line options......................................433
configuring NTFS permissions ..........................421
metrics .............................................................272
setting maximum idle times ..............................300
setting root directories ......................................300
firewall rules
NAT .........................................376, 377, 381, 382
packet filtering..................................384, 386, 387
firewalls ............................................................61, 368
configuring ...............................................374, 420
for Crystal Enterprise....................................373
NAT.............................................................375
packet filtering.............................................383
SOCKS.........................................................387
forcing servers to register by name....................324
scenarios ..........................................................373
with application tier.....................374, 377, 385
with thick client...........................374, 382, 387
with WCA....................................................392
with WCS ............................373, 375, 383, 388
with Web Connector ...........373, 375, 383, 389
server communications, and.............................371
types of.............................................................369
NAT.............................................................370
packet filtering.............................................369
SOCKS.........................................................370
folder administrators, creating .................................167
folders.....................................................................106
access to...........................................................111
adding a report .................................................109
502
changing top-level rights .................................. 159
copying/moving ............................................... 108
creating ............................................................ 106
default rights at top level .................................. 417
default user folders ........................................... 113
delegated administration .................................. 167
deleting ............................................................ 108
Favorites folder ................................................ 113
importing
from Crystal Enterprise ................................ 132
from Info ..................................................... 134
inheritance ....................................................... 150
moving............................................................. 108
object rights ..................................................... 142
access levels................................................ 144
advanced settings ........................................ 146
inheritance .................................................. 150
setting access levels..................................... 144
viewing ....................................................... 143
when copying/moving................................. 108
rights ................................................................ 111
setting instance limits ....................................... 112
specifying rights ............................................... 111
fonts, conditional.................................................... 454
format, choosing..................................................... 243
formatting, and accessibility ................................... 466
FTP destination ....................................................... 239
setting defaults ................................................. 310
Full Control access level ......................................... 145
reference .......................................................... 416
G
global deployments, Crystal Enterprise.................... 446
granted rights.......................................................... 154
group inheritance ................................................... 150
group rights ............................................................ 142
grouping servers ..................................................... 350
groups
access to .......................................................... 175
creating .............................................................. 71
for tutorials.................................................. 155
deleting .............................................................. 73
importing
from Crystal Enterprise ................................ 131
from Info ..................................................... 134
modifying........................................................... 72
object rights
access levels................................................ 144
advanced rights ........................................... 146
inheritance .................................................. 150
of servers.......................................................... 350
setting
instance limits on folders............................. 112
object rights ................................................ 182
viewing members ............................................... 73
Crystal Enterprise Administrator’s Guide
Guest account
default rights .................................................... 417
disabling ...................................................... 25, 74
disabling Sign Up .............................................. 24
H
help
documentation resources ................................. 395
online .................................................................. 6
product registration.............................................. 6
technical support ................................................. 7
highlighting exceptions and accessibility................ 468
Holos applications, from Info ................................. 135
HTTP.................................................................. 47, 59
hyperlinks between reports..................................... 199
I
idle times
Cache Server ................................................... 301
File Repository Servers ..................................... 300
Page Server ...................................................... 304
importing
Crystal Import Wizard...................................... 130
from Crystal Enterprise ..................................... 130
from Info.......................................................... 133
selecting information ....................................... 137
specifying source and destination .................... 136
index, setting CMC preferences ................................ 20
Info cubes .............................................................. 135
Info Views .............................................................. 135
Info, importing information .................................... 133
information flow, between servers............................ 40
Informix ................................................................. 314
inheritance ............................................................. 149
and advanced rights................................. 146, 151
base rights and available rights ........................ 149
enabling and disabling..................................... 150
priorities affecting ............................................ 154
tutorials ........................................................... 154
Inherited column.................................................... 146
initializing CMS database ....................................... 298
initlaunch.sh .......................................................... 444
Input File Repository Server...................................... 35
command-line options ..................................... 433
configuring NTFS permissions.......................... 421
metrics............................................................. 272
setting maximum idle time............................... 300
setting root directory ........................................ 300
instances
from Info.......................................................... 134
importing from Crystal Enterprise ..................... 132
managing......................................................... 236
notification ...................................................... 250
object packages ............................................... 208
program objects ............................................... 201
Crystal Enterprise Administrator’s Guide
report objects ...................................................184
setting limits at the folder level .........................112
intelligence tier .........................................................34
configuring .......................................................284
international deployments, planning .......................446
Internet Information Services (IIS)
and NT Single Sign On .................................53, 55
default web site ................................................396
J
Java platform.............................................................32
Java programs .........................................121, 201, 206
authentication ..................................................207
configuring .......................................................205
setting parameters.............................................205
Java SDK...................................................................32
Java viewer, modifying options ...............................280
Job Server
configuring ...............................................309, 313
NTFS permissions ........................................423
on UNIX ......................................................315
maximum number of jobs.................................308
metrics .............................................................273
report objects ...........................................187, 212
Job Servers ................................................................37
JScript .....................................................................121
K
key combinations........................................................8
keyboard shortcuts......................................................8
L
languages, multiple.................................................449
launchpad, accessing................................................19
LDAP ........................................................................54
about..................................................................54
and SSL ..............................................................54
authentication ....................................................66
managing accounts.............................................84
LDA