Chapter 17 Introduction to the BusinessObjects XI Repository
Exploring the BusinessObjects Repository 386
Migration of the BusinessObjects Repository 387
Sharing Components in the Repository 390
Introduction
The BusinessObjects Repository is a database that stores all of the Enterprise components, such as users, groups, folders, security settings, events, business views, universes, and user and system settings.
It also includes commonly used components that report developers can share between Crystal Reports.
This database is created and populated at install time and is controlled by the Central Management Server (CMS). For this reason, you need to ensure that the database connection or database client software is installed on the server the CMS resides on. However, the physical database itself does not have to reside on the same server as the CMS, and for performance reasons it is recommended that the two are separated.
This repository was separated in the Crystal Decisions version 9 product suite into a repository for Crystal Reports 9 and an Enterprise object repository attached to the Automated Process Scheduler or APS. In Crystal Enterprise version 10, these two repositories were merged and are simply known as the Crystal Repository, which is attached to the CMS.
Administrators often have the misconception that the repository stores the report documents and report instances. These are actually stored on the file system as part of the File Repository Services. Consequently, when backing up the system or creating a fault-tolerant system, these folder structures need to be replicated. Furthermore, the Auditing database is not the same database as the Repository, but rather a separate database requiring a separate install. These concepts are described further in Chapter 25, “BusinessObjects Enterprise Architecture.”
For a listing of supported databases, see the CMS database listing found on the platforms.txt on your Enterprise CD.
Exploring the BusinessObjects Repository
Objects stored in the repository are exposed through a SQL-like language that allows the administrator to query the repository. For example, he might wish to know all the objects in the repository that were created by a certain user or after a certain date. Objects in the repository are assigned certain properties when they are saved to the system, logically grouped into components known as property bags. It is these properties that are exposed via the SQL expressions.
The Query Builder, as shown in Figure 17.1, is a Web-based application that allows an administrator to query the repository. A link to Query Builder can be found on the Administator Launchpad page at http://<Server>:<port>/businessobjects/enterprise11/adminlaunch/launchpad.html.
Figure 17.1 The Query Builder displaying all of the object’s properties.
To get a listing of all exposed properties, an administrator could write a SQL statement such as SELECT * FROM CI_INFOOBJECTS. All objects and all properties would be selected. After the administrator has an understanding of the properties, specific queries can be written, such as SELECT * FROM CI_INFOOBJECTS WHERE SI_KIND = 'CrystalReport' to display a listing of all Crystal Reports published to BusinessObjects XI.
Migration of the BusinessObjects Repository
Numerous circumstances exist where an administrator might want to upgrade or migrate the BusinessObjects XI Repository. For example, during an upgrade, she might need to move objects from Development to Test and Production environments, or merge two repositories.
With any migration of data, you should perform any necessary backups. If the repository is not at the correct revision level, the Import Wizard will upgrade it to the correct level.
The Import Wizard, shown in Figure 17.2, is the tool that allows the user to migrate repositories from one version to another. The wizard walks the administrator through a number of steps, enabling her to determine what needs to be moved and which components will remain.
Figure 17.2 The Import Wizard shows the versions from which the user can import objects.
Although the utility is Windows-based, it only requires a client for Windows and can be used to connect to Crystal Enterprise and BusinessObjects systems hosted on Windows, UNIX, or Linux.
Upgrades from Earlier Versions of Crystal Enterprise and Crystal Info
Prior to version 9, no Report Object repository existed. The Crystal Import Wizard migrates the Crystal Enterprise repository from versions 10.x and below (refer to Figure 17.2). The Import Wizard enables users to import users, groups, report objects and instances, associated permissions, events, and server groups.
Upgrades from Crystal Enterprise 9
In version 9 of Crystal Enterprise and Crystal Reports, the repository was split into two databases. This consisted of the Crystal Reports repository that stored the text, bitmaps, SQL Command objects, and custom functions, and the Crystal Enterprise 9 repository that consisted of objects such as the users, folders, and so on.
To migrate the Crystal Enterprise 9 repository, the Migration Wizard is used as described previously in this chapter.
To migrate a Crystal Reports 9 repository to BusinessObjects XI, use the Repository Migration Wizard. This Windows-based utility is found on the BusinessObjects Enterprise CD and can be installed on the local administrator’s workstation. It requires the administrator to create a connection to the Crystal Reports 9 repository. After this connection is established, the administrator connects to the BusinessObjects XI, typically with administrator permissions, and the associated objects are imported.
For more information on setting the BusinessObjects Repository permissions, see “Setting Security of the Repository,” p. 401.
With any migration of data, you should back up the repository. The Migration Wizard does not move the data, but rather copies it, leaving the existing database intact.
If an object exists with the same name, the Crystal Reports Migration Wizard does not copy over the database, but rather informs the user that there is a duplicate object and the original has not been migrated.
Migrations from BusinessObjects 6.x
The Import Wizard allows administrators to migrate BusinessObjects 6.x systems over to BusinessObjects XI systems. Before undertaking this migration, the administrator should be aware what will upgrade and what will not.
What Does Import?
For a successful import, ensure that your XI system has the same rights and middleware as your 6.x system and that the user performing the upgrade has sufficient operating system rights. For example, if a universe requires the Oracle 9 client to be installed, this needs to be created on the target machine before beginning the upgrade.
The following components are imported into the system:
- Universes—You can import all universes and related objects or you can import the universes related to the documents you are importing. The latter approach is best used if you are using this upgrade as an opportunity to clean your XI system of any unwanted universes.
- Associated users and groups—Enterprise 6.x profiles map to Enterprise XI groups; for example, the General Supervisor profile maps to the Administrators Group. Any users’ personal documents can be added to their favorites folder in Enterprise XI.
- Permissions—Supervisor in BusinessObjects 6 has been replaced by the Central Mananagement Console (CMC) in BusinessObjects XI. However, for the users and groups selected, their associated permissions will be migrated in the form of restriction sets.
- Domains and categories—Domains are created as folders and all associated categories are created as categories.
User and group permissions might not map directly or might not import; therefore, your target objects can end up being more restrictive than intended. Administrators should check granted permissions at the target location to verify they have been imported as desired.
- Web intelligence documents—By selecting their associated domains, the administrator can import the WebI documents. Alternatively, selecting the document will import its associated domain.
- Third-party documents—With the ability to host third-party documents, such as Microsoft Office Documents, PDF, and text files, any XI supported document can be imported.
What Does Not Import?
Before the organization embarks on an upgrade, it needs to be aware of what will not upgrade:
- Version 5.x and prior versions—If you are using an earlier version, you need to upgrade to version 6 before you can continue.
- Any BusinessObjects full-client reports—These might need to be re-created in Web Intelligence or Crystal Reports, depending on the requirement. If the report cannot be re-created in either of the above tools, you might want to use a parrallel install of XI or contact BusinessObjects as to when this will be available.
- WebIntelligence OLAP—A possible solution would be to rewrite these reports in OLAP Intelligence.
- BCA Scheduler, BCA Publisher, Supervisor, and Auditor components—These are not included in Enterprise XI. Anything created in these components will have to be re-created in XI using the CMC.
- Infoview preferences—The user preferences have changed considerably, so these will need to be reset.
- Customizations made using the SDK—If, for example, you have made customizations using the Enterpise SDK, these have to be moved over and retested. Changes made using the WIBean should be rewritten to use the Enterprise Java SDK.
- Custom Application Foundation components—Any cutomizations that you might have made to Application Foundation will not migrate.
It is expected that the ability to import and host full client documents (.rep) will be available in a future release of BusinessObjects. Depending on the requirement, it might be acceptable to rewrite the document in either Web Intelligence or Crystal Reports.
Sharing Components in the Repository
Imagine the real-life situation where an organization has thousands of Crystal reports, some of which have a copyright notice on the bottom of each page. The legal department decides it wants to change the verbiage on this copyright notice. The administrator faces three problems: which reports have this notice, how to make this change in a timely fashion, and how to effectively make these types of changes in the future.
Without having the ability to check commonly used components into the repository, the administrator would have the unfortunate task of checking each report for the copyright notice and making the change on each report individually.
To solve this problem, Crystal Report developers should store and reuse commonly used components in the repository.
These components include
- Text objects—Reusable text, such as company addresses or confidentiality text.
- Images—Bitmaps, metafiles, TIFF, JPEG, and PNG image formats.
- Custom functions—Business logic that could be reused by passing in new fields as variables.
- SQL Commands—Encapsulated SQL Commands enable you to write free-form SQL for data access, including parameters. The results are seen as a table by Crystal Reports.
- List of values—Dynamic or scheduled list of available parameter values.
One component not included in the BusinessObjects Repository is report templates. Although it is possible to secure the template via BusinessObjects Enterprise security, it is not possible to automatically loop through all the reports that reapply a new template. This task is possible but it is a manual process or requires that an administrative script be written.
When publishing the relevant reports back to Enterprise XI, the report developer should check the Update Repository Objects box, as shown in Figure 17.3. This allows the system to check whether any repository components have changed and to make the necessary report changes. If this box is not checked, the report is skipped and nothing in the report is updated, even if the report object has been changed in the repository. The Publishing Wizard and the Central Management Console also provide the ability to set this flag.
Figure 17.3 Select the Enable Repository Refresh box to allow this report to check for modified shared report components.
If the organization wants to make changes at a later date to the notice or any other shared objects, the developer would open the report, disconnect the text object, make the change, and resave the object to the repository. All reports that use the text component and have the Repository Refresh flag confirmed will adopt the new component.
Adding Text Objects and Images
To add text and image objects to your report from the repository, the repository explorer should be open in Crystal Reports. To open the repository explorer, select Repository Explorer from the View menu at the top of your screen. You might need to authenticate with BusinessObjects Enterprise either by logging on as prompted by the logon screen or by clicking on the Logon icon at the top of the Explorer. After this occurs, you can see all the folders and objects available in the repository. To add a text or image field, simply drag the field onto the report. You will notice that the object is read-only. To modify the object, right-click the object and select Disconnect from Repository. You will then be able to modify the object. If the changed object is saved back into the repository with the same name, the original version is replaced and all Crystal Reports that use this object and remain connected are updated the next time they are viewed.
To reconnect a text object or image to the repository, simply drag and drop the object from the Design or Preview tab in Crystal Reports back to its original repository object name in the Repository Explorer. A dialog will appear to confirm that you want to update the original object or add a new one. The user can then set the properties of the object by adding the required information.
For information on how to set the security around the object explorer, see “Business View Manager,” p. 400.
The capability to store objects from Web and OLAP Intelligence reports in the repository was not supported at publication time.
SQL Commands
With the introduction of SQL Command objects to Crystal Reports, developers have been able to write custom database SQL to access data. The repository enables the developers to share these objects with others who might not have that skill set or those developers who do not want to reinvent the wheel.
To select a SQL Command from the repository, select the Repository from the Data Explorer or the Data step of the Report Wizard. Once again, BusinessObjects Enterprise will ask you to authenticate to ensure you are a valid user. Select the required SQL Command from the repository. If the command has any parameters associated with it, you will be required to populate the parameters. This enables the SQL statement to run, which will then populate the report with data, providing the report designer with some data to work with.
To add a new SQL Command object to the repository, use the Database Expert, connect to the database desired in the Available Data Sources list box, and choose Add Command from the list of available options. Select Add Command by double-clicking on it. This opens the Add Command to Report dialog. Then follow these steps:
- Enter the SQL statement you want into the query box. If parameters are required, you can use this dialog to create them as well by clicking the Create button in the Parameter List section. Click OK to close the Add Command to Report dialog.
- You are brought back to the Data tab of the Database Expert dialog. Before leaving this dialog, right-click the newly created SQL object under the selected tables pane and select the Add to Repository option.
- Complete the form by giving your SQL command object a name and then selecting a folder where you want to store the object.
If the user wishes to edit the SQL command object, she needs to first disconnect it from the repository, making the edit button accessible.
Custom Functions
Custom functions are reusable procedures that enable you to share logic across reports. To allow for this sharing, the function needs to be data- and report-independent and specific guidelines must be adhered to:
- No User Function Libraries (UFL) can be used because these are machine dependent.
- No report or data source fields.
- You cannot associate a particular state with the function, such as Evaluation Time or Print State.
- You cannot use recursion; that is, the function cannot call itself.
- You cannot use variables, either shared or global, because these are report-specific.
Custom functions are not editable from the Repository Explorer because they are housed inside of Formulas. To view custom functions available in the Repository, go to Report, Formula Workshop. In the group tree, the Crystal Repository branch can be seen and all custom functions can be viewed from there.
Adding a new custom function to the repository needs to be done from within the Crystal Reports designer. The user can select the drop-down list from the new icon in the Formula Workshop. The function is then created and the user can select the Add to Repository icon, which adds the function to the desired location in the repository.
Organizing and Updating the Repository
The Repository Explorer represents the repository database as a tree structure made up of folders and objects. It is up to the report designer to decide how he wants to organize it. For example, the sample Repository that ships with BusinessObjects Enterprise XI is sorted by object types. The folders are named to indicate their contents (Images, Text Objects, and Commands). However, the content creator or report designer can use folders to his organizational advantage.
To add new folders to the repository, right-click on the desired folder where the intended subfolder is to be placed. If the folder is intended to be at the root, right-click on the repository name. Choose New Folder from the context menu.
To move objects or folders, drag and drop the object to the desired location. To rename a folder, simply choose the folder to be renamed, right-click on it, and choose Rename from the context menu.
After the shared object has been changed, there is an update process called the Object Repository Helper (found on the Administrator’s Launchpad page under the Administrator’s Tools section) that will loop through all the reports and update the changed component. An administrator can select all reports, individual reports, or all reports within a folder and its subfolders.
Troubleshooting
Editing Custom Functions
I can’t seem to edit my custom functions from the Repository Explorer.
Custom functions are not editable from the Repository Explorer because they are housed inside of Formulas. To view custom functions available in the Repository, go to Report, Formula Workshop. In the group tree, the Crystal Repository branch can be seen and all custom functions can be viewed from there.
Business Views Are Gone
When creating a new report, I see my available Business Views; however, after I open the Repository Explorer in Crystal Reports, the Business Views disappear.
The Repository Explorer in Crystal Reports is context-sensitive and only displays objects that can be used within the report itself.
Migrating the Repository
In Crystal Reports 9, the sample Repository database was in Microsoft Access format. Can I migrate this to BusinessObjects XI?
In BusinessObjects XI, Microsoft Access is not a supported Repository database. The Access database will need to be migrated to a supported database such as SQL Server. The Crystal Repository Migration Wizard will connect to the Access database and transfer all the data to the SQL Server database for the user. However, for this to be successful, it assumes the user has not modified the Access database.
Migrating the Repository
Why did the shared components not change on the reports when I updated them in the repository?
The Use Object Repository When Refreshing Report field needs to be checked. This field can be found using the CMC under objects and refresh options.
The Repository Helper process also needs to be run for the objects to be updated.