Linking Objects to Hyperion Essbase Data

This chapter describes linked reporting objects (LRO). This feature, similar to the file attachment feature in many e-mail software packages, lets you link various kinds of data with any cell in a Hyperion Essbase database. Linked reporting objects provides improved support for planning and reporting applications and can enhance your data analysis capabilities.

This chapter contains the following sections:

What Are Linked Reporting Objects?

Linked reporting objects are objects that you associate with specific data cells in a Hyperion Essbase database. An object can be a paragraph of descriptive text, a separate file such as a graph, bitmap image, or audio clip, a Uniform Resource Locator (URL), or a link to data in another Hyperion Essbase database.

Hyperion Essbase supports the following types of linked objects:

*Table 12-1: Types of Linked Objects*
Object Type	Description
Cell note	A text annotation of up to 599 characters.
File	An external file, such as a Microsoft Word document, an Excel spreadsheet, a scanned image, an audio clip, or an HTML file (for example, `mypage.htm`).
URL	An acronym for Uniform Resource Locator. A string that identifies the location of a resource on the World Wide Web, such as a document, image, downloadable file, service, electronic mailbox, or other resource. Examples of URLs are: `http://www.hyperion.com` `ftp://ftp.hyperion.com` `file:///D\|/ESSBASE/docs/index.htm`
Linked partition	A set of data cells that you can link to in another Hyperion Essbase database. For more information on linked partitions, see Designing Partitioned Applications.

For example, a sales manager may attach cell notes to recently updated budget items. A finance manager might link a spreadsheet containing supporting data for this quarter's results. A product manager might link bitmap images of new products. A sales manager may link the URL of a company's Web site to quickly access the information on the Web site.

Users create linked objects through the Hyperion Essbase Spreadsheet Add-in interface by selecting a data cell and choosing a menu item. There is no limit to the number of objects you can link to a cell. The objects are stored on the Hyperion Essbase server where they are available to any user with the appropriate access privileges. Users retrieve and edit the objects through the Linked Objects Browser, which displays all objects linked to the selected cell.

The next section describes in more detail how Hyperion Essbase manages linked reporting objects. For more information on how end users work with these objects, see the Hyperion Essbase Spreadsheet Add-in User's Guide.

How Do Linked Reporting Objects Work with Hyperion Essbase?

Linked reporting objects are linked to data cells--not to the data contained in the cells. The link is based on a specific member combination in the database. Adding or removing links to a cell does not affect the cell contents.

When a user links an object to a cell, Hyperion Essbase creates an entry for the object in the linked object catalog for the database. The catalog, an internal data structure stored with the database's index, contains information describing the object, such as the object handle, object type, the name of the last user to modify the object, and the date the object was modified. Developers use the object handle in Hyperion Essbase API functions to refer to the object.

If the object is a cell note, the text is stored as part of the object description in the catalog entry. If the object is a file, the Storage Manager stores the contents of the file in the database's directory on the server, giving it a.LRO extension. Hyperion Essbase imposes no restrictions on the data formats of linked files and performs no file-type checking. It is up to the user's client machine to render the file after retrieving it from the Hyperion Essbase server.

If the object is a URL, Hyperion Essbase stores the URL string as part of the object description in the catalog entry. Hyperion Essbase does not check the syntax of the URL until the user tries to view it. At that time, Hyperion Essbase does a preliminary syntax check; then the default Web browser checks for the existence of the URL.

The third kind of linked object, linked partition, is available through the Hyperion Essbase Partitioning feature. For more information on linked partitions, see Designing Partitioned Applications.

Note:

Hyperion Essbase uses a database's index to locate and retrieve linked objects. If you remove data values from a database by choosing Database > Clear Data > All in the Hyperion Essbase Application Manager, the index is deleted and so are the links to linked objects. If you restructure a database, the index is preserved and so are the links to linked objects.

Shared members share data values but do not share linked reporting objects. This is because linked reporting objects are linked to specific member combinations and shared members do not have identical member combinations. If you want a given object to be linked to shared members, you must link it to each shared member individually.

Managing Linked Reporting Objects

This section discusses storing and maintaining linked reporting objects on the server.

Providing Access to Linked Reporting Objects

Users who add, edit, and delete linked reporting objects through client interfaces need to have the appropriate security privileges in the active database. If the object is a linked partition, the user must also have the required privileges in the database containing the linked partition. The following table lists the privileges required for several different tasks.

*Table 12-2: Privileges Required for LRO Tasks*
Task	Access Level
Add a linked object to a database	Read/Write
View an existing linked object	Read
Edit an existing linked object	Read/Write
Delete a linked object	Read/Write

Sometimes you might want to prevent users from linking files to data cells without changing their access to other data in a database. You can accomplish this by setting the maximum file size for linked files to 1. Users can then create cell notes, link to a URL, or view linked partitions but can only attach very small files (under 1 kilobyte).

Limiting LRO File Sizes

Because Hyperion Essbase stores linked files in a repository on the server, you might want to limit the size of files that users can link. This would prevent a user from taking up too much of the server's resources by storing extremely large objects. You can set the maximum linked file size for each application. If a user attempts to link a file that is larger than the limit, an error message displays.

Note:

The maximum file size setting applies only to linked files and does not affect cell notes or URLs. The maximum cell note length is fixed at 599 characters. The maximum URL string length is fixed at 512 characters.

By default, the maximum file size for linked files is unlimited. To specify a maximum file size for an application:

In Hyperion Essbase Application Manager, connect to the appropriate server and select the name of the application.
Select Application > Settings to display the following dialog box:
Figure 12-1: Application Settings Dialog Box
Enter the maximum file size (in kilobytes) in the Max. Attachment File Size text box.
To prevent users from attaching anything except very small files, enter 1. This lets users link only cell notes, URLs, and files less than 1 kilobyte in size.
Click OK to save your setting.

Viewing and Deleting Linked Reporting Objects

Users work with linked reporting objects through the Spreadsheet Add-in on a cell-by-cell basis. That is, they select a cell and open the Linked Object Browser which displays the objects linked to the selected cell. Through Hyperion Essbase Application Manager, you can view and delete all linked reporting objects for the entire database. You can also view linked reporting objects based on selection criteria such as user name and last modification date. For example, you might want to purge all objects that are older than a certain date, or remove the objects belonging to a user who has left the company.

To view or delete the linked objects for a database, follow these steps:

From the Application Desktop window, select the application and database name.
Select Database > Linked Reporting Objects to display the following dialog box:
Figure 12-2: Linked Reporting Objects Dialog Box
Specify your selection criteria as follows:
- To select by modification date, select By Date and enter a modification date. Objects modified on or before the date are selected.
- To select by user name, select By User and select a user name. Objects last modified by the user are selected.
  If you select both options, objects matching both criteria are selected. If you select neither By Date nor By User, all objects in the database are selected.
To delete all objects that meet your criteria, click Delete. To see a list of the objects that meet the criteria, click Preview. If you click Preview, Hyperion Essbase displays the Linked Objects Browser:
Figure 12-3: Linked Objects Browser

In the Linked Objects Browser, the Linked Objects list box displays all the objects that match the criteria you entered. To view, edit, or delete an object, first select it and then click the appropriate button. After you select an object, the member combination it is linked to displays for your reference. The actions you can perform vary depending on the type of object you select.

If you select a linked file, you can:

Click View/Launch to view the contents of the file. Hyperion Essbase retrieves the file from the server, copies it to your local client operating system's temporary directory, and saves it under a temporary file name. It then sends a command to the client operating system to open the temporary file. If you make changes to the file and wish to save your changes on the Hyperion Essbase server, first save the file on your client machine (making note of the temporary file name), then return to the Linked Objects Browser and click Edit to re-attach the new file.
Click Edit to re-attach the linked file. You can use this to update the contents of the linked file with a newer version, or to replace the file with a different one.
Click Delete to delete the link. This destroys the link in the index file and removes the file from the server. It does not affect copies of the file stored locally on client machines.

If you select a cell note, you can:

Click View/Launch to read the cell note.
Click Edit to edit its contents.
Click Delete to remove it from the database.

If you select a URL, you can:

Click View/Launch to open your default Web browser to view the URL.
Click Edit to edit the URL string.
Click Delete to delete the link.

Note:

You cannot make changes to linked partitions from the Linked Objects Browser. To create or change a linked partition, open the Partition Manager by choosing Database > Partition Manager. For more information on linked partitions, see Designing Partitioned Applications.

You cannot change the member combination associated with any linked object through Hyperion Essbase Application Manager. To move an object to another member combination, first delete it, then use the Spreadsheet Add-in to re-link the object to the desired member combination.

Use the LISTLINKEDOBJECTS and PURGELINKEDOBJECTS commands in ESSCMD to perform these tasks. See the online Technical Reference in the DOCS directory for information about these commands. See Performing Interactive and Batch Operations Using ESSCMD for information about ESSCMD.