Hyperion System 9 BI+ Application Builder Administrator's Guide

HYPERION® SYSTEM™ 9 BI+™ APPLICATION BUILDER J2EE™ RELEASE 9.2

SYSTEM ADMINISTRATOR’S GUIDE Copyright 1998–2006 Hyperion Solutions Corporation. All rights reserved.

“Hyperion,” the Hyperion “H” logo, and Hyperion’s product names are trademarks of Hyperion. References to other companies and their products use trademarks owned by the respective companies and are for reference purpose only.

No portion hereof may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the recipient’s personal use, without the express written permission of Hyperion.

The information contained herein is subject to change without notice. Hyperion shall not be liable for errors contained herein or consequential damages in connection with the furnishing, performance, or use hereof.

Any Hyperion software described herein is licensed exclusively subject to the conditions set forth in the Hyperion license agreement.

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the applicable Hyperion license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (Oct 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14, as applicable.

Hyperion Solutions Corporation 5450 Great America Parkway Santa Clara, California 95054

Printed in the U.S.A. Contents

Preface ...... 9 Purpose ...... 9 Audience ...... 9 Document Structure ...... 9 Where to Find Documentation ...... 10 Conventions ...... 12 Additional Support ...... 13 Education Services ...... 13 Consulting Services ...... 13 Technical Support ...... 13 Documentation Feedback ...... 13

CHAPTER 1 Administration Tools Overview ...... 19 Accessing the Launch Page and Administration Tools ...... 20 Navigating Application Builder Administration Tools ...... 22

CHAPTER 2 Using Security ...... 23 Configuring Security ...... 23 Application Configuration ...... 23 Data Source Configuration ...... 24 ATF Repository Configuration ...... 25 Implementing Security ...... 26 Application Security ...... 26 Data Source Security ...... 27 ATF Repository Security ...... 28 Using the ATF Repository ...... 29 Setting Up ATF Repository XML Files ...... 30 Using Localized Strings ...... 40 Initializing the ATF Repository ...... 40 Using the ATF Repository ...... 41 Using Single Sign-on ...... 41 About External Authentication ...... 42 About Single Sign-On ...... 42

Contents 1 Support for SiteMinder ...... 43 Prerequisites ...... 44 Setting Up the Environment for NT LAN Manager Support ...... 44 Configuration for External Authentication ...... 47 Configuring for SiteMinder Single Sign-On ...... 58 Sample Deployment Scenarios ...... 58 Scenario 9: Multiple NTLM Domains with Trust Relationships ...... 65 Scenario 10: Multiple NTLM Domains Connected with Hyperion Remote Authentication Module ...... 66 Scenario 11: Single Sign-on with SiteMinder ...... 67 Setting up Single Sign-On Authentication for Application Builder ...... 68

CHAPTER 3 Edit Member Tool ...... 73 Accessing the Edit Member Tool ...... 73 Managing Dimension Members ...... 73 Configuring the Edit Members Tree ...... 74 Arranging the Member Order ...... 74 Editing Member Properties ...... 74 Deleting Members from a Dimension ...... 75

CHAPTER 4 Repository Objects Tool ...... 77 Accessing the Repository Objects Tool ...... 77 Managing Views ...... 78 Using OLAP Views ...... 78 Creating or Editing Tasks ...... 81 Using Relational Views ...... 81 Creating Folders ...... 88 Deleting Views ...... 88 Running Views ...... 88 Setting Permissions ...... 89

CHAPTER 5 XML Setup Tool...... 91 Accessing XML Files ...... 92 Annotation XML Setup ...... 93 Creating OLAP Annotations ...... 93 Creating Relational Annotation XML Files ...... 99 Cell Format XML Setup ...... 104 Accessing the Cell Format Tool ...... 104 Creating OLAP Cell Format XML Files ...... 105 Creating Relational Cell Format XML Files ...... 111 Data Source XML Setup ...... 119 Accessing the Data Source Tool ...... 120 Navigating the Data Source Tool ...... 120

2 Contents Selecting and Synchronizing the Data Source XML Files ...... 121 Populating the Data Source XML File ...... 122 Modifying the Node Settings ...... 123 Managing ADM Pools ...... 124 Managing Folders ...... 127 Managing OLAP Data Sources ...... 128 Managing Relational Data Sources ...... 130 Managing Cube Nodes ...... 132 Drill Through XML Setup ...... 133 Accessing the Drill Through Setup ...... 134 Managing Drill Through Mappings ...... 134 Defining the WAA Drill Through Source ...... 135 Defining Drill Through Targets ...... 136 Defining Drill Through Queries ...... 137 Defining Global Mappings ...... 138 Grid Export XML Setup ...... 139 Accessing the Grid Export Setup ...... 139 Creating or Editing Grid Export XML Files ...... 140 Single Sign-on XML Setup ...... 142 Accessing the Single Sign-on Setup ...... 142 Creating or Editing Single Sign-on XML Files ...... 143 Task Registry Setup ...... 146

CHAPTER 6 Conversion Tool ...... 149 Accessing the Conversion Tool ...... 150 Converting a Repository ...... 150

CHAPTER 7 Security Tool ...... 153 Accessing the Security Tool ...... 153 Managing Users ...... 154 Creating or Editing Users ...... 154 Deleting Users ...... 154 Setting User Permissions and Special Permissions ...... 155 Managing Groups ...... 155 Accessing Groups ...... 156 Creating or Editing Groups ...... 156 Setting Permissions and Special Permissions for Groups ...... 157 Managing Object Types ...... 159 Setting Special Permissions for Object Types ...... 159 Setting Object Type Permissions ...... 161

CHAPTER 8 Managing Shared Services Models Tool...... 163 Overview ...... 163

Contents 3 Configuring Application Builder for Shared Services ...... 164 Accessing Manage Models ...... 164 Registering Application Builder ...... 165 Setting Up Guided Analysis ...... 166 Setting up Guided Analysis Links ...... 167 About Managing Metadata ...... 167 About Sharing Metadata ...... 168 About Sharing Data ...... 168 Working with Projects ...... 168 Working with Application Projects ...... 168 Working with Shared Projects ...... 169 Managing Projects ...... 170 Working with Models ...... 173 Synchronizing Models ...... 175 Comparing and Merging Models ...... 176 Viewing and Editing Model Content ...... 178 Renaming Models ...... 179 Sharing Models ...... 180 Filtering the Content of Models ...... 181 Tracking Model History ...... 182 Managing Permissions to Models ...... 183 Viewing and Setting Model Properties ...... 187 Sharing Data ...... 188 Prerequisites to Moving Data Between Projects ...... 189 Managing Data Integrations ...... 189 Creating or Changing a Data Integration ...... 190 Deleting Integrations ...... 194 Scheduling Integrations ...... 195 Managing Scheduled Integrations ...... 196 Grouping Integrations ...... 198

CHAPTER 9 Using and Scheduling Tasks ...... 201 Initializing the Task Registry ...... 202 Initializing Web.xml ...... 202 Using a Task Definition Builder ...... 203 Scheduling Task Definitions ...... 207 Sample Task Definitions ...... 208 Examples ...... 209

APPENDIX A Using Tasks...... 221 Using the Task Registry ...... 225 General Tasks ...... 226 Conditionals ...... 227

4 Contents Database Meta Data ...... 227 Database ...... 228 Data Source ...... 229 Error Log ...... 230 Else ...... 231 File Input Stream ...... 232 File Notify Alert ...... 232 File Writer ...... 233 File Properties ...... 234 Fixed Properties ...... 235 Grouping ...... 236 Link ...... 236 Mail Notify Alert ...... 237 Mail Server ...... 238 Mail ...... 239 Sql Notify Alert ...... 240 Sql Properties ...... 241 Sql Result Set Metadata ...... 241 Sql Statement ...... 242 URL ...... 242 URL Datasource ...... 243 User File Properties ...... 244 Core Tasks ...... 245 Evaluate Scripting Framework Script ...... 245 Execute Scripting Framework Script ...... 246 Get Scripting Framework Member ...... 246 Grid Export Data Source ...... 247 Grid Export Manager ...... 247 Grid Export ...... 248 If Scripting Framework Script ...... 249 Repository Object ...... 249 Scripting Framework ...... 250 Set Scripting Framework Member ...... 251 OLAP Tasks ...... 251 Add Cube View Cell Value Format Cube Format ...... 252 Cube ...... 253 Cube View Cell Value Format Manager ...... 254 Cube View Cell Value Format ...... 254 Cube View Export Data Source ...... 255 Cube View Export Manager ...... 256 Cube View Export ...... 256 Cube View Grid ...... 257 Cube View ...... 257 Schema ...... 258

Contents 5 Relational Tasks ...... 259 Add Query Information Cell Value Format Database Format ...... 260 JDBC Data Source ...... 261 Query Information Cell Value Format Manager ...... 262 Query Information Cell Value Format ...... 262 Query Info Export Data Source ...... 263 Query Info Export Manager ...... 264 Query Information Export ...... 264 Query Information Grid ...... 265 Query Information ...... 265

APPENDIX B Setting up OLAP Data Sources and ADM Pooling ...... 267 Specifying the Data Source XML File Name ...... 268 Defining the OLAP Data Source and Cube ...... 268 Defining the ADM pool ...... 270 Defining the ADM Pool Configuration ...... 271 Encrypting Passwords ...... 272 Data Source XML File Examples ...... 273 Defining OLAP Data Sources in Tree Format ...... 273 Defining OLAP Data Sources in a Flat List ...... 275 WAADataSources.xml File ...... 276

APPENDIX C Setting Up Relational Data Sources ...... 279 Setting Up Relational Data Sources ...... 279 Using a WAA Drill-Through ...... 281 Before You Begin ...... 282 Enabling Drill-Through in the Web.xml File ...... 282 Defining the WAADrillThrough.xml Tags ...... 282 Setting Up the Drill-Through File ...... 285

APPENDIX D Setting Up Formatting XML Files...... 291 Using a Relational Formatting XML File ...... 291 Tags ...... 292 Example ...... 293 Processing ...... 294 Using an OLAP Formatting XML File ...... 294 Tags ...... 296 Example ...... 298 Processing ...... 299 Formatting Objects ...... 299 Numeric Formatting ...... 299 Date/Time Formatting ...... 302

6 Contents APPENDIX E Setting Up Annotation XML Files ...... 305 Using a Relational Annotation XML File ...... 305 Tags ...... 307 Example ...... 308 Relational Annotation Processing ...... 309 Using an OLAP Annotation XML File ...... 310 Tags ...... 311 Example ...... 311 Processing ...... 313

APPENDIX F Setting Up Export XML Files ...... 315 Setting up the Export XML File ...... 315 Tags ...... 316 Example ...... 317 Processing ...... 318 Setting XSLT Parameter Values ...... 319 Cell Rendering Parameters ...... 320

APPENDIX G Setting Up Universal Chart XML Files ...... 323 Setting up the Universal Chart XML File ...... 323 Tags ...... 324 Setting Universal Chart Name and Values ...... 325 Example ...... 325

Glossary...... 329

Index ...... 339

Contents 7 8 Contents Preface

Welcome to the Hyperion® System™ 9 BI+ Application Builder J2EE™ System Administrator’s Guide. This preface discusses the following topics:

● “Purpose” on page 9

● “Audience” on page 9

● “Document Structure” on page 9

● “Where to Find Documentation” on page 10

● “Conventions” on page 12

● “Additional Support” on page 13

● “Documentation Feedback” on page 13

Purpose This guide provides information that you need to deploy the EAR files, create and configure a JDBC data source, add users, roles, and groups, and set up security. It explains features and options and contains the concepts, processes, procedures, formats, tasks, and examples that you need to use the software.

Audience This guide is for system administrators who are responsible for installing and customizing Application Builder at their site.

Document Structure This document contains the following information: Chapter 1, “Administration Tools Overview,” provides an overview of each Administration Tool. Included is general navigation and access information. Chapter 2, “Using Security,” describes how to set up security for users, applications, data sources, ATF repository and single sign-on.

Preface 9 Chapter 3, “Edit Member Tool,” provides instructions for using the Edit Member tool for administrating the members of OLAP cubes. Chapter 4, “Repository Objects Tool,” provides instructions for managing views to OLAP data sources, and SQL queries to relational data sources. Chapter 5, “XML Setup Tool,” provides procedures for managing the selection and assignment of XML files used to communicate data between the application and Application Builder. The individual utilities manage OLAP and relational annotations, OLAP and relational cell formatting, OLAP and relational data sources, WAA drill throughs, and exporting view, query and grids to file formats. Chapter 6, “Conversion Tool,” describes how to convert views and queries stored in Application Builder release 2.5 repository to the release 3.0 ATF repository. Chapter 7, “Security Tool,” describes how to manage all of you applications users, groups and repository object types. Permissions and special permissions are also defined and described. Chapter 8, “Managing Shared Services Models Tool,” describes how to enable you to share metadata models between Application Builder applications and applications from other products. Chapter 9, “Using and Scheduling Tasks,” describes how to use tasks to create, schedule and distribute reports and to send alerts. Appendix A, “Using Tasks,” describes the tasks that are loaded in the task registry and used to construct task definitions. Appendix B, “Setting up OLAP Data Sources and ADM Pooling,” describes how to set up the data source XML file to define ADM pooling. Appendix C, “Setting Up Relational Data Sources,” describes how to set up XML files for your relational data sources. Appendix D, “Setting Up Formatting XML Files,” describes how to format XML files to define formatting for relational or OLAP data. Appendix E, “Setting Up Annotation XML Files,” describes how to set up an XML file to define a relational or OLAP data cell. Appendix F, “Setting Up Export XML Files,” describes how to set up an XML file to export a grid, join, or transformation grid to the following formats: PDF, RTF, HTML, Excel, or Power Point. Appendix G, “Setting Up Universal Chart XML Files,” describes how to set up XML files to chart a universal result set. Glossarycontains a list of key terms and their definitions. Indexcontains a list of Application Builder terms and their page references.

Where to Find Documentation All Application Builder documentation is accessible from the following locations:

10 Preface ● The Hyperion Solutions Web site is located at http://www.hyperion.com.

● Access to the Hyperion Download Center is through http://hyperion.subscribenet.com.

➤ To access the documentation after installation, perform one of the following:

● To access the PDFs and HTML files, navigate to \ApplicationBuilder\7.0.0\docs where HAB Install Directory > is the location where Application Builder is installed.

● To access the hab-docs.war file: a. Navigate to \ApplicationBuilder\7.0.0\waa\war\docs. b. Unzip hab-docs.war and extract docs-general.jar. c. Unzip docs-general.jar. Each guide is delivered in PDF and HTML format. You must unzip the HTML guides before using them.

➤ To access the documentation after installation and deployment: 1 If necessary, start the application server, relational data source server, and OLAP server. 2 Open the Information Map in one of the following ways:

● Select Start > Programs > Hyperion Solutions > Application Builder > Launch Page, then click Documentation or Information Map.

● Type the following URL in your Web browser: http://hostname:port/hab-docs/docs/information_map_HAB.htm

where hostname:port is the computer name or IP address and port of the Admin Tool. If you installed Application Builder on your computer, the hostname is localhost. If you are using Apache Tomcat, the port is 8080.

➤ To access documentation from the Hyperion Solutions Web site: 1 Log on to http://www.hyperion.com. 2 Select the Support link and type your username and password to log on.

Note: New users must register to receive a username and password.

3 Follow the on-screen instructions.

➤ To access documentation from the Hyperion Download Center: 1 Log on to http://hyperion.subscribenet.com. 2 In the Login ID and Password text boxes, enter your assigned login ID name and password. Then click Login. 3 If you are a member on multiple Hyperion Download Center accounts, select the account that you want to use for the current session.

Where to Find Documentation 11 4 Follow the on-screen instructions.

➤ To order printed documentation:

● Visit the Hyperion Solutions Web site at http://www.hyperion.com.

● In the United States, call Hyperion Solutions Customer Support at 877-901-4975.

● From outside the United States, including Canada, call Hyperion Solutions Customer Support at 203-703-3600. Clients who are not serviced by support from North America should call their local support centers.

Conventions The following table shows the conventions that are used in this document:

Table i Conventions Used in This Document

Item Meaning

➤ Arrows indicate the beginning of procedures consisting of sequential steps or one- step procedures.

Brackets [ ] In examples, brackets indicate that the enclosed elements are optional.

Bold Bold in procedural steps highlights major interface elements.

CAPITAL LETTERS Capital letters denote commands and various IDs. (Example: CLEARBLOCK command)

Ctrl + 0 Keystroke combinations shown with the plus sign (+) indicate that you should press the first key and hold it while you press the next key. Do not type the plus sign.

Example text Courier font indicates that the example text is code or syntax.

Courier italics Courier italic text indicates a variable field in command syntax. Substitute a value in place of the variable shown in Courier italics.

ARBORPATH When you see the environment variable ARBORPATH in italics, substitute the value of ARBORPATH from your site.

n, x Italic n stands for a variable number; italic x can stand for a variable number or an alphabet. These variables are sometimes found in formulas.

Ellipses (...) Ellipsis points indicate that text has been omitted from an example.

Mouse orientation This document provides examples and procedures using a right-handed mouse. If you use a left-handed mouse, adjust the procedures accordingly.

Menu options Options in menus are shown in the following format. Substitute the appropriate option names in the placeholders, as indicated. Menu name > Menu command > Extended menu command For example: 1. Select File > Desktop > Accounts.

12 Preface Additional Support In addition to providing documentation and online help, Hyperion offers the following product information and support. For details on education, consulting, or support options, visit Hyperion’s Web site at http://www.hyperion.com.

Education Services Hyperion offers instructor-led training, custom training, and eTraining covering all Hyperion applications and technologies. Training is geared to administrators, end users, and information systems (IS) professionals.

Consulting Services Experienced Hyperion consultants and partners implement software solutions tailored to clients’ particular reporting, analysis, modeling, and planning requirements. Hyperion also offers specialized consulting packages, technical assessments, and integration solutions.

Technical Support Hyperion provides enhanced electronic-based and telephone support to clients to resolve product issues quickly and accurately. This support is available for all Hyperion products at no additional cost to clients with current maintenance agreements.

Documentation Feedback Hyperion strives to provide complete and accurate documentation. We value your opinions on this documentation and want to hear from you. Send us your comments by clicking the link for the Documentation Survey, which is located on the Information Map for your product.

Documentation Feedback 13 14 Preface Chapter Administration Tools Overview 1

Welcome to Hyperion® System™ 9 BI+ Application Builder J2EE™, Administration Tools. The Administration Tools are designed to assist with the administration of applications created with Application Builder. There are six browser-based tools:

● “Edit Member Tool” on page 73 - The Edit Member tool adds, deletes, or modifies dimension members from a browser and saves them to the OLAP data source.

● “Repository Objects Tool” on page 77- The Repository Objects tool is used to access views to OLAP data sources, and SQL queries to relational data sources. You can also create tasks, alerts and schedule them.

● “XML Setup Tool” on page 91- The XML Setup tool manages the selection and assignment of several XML files used to communicate data between the application and Application Builder. There are five separate setups that affect seven XML files:

❍ Annotation - An annotation is textual data that is stored at the cell level. There are two kinds of annotations. One is an OLAP data cell, which can be an Hyperion System 9 BI+ Analytic Services™ linked reporting object (LRO) or a Hyperion System 9 Financial Management™ cell text. The other is a relational data cell, which consists of an Application Builder annotation as text, a URL, or a file.

❍ Cell Format - Cell formatting is using an XML file to define the format of an OLAP cube or a relational database at the cell level. The formatting you define is for the cell data and it applies either a numeric or date/time format.

❍ Data Source - The data source tool handles the XML generation for all application data source nodes. It includes forms for objects such as hierarchical folders, OLAP data sources, relational data sources, cubes, and pools. You can use the forms to create, edit, and manage these objects.

❍ Drill Through - The drill through tool is used to establish the path from an application's OLAP cube to a target relational system using SQL queries and storing them in an XML file. This tool provides screens where you can select a drill-through object for an application. It provides the steps required to establish a drill-through connection, such as defining a source and a target.

❍ Grid Export - The grid export tool exports a cube view, query info, or grid to the following formats: PDF, RTF, HTML, Excel, Power Point, or plain text. Only the grid is produced in the output.

Administration Tools Overview 19 ● “Conversion Tool” on page 149 - The conversion tool provides a means by which an application that is storing data in the Application Builder release 3.0 repository can convert the repository into a Application Builder release 7.0 relational repository. The data is pulled into the new repository and the old repository is not accessible to the Administration Tools.

● “Security Tool” on page 153 - The security tool provides all of the authorization data on users, which includes group management, role selection, and user management stored in the repository.

● “Managing Shared Services Models Tool” on page 163 - Registers Application Builder with Hyperion System 9 Shared Services™ and registers a server and URL which enable guided analysis functionality.

Accessing the Launch Page and Administration Tools From the Application Builder Launch page you can access all the necessary information, documentation, and tools needed to manage your applications. The launch page provides the following:

● Information about Application Builder

● Sample Application and Sample Pages

● Administration Tools

● Information Map which contains links to Application Builder documentation

➤ To access the Application Builder Launch page and Administration Tools: 1 Perform one of the following: a. Open a Web browser.

❍ In the address text box, enter the following URL to display the Application Builder launch page: http://:8080/hab-admin/ADMINApplicationServlet

Note: Where is the name of the computer where Application Builder Administration Tools and the Sample Application are installed. If you are accessing the Administration Tools from the server, the is “localhost.”

The Application Builder Launch Page is displayed:

20 Administration Tools Overview b. Click Start>Programs>Hyperion Solutions>Application Builder>Launch Page. The Application Builder Launch page is displayed:

c.

❍ Click on Administration Tools on the Application Builder launch page. The Administration Tools home page is displayed. 2 Optional: To use Application Builder Administration Tools in a different language, select one of the following from Language :

● German

● French

● Japanese

● English The default language is English.

Accessing the Launch Page and Administration Tools 21 3 Select the tool you want to use from the Administration Tools menu bar.

Navigating Application Builder Administration Tools While using the Application Builder Administration Tools, you have access to the following menu options in the upper right hand corner of the Administration Tools home page:

● Logoff/Login - This option logs out of or into Application Builder Administration Tools.

● Help - This option displays online help for Application Builder Administration Tools in a new browser window. In some cases it is context sensitive to the screen you are editing.

There are several navigation features common to all Application Builder Administration Tools. The following table describes those features: Table 2 Application Builder Administration Tools Navigation Features

Navigation Feature Description

Advanced Options button The Advanced Options button displays advanced options such as Find and the Expand/Collapse options.

Find drop-down list box This option provides the ability to search on either a node name or description. This feature is used in conjunction with the Find box and the Find Previous / Find Next buttons.

Node text box The Node text box is used to locate a node by specifying either a node name or description.

Find Previous / Find Next buttons These options execute the search defined in the Find drop-down list box and the Node text box.

Use Wildcards check box Wildcard characters provide the ability to use the asterisk (*) to represent text in searches.

Case-Sensitive check box When selected, the Case Sensitive check box makes search criteria case-sensitive.

Expand All / Collapse All buttons The Expand/Collapse All option expands or collapses the nodes of the tree.

Rows Per Page drop-down list box Enables you to display select numbers of rows of data in the Administration Tool tables, including: , 5, 10, 20, 50, 100, 250, or 500 rows. The default is 20 rows.

22 Administration Tools Overview Chapter Using Security 2

This chapter describes how to set up security for users, applications, data sources, ATF repository and single sign-on in the following sections:

● “Configuring Security” on page 23

● “Implementing Security” on page 26

● “Using the ATF Repository” on page 29

● “Using Single Sign-on” on page 41

Configuring Security You can configure application users, data source users, ADM pooling, and the ATF repository for use with your custom application. This section describes how to configure these components to work together to provide security.

Application Configuration You set up your custom Application Builder application to use J2EE or single sign-on security. The differences are listed below:

● J2EE users and roles implement security, authentication, and secure application resources, such as JSPs, URLs, and servlets.

● Single sign-on (SSO) users and groups implement security, authentication, and secure application resources, such as JSPs, URLs, and servlets. The single sign on security is implemented by the WAACssAuthenticationServletFilter filter, which emulates the J2EE framework. Using single sign-on for application users provides two main benefits:

❍ The existing corporate structure of user accounts is utilized by Hyperion applications, thus reducing administrative overhead

❍ The need for users to log on to multiple Hyperion applications is eliminated. After a user is authenticated in one Hyperion application, SSO information is passed to other applications; therefore, the user does not need to explicitly sign on.

J2EE roles or SSO groups determine access to an application and are used to secure application resources. You can assign one or more roles or groups to a user. Roles or groups also map application users to ADM pools, which are used to connect to OLAP data sources. For

Using Security 23 instructions on how to implement single sign-on security, see“Using Single Sign-on” on page 41. For instructions on how to implement J2EE security, see the Application Builder Installation Guide.

Data Source Configuration You set up access to relational data sources in the data source XML file and application server using your application server’s JNDI settings and connection pooling. When a user logs on to a Application Builder application, the user automatically has access to the current application’s relational data sources. You must create a relational data source to be used as the ATF repository; you can also use a relational data source for an annotations repository or drill- through data, or you can query against it. For instructions on how to set up a relational data source, see “Setting Up Relational Data Sources” on page 279. You set up access to OLAP data sources in the data source XML file. If an application uses ADM pooling, the administrator must also define ADM pools in the data source XML file. ADM pooling enables users to share a connection or license key to a data source. You define your ADM pools in the data source XML file. You must define an ADM pool for each role or group. For example, if a role or group is HAB_Viewer, then you must have an ADM pool with the name HAB_Viewer.

Note: If an application user has more than one role, the first matching pool found in the data source XML file is used.

Within the ADM pool, you define the schema, and cube and one OLAP user and password. When an application user is mapped to an ADM pool, the OLAP user id and password, defined in the pool, are used to create connect to the OLAP. You also configure settings for each ADM pool, such as the maximum number of ADM connections and the number of times to retry a connection. For more information, see “Setting up OLAP Data Sources and ADM Pooling” on page 267. The following figure summarizes the steps for setting up application users.

24 Using Security Figure 1 Application Security Components

ATF Repository Configuration The ATF repository stores object information for an application, such as folders, OLAP views, and relational views. It also contains users, groups, permissions, and special permissions which control security on the objects. You must add the J2EE user or SSO users to the ATF repository. Authenticated J2EE or SSO users are automatically added to the ATF repository the first time they access it. You can add them manually using the Administration Tools.

Note: For each J2EE user or SSO user, there must be a matching ATF repository user.

You use XML files to initialize the ATF repository, which define default users, groups, permissions, object types, and specific objects. You can assign users and groups to have permissions for specific objects. For example, you can assign one user read access and another user write access to the same view. For information on how to set up the ATF repository, see “ATF Repository Configuration” on page 25. The Typical installation option creates and initializes the Application Builder database, preparing it for use as the ATF repository. The following figure shows an overview of the ATF repository components.

Configuring Security 25 Figure 2 ATF Repository Components

Hyperion J2EE Users

SSO Users Add ATF Users

ATF Users

Permissions

Atf RDBMRepository Secured Objects S

Implementing Security You can configure application users, data source users, ADM pooling, and the ATF repository for use with your custom application. This section describes how these components work together to implement security.

Application Security Application security is based on the J2EE user and role or the SSO user and group. The following figure shows user authentication and application resource access defined in web.xml.

Figure 3 Application Security

User Authentication

J2EE SSO User/ User/Role Group

Application SSO

Server H yper ion Filter

Secured Application Resources

JSP URL Servlets

26 Using Security Based on the users, one of the following happens:

● The J2EE user id and password are sent to the application server for authentication. The J2EE role determines whether the user can access application resources.

● The SSO user id and password are sent to the existing corporate structure of user accounts for authentication. If the application user is not authenticated, an error message is displayed. The SSO group determines whether the user can access application resources.

Note: If the application user is not authenticated, an error message is displayed.

The Typical installation option sets up the following J2EE users and roles used by the Administration Tools, Sample Pages, HAB-test JSP pages, Tutorials and Sample Application. Table 3 Application Builder Default Users and Roles

J2EE User/Password Role Definition

Administrator HAB_Admin A user with administration privileges to /password applications. A user must have the HAB_Admin role to log on to the Administration Tools.

Viewer HAB_Viewer A user with read-only access to applications. A /password user must have the HAB_Viewer or HAB_Analyst role to log on to the Sample Application.

Analyst HAB_Analyst A user with read/write access to applications. A /password user must have the HAB_Viewer or HAB_Analyst role to log on to the Sample Application.

Note: HAB_Admin is a predefined role that you must assign to an application user in order for the user to logon to the Administration Tools. All users are also assigned to the HAB_User role. The HAB_User role assigns default ATF repository privileges to users.

If you are using SSO you must set up SSO users and groups similar to those in Table 3. For more information, see “Using Single Sign-on” on page 41.

Data Source Security Relational data source security is controlled by the relational data source user, which is managed by the Relational Database Management System and your application server. OLAP data source security is controlled by the OLAP data source user access rights. The following figure shows OLAP user authentication.

Implementing Security 27 Figure 4 OLAP Security

OLAP User Authentication

SSO User/ J2EE User/Role Group

ADM Pool

OLAP User

OLAP Datasource

The J2EE user's role or the SSO user’s group is used to find a matching ADM pool. An OLAP user id and password is retrieved from the ADM pool definition and used to connect to OLAP. The ADM connection can be used by one or more application users. The Typical installation option uses the information defined in Table 4. The ADM pools are defined in the WAADataSources.xml file. You need to add the Essbase users. If you are using the Hyperion System 9 Analytic Deployment Services (EDS) driver you need to add the users to EDS also. Table 4 Application Builder Default Essbase Users

Essbase User/Password Role/ADM Pool Definition

Administrator HAB_Admin A user with supervisor access to Essbase. /password

viewer HAB_Viewer A user with read-only access to Essbase. /password

analyst HAB_Analyst A user with read/write access to Essbase. /password

For instructions on how to set up an OLAP data source, see “Setting up OLAP Data Sources and ADM Pooling” on page 267

ATF Repository Security The ATF repository maintains an application’s internal objects, such as folders, views, task, scheduled tasks, and ATF users. The typical installation creates and initializes the Application Builder database for the ATF repository. The following figure shows user authorization and ATF repository object access.

28 Using Security Figure 5 ATF Repository Security

ATF User Authorization

J2EE User SSO User

ATF Users/ Groups

Permissions

Atf RDBMRepository Objects S

The ATF repository Administrator is defined in the application-services.xml file. This Administrator has administrative privileges enabling them to perform all tasks within the repository. The J2EE user or SSO user is automatically added and initialized as an ATF user the first time they access the ATF repository. You can grant ATF users access rights to object types and specific objects. For more information, see “Using the ATF Repository” on page 29 and “Security Tool” on page 153.

Using the ATF Repository

This section describes the Application Builder Analysis Tool Framework (ATF) Repository and how to set up the XML and property files for ATF repository functionality. You can utilize the ATF repository in a custom application using JSP tags. For more information, see the Hyperion System 9 BI+ Application Builder J2EE Web Application Architecture Developer’s Guide. Analysis Tool Framework (ATF) provides an object repository that leverages Jakarta's ObjectRelationalBridge (OJB), object/relational mapping tool and an internal security framework to provide secure access to its stored objects. Application Builder uses the ATF repository to persist its internal objects, which are OLAP views, relational views, scheduled tasks, task definitions, OLAP datasources, and relational datasources. This section uses the repository xml and property files deployed with the hab-samples application as examples. You can set up the repository XML and property files to perform the following tasks:

● “Defining Object Types” on page 32

● “Defining Permissions” on page 33

● “Defining the RDBMS Platform” on page 39

Using the ATF Repository 29 ● “Initializing the ATF Repository” on page 40

Once the ATF repository is initialized you can start using it in the following ways:

● Manually using the Administration Tools. For more information, see the “Repository Objects Tool” on page 77.

● Programmatically with JSP tags. For more information, see the “Using Tags” chapter in the Hyperion System 9 BI+ Application Builder J2EE Web Application Architecture Developer’s Guide.

Setting Up ATF Repository XML Files

You need to set up repository information in the following XML or property files:

● “web.xml” on page 30

● “application-services.xml” on page 31

● “hab-types.xml” on page 32

● “repository.xml” on page 38

● “Using Localized Strings” on page 40

web.xml You need to set up a default user and the repository initialization file (application- services.xml) for your application in the web.xml file. The repository initialization file (application-services.xml) specifies the services that the ATF repository provides, such as authentication, cron scheduling services, and task services. The default group is assigned to all ATF repository users automatically. This web.xml snippet defines the default group and the repository initialization file, located on the classpath, for the WAAApplicationServicesServlet.

Note: The WAAApplicationServicesServlet is required for ATF and performs basic initialization of ATF services:

WAAApplicationServicesServlet Application Services Servlet Servlet which handles starting ATF services com.hyperion.waa.web.core.WAAApplicationServicesServlet ConfigXMLFileName /application-services.xml File with information for the ATF Services RepositoryDefaultGroup HAB_User The default repository group

30 Using Security 1 The following web.xml snippet defines the default group HAB_USER for the WAAApplicationServicesServletFilter. The filter is required for ATF and provides ATF authentication: WAAApplicationServicesServletFilter Application Services Servlet Servlet which handles starting ATF services com.hyperion.waa.web.core.WAAApplicationServicesServletFilter RepositoryDefaultGroup HAB_User The default repository group

application-services.xml The application-services.xml file specifies the services that the ATF repository provides, such as authentication, cron scheduling services, and task services. You must specify the name of the administrator and a default group that all users belong to in the application- services.xml file. The following application-services.xml snippet specifies the value of Administrator for the administrator and Everyone as the default group name:

Note: The default group defined in the application-services.xml file is used internally only. The default group defined in the web.xml is assigned to all ATF users automatically.

Using the ATF Repository 31 hab-types.xml The hab-types.xml file specifies the object types, object permissions, and special permissions created when the ATF repository initializes. Each object is assigned a unique id in the hab-types.xml file. The , or tags are used to define all objects in the hab-types.xml file. The following table shows the object id ranges, the products that use them and a description. Table 5 ATF Object Id ranges

Object Id Range Product Description

-1 to -1999 Analysis Tools Framework This range is reserved for objects used by the Analysis Tools Framework.

-2000 to -11999 Application Builder This range is reserved for objects used by Application Builder.

-12000 to -501999 Hyperion products This range is reserved for objects used by other Hyperion Products.

-502000 to -511999 Custom applications This range is reserved for objects created for a custom Application Builder application.

Defining Object Types Object types define the objects used by a custom application, such as an OLAP view or relational view. A custom application creates instances of object types that are stored in the ATF repository. For example, an application can create several task definitions which are AtfTaskDefinition object types. The Analysis Tools Framework object types are defined as follows:

● task - Defines a scheduled task definition object type. You can create an instance of this object using the Administration Tools or the task tags. It appears as a Scheduled Task Definition object type in the Administration Tools.

● AtfTaskDefinition - Defines a task definition object type. You can create an instance of this object using the Administration Tools or the task tags. It appears as a Task Definition object type in the Administration Tools.

The Application Builder object types are defined as follows:

● WAAAtfOlapView- Defines an OLAP view object type. You can create an instance of this object using the useOlapView tag or using the Administration Tools. It appears as a Olap View object type in the Administration Tools.

32 Using Security ● WAAAtfRelationalView - Defines a relational view object type. You can create an instance of this object using the useRelationalView tag or using the Administration Tools. It appears as a Relational View object type in the Administration Tools.

● WAAAtfOlapDataSource - Defines an OLAP data source object type. This is created when the data source xml file is initialized or synchronized. It appears as a OLAP Datasource object type in the Administration Tools.

● WAAAtfRelationalDataSource - Defines the relational data source object type. This is created when the data source xml file is initialized or synchronized. It appears as a Relational Datasource object type in the Administration Tools.

Note: The atf-types.xml file defines system objects, such as users, groups and folders that are used internally by the ATF repository. It is located in the hyperion-atf.jar file.

Defining Permissions A special permission is a single bit, representing an access right. A permission is a combination of one or more special permissions. You assign permissions to define several activities that can be performed. For example, the Super Admin is granted all access rights and the ReadOnlyAnalyst can only read objects.

Default Special Permissions The default special permissions are defined by ATF and can be applied to all object types.

Figure 6 Default Special Permissions

The default special permissions have the following meaning:

● Read - The ability to read or view all objects types.

● Write - The ability to modify and save all object types.

● Delete - The ability to delete all object types.

● Change Permissions - The ability to write to change permissions on all object types.

● Change Owner - The ability to change the owner for all object types.

Using the ATF Repository 33 ● Owner - This bit signifies that you are the owner.

● List - The ability to list all object types.

● Create - The ability to create all object types.

User and Group Permissions User and group permissions define the activities that a user or group can perform that are defined by Application Builder. You assign the permissions and special permissions to a user or a group. The hab-types.xml file specifies the following permissions for users and groups:

The hab-types.xml file also specifies the following special permissions for users and groups:

The special permissions have the following meaning:

● AdministrateUsersGroupsPermissions - The ability to create, update, and delete permissions on a user or group.

● AdministrateFoldersObjects - The ability to create, update, and delete any folder or object.

● AdministratePermissions - The ability to create, update, and delete permissions on any object in the repository.

● AllPermissions - The ability to create, update, and delete permissions on any object in the repository and on users and groups.

● AdministrateDataSources - Create, update, and delete data sources in WAADataSources.xml. For example, the Administration tools looks for this in order to allow a user to modify the WAADataSources.xml file.

● AdministrateAnnotations - Create, update, and delete annotations.

● AdministrateDrillThroughs - Create, update, and delete drill-though information in WAADrillThrough.xml file. For example, the Administration tools looks for this in order to allow a user to modify the WAADrillThrough.xml.

● ChangeDataSourceMetadata - Enable a user to modify OLAP metadata.

34 Using Security ● ExecuteTaskDefinition - Enable a user to execute a task definition.

Special permissions are assigned to a bit in a mask. A mask is a unique set of 32-bit values where one or more bits are on or off (on = 1, off = 0). The following two figures show how a mask is used to define the ReadOnlyAnalyst permission. Figure 7 depicts a mask horizontally in binary format. In this figure the ReadOnlyAnalyst permission is defined with bits 0 and 7 are turned on which correspond to the special permissions of read and list respectively. Bit 0 = 20 (1) and bit 7 = 26 (64). The binary number below is equivalent to 65 in decimal:

Figure 7 Mask Configuration 0000 0000 0000 0000 0000 0000 0000 0000 0100 0001 | | | ------

User Assignable Reserved Figure 8 shows the special permissions that are set to 1 or 0 for a permission mask. The permission masks are on the columns and the special permissions are on the rows. For example, the ReadOnlyAnalyst is a permission consisting of the Read and List special permissions and is calculated to be 65 in decimal, shown at the bottom right of the table below.

Note: Bits 1 - 12 define default special permissions. Bits 22 - 32 are available for custom special permissions.

Figure 8 Permissions and Special Permissions for a User or Group

Using the ATF Repository 35 Olap View and Relational View Permissions Olap view and relational view permissions define the activities that can be performed on a view. You associate a user with a view and then assign the permissions and special permissions. The hab-types.xml file specifies the following permissions for OLAP views and relational views:

The hab-types.xml file also specifies the following special permissions for OLAP views and relational views:

The special permissions have the following meaning:

● RunReports - The ability to run an OLAP view or relational view.

● CreateCellAnnotations - The ability to create an OLAP cell annotation or relational row annotation.

● ModifyCellAnnotations - The ability to modify an OLAP cell annotation or relational row annotation.

● DeleteCellAnnotations - The ability to delete an OLAP cell annotation or relational row annotation.

● DisplayCellAnnotations - The ability to display an OLAP cell annotation or relational row annotation.

● CreateReportAnnotations - The ability to create an OLAP view annotation or relational view annotation.

● ModifyReportAnnotations - The ability to modify an OLAP view annotation or relational view annotation.

● DeleteReportAnnotations - The ability to delete an OLAP view annotation or relational view annotation.

36 Using Security ● DisplayReportAnnotations - The ability to display an OLAP view annotation or relational view annotation.

● InteractiveAnalysis - The ability to navigate using the zoom-in/zoom-out or remove- only/keep-only actions on an OLAP data cell.

● Drillthrough - The ability to drill-through from a OLAP data cell to another data source, such as Financial Management drill-through line item detail (DTLID), Analytic Services to Hyperion Integration Services drill-through, or a WAA drill-through from OLAP cell to a relational cell.

● DataWriteback - The ability to write to an OLAP cell or relational cell.

Figure 9 shows the special permissions that are set to 1 or 0 for a permission mask. The permission masks are on the columns and the special permissions are on the rows. For example, the Minimal Read permission enables a user to read, list and run a view.

Note: Bits 1 - 12 define default special permissions. Bits 25 - 32 are available for custom special permissions.

Figure 9 Permissions and Special Permissions for an OLAP View or Relational View

Using the ATF Repository 37 Task Definition Permissions Task definition permissions define the activities that can be performed on a task definition. The hab-types.xml file specifies the Execute permission which enables the execution of a task definition. This permission must be set in order to execute a task definition.

Figure 10 shows the special permissions on the rows for a task definition. Pre-defined permissions are not set up for task definitions.

Note: Bits 1 - 8 and bit 13 define default special permissions. Bits 14 - 32 are available for custom special permissions.

Figure 10 Special Permissions for a Task Definition

repository.xml The repository.xml specifies the information for the data source JDBC connection and the database table and column to Application Builder object mappings. This database object mapping tells OJB how to create an object when it retrieves it from the database.

38 Using Security Defining the RDBMS Platform The platform attribute is used to define the specific RDBMS Platform. This attribute corresponds to a org.apache.ojb.broker.platforms.PlatformXXXImpl class. The following repository.xml snippet specifies MySQL:

The following repository.xml snippet specifies DB2: password="habdbuser"/>

The following repository.xml snippet specifies WebLogic with DB2 8.1.4:

Note: With WebLogic, DB2 8.1.4 needs the following driver: com.ibm.db2.jcc.DB2Driver. Use port 50000 in the URL, not 6789. The DB2 driver files should be in db2jcc*.zip.

The following repository.xml snippet specifies MS SQL Server: microsoft.jdbc.sqlserver.SQLServerDriver" protocol="jdbc" subprotocol="microsoft:sqlserver" dbalias="//localhost:1433;DatabaseName=Name;SelectMethod=cursor;" username="name" password="password"/>

The following repository.xml snippet specifies Oracle Server:

Using the ATF Repository 39

Using Localized Strings You specify localized strings for the ATF objects in the atf_types.properties file. Localized stings are text strings used on the user interface. translated to a specific language. The following files specify localized strings:

● atf_types.properties for English

● atf_fr.properties for French

● atf_de.properties for German

● atf_ja.properties for Japanese

These strings correspond to the permission type names in hab-types.xml file that are displayed in the user interface. The following hab-types.xml snippet specifies the strings for the system objects: atf-system/user=Hyperion User atf-system/group=Hyperion Group atf-system/security-manager=Hyperion Administrator

Initializing the ATF Repository The first time the repository is used, it is automatically initialized and the following tasks are performed:

● The following default folders are added: /hyperion/task definitions /hyperion/olap /hyperion/relational /system (internal use only - not visible to any users) /system/datasource(internal use only - not visible to any users) /system/datasource/olap (internal use only - not visible to any users) /system/datasource/relational (internal use only - not visible to any users) /hyperion /hyperion/olap /hyperion/relational /system directory. This directory contains objects which are used by the system and should not be modified.

40 Using Security ● A group called HAB_USER is added and the following permissions are assigned:

❍ The special permissions create, read, list and write on the folders: /hyperion, /hyperion/olap and /hyperion/relational.

❍ The special permissions create, delete, read, list, write, change owner and change permission on object types olap view and relational view.

● The data source XML file, WAADataSources.xml, is read in and objects are created that access the OLAP and relational data sources. If you update the data source XML file and you want to implement the changes, you need to reload it using the Synchronize button on the XML Setup module of the Sample Deployment Scenarios

Using the ATF Repository The first time a user logs into the ATF repository the following user initialization takes place:

❍ The authenticated user is added as an ATF user

❍ The authenticated user is assigned to the HAB_USER group

❍ A folder with the authenticated user name is created.

❍ If the authenticated user’s role or group is not in the ATF repository, it is automatically added as an ATF repository group; however permissions are not assigned to it.

For example, if a user Jane Doe in the Analyst group signs onto the Administration Tools, and she is not an ATF user the following tasks are implemented:

❍ The user Jane Doe is created and assigned to the HAB_USER group.

❍ The group Analyst is created without permissions.

❍ A folder named Jane Doe is created.

Using Single Sign-on This section helps you set up Hyperion applications to use single sign-on authentications instead of J2EE authentication. Using single sign-on to manage user accounts on Hyperion applications provides two main benefits:

● The existing corporate structure of user accounts is employed by Hyperion applications, thus reducing administrative overhead

● The benefit of single sign-on to Hyperion applications is added, thus eliminating the need for users to log on multiple times with multiple user names and passwords

This chapter contains the following topics:

● “About External Authentication” on page 42

● “About Single Sign-On” on page 42

● “Prerequisites” on page 44

● “Setting Up the Environment for NT LAN Manager Support” on page 44

Using Single Sign-on 41 ● “Configuration for External Authentication” on page 47

● “The data source XML file, WAADataSources.xml, is read in and objects are created that access the OLAP and relational data sources. If you update the data source XML file and you want to implement the changes, you need to reload it using the Synchronize button on the XML Setup module of the Sample Deployment Scenarios” on page 41

● “Setting up Single Sign-On Authentication for Application Builder” on page 68

About External Authentication External authentication means that the user login information needed by Hyperion applications is stored outside the applications. Single sign-on always uses external authentication. The information is maintained in a central authentication directory, such as Lightweight Directory Access Protocol (LDAP) Directory, Microsoft Active Directory, or Windows NT LAN Manager. An authentication directory is a centralized store of user information such as login names and passwords, and perhaps other corporate information. The repository functions like a telephone directory. The authentication directory probably contains much more than user names and passwords; for example, it may include e-mail addresses, employee ids, job titles, access rights, and telephone numbers. It may also contain objects other than users; for example, it may contain information about corporate locations or other entities. In order to use external authentication for Hyperion applications, your organization must have an authentication directory that contains corporate user information. Additionally, you must modify the XML-based security configuration file associated with your product to specify correct information pertaining to your corporate authentication directory. The following types of authentication repositories are supported:

❍ Windows NT LAN Manager (NTLM), 4.0 or higher

❍ Lightweight Directory Access Protocol (LDAP)

❍ Microsoft Active Directory server (MSAD), Windows 2000 sp1 or higher

About Single Sign-On Single sign-on is the ability of a user to access multiple Hyperion applications after logging on only once. The user is externally authenticated the first time he logs in. When an externally authenticated user logs on to a Hyperion application, an encrypted token is generated which contains the user credentials in the form of:

● The user name

● In some cases, the user password. The presence of a password in the token depends on the configuration. If you are using a trusted authentication directory, no password is present or required in the token.

42 Using Security As shown in Figure 11, the token is passed among other Hyperion applications and is used as needed to automatically re-authenticate the user when the user moves to another application. Single sign-on is effective in cases where one Hyperion application launches another. Note that if a user launches a second application independently, for example, from the Start Menu, a token cannot be passed between the applications, and the user must re-authenticate.

Figure 11 Authentication to External Provider Enables Sign-On to Reach Multiple Applications

Tokens are encrypted; however, additional security such as Secure Sockets Layer (SSL) protocol is recommended for prevention of replay attacks or man-in-the middle attacks. To enable single sign-on between multiple Hyperion applications that launch one another, you must use a single XML configuration file that is shared by the multiple product installations. For more information, see “Configuration for External Authentication” on page 47.

Support for SiteMinder In addition to native Hyperion single sign-on, Hyperion applications can integrate with Web access management solutions such as the Netegrity product SiteMinder. SiteMinder is a Web access management solutions provider. Web access management solutions are employed by organizations to manage and enforce authentication, authorization, and single sign-on for web resources such as JSP files, ASP files, or HTML files. The Hyperion security platform enables single sign-on for a user into web-based Hyperion applications. Integration with a security agent requires configuration of the element in the XML configuration file.

Note: In this documentation, the terms security agent and Web security agent are interchangeable, and refer to any Web access management solutions provider such as SiteMinder.

The following security agents are tested and supported for single sign-on with Hyperion applications using the Hyperion security platform:

● SiteMinder Policy Server 5.5 Service Pack 2

● SiteMinder Web Agent 5.5 Service Pack 2

Using Single Sign-on 43 If your corporation has implemented SiteMinder to protect company Web resources, you can configure the security platform to require only that users authenticate through SiteMinder, after which they will not be required to present credentials again when logging in to Hyperion applications. For information about configuring the element in the XML configuration file, see “Configuring for SiteMinder Single Sign-On” on page 58. For a sample deployment scenario illustrating single sign-on with SiteMinder, see “Scenario 11: Single Sign-on with SiteMinder” on page 67.

Prerequisites The following steps are required before implementing external authentication and single sign- on with Hyperion applications. 4 Decide how you will implement the security platform: from an application, or from an application server. 5 Decide which of the supported authentication providers, on which platforms, to make available in the security realm. See Table 6. Table 6 Supported Authentication Providers and Platforms

Lightweight Directory Microsoft Active Access Protocol (LDAP) NT LAN Manager (NTLM) Directory

Windows NT 4.0 X X X

Windows 2000 X X X

Windows XP X X X

UNIX X X - requires installation of X NTLM Remote Server

Note: iPlanet 4.15 and Novell eDirectory 8.7 are the tested and supported LDAP servers. iPlanet is now known as Sun[tm] Open Net Environment (Sun ONE).

6 If you are implementing security using an NTLM provider and are using a UNIX system as the client application machine, ensure that the NTLM remote server is installed on a Windows NT or Windows 2000 server. Install the NTLM remote server from the Hyperion application’s installation software.

Setting Up the Environment for NT LAN Manager Support The directions in this chapter apply to administrators who want to enable one or more Hyperion applications to use external authentication of users in a Windows NT LAN Manager (NTLM) domain. This section contains the following topic:

44 Using Security ● “Setting Up User Rights for NT LAN Manager” on page 45

● “UNIX Application Support for NT LAN Manager” on page 46

Setting Up User Rights for NT LAN Manager To enable use of the NTLM provider, certain access rights are required of the Windows NT user account on which the application or application server runs.

Note: Make sure you set up these rights on the machine on which the application runs, rather than on the NT domain machine.

Additionally, certain access rights are required for end users. The following access rights are required for external authentication to work with an NTLM provider:

❍ “Access this computer from the network” (usually granted to Administrators). End users of Hyperion applications using external authentication require this right.

❍ “Act as part of the operating system” (normally not granted to anyone). The account used to run Hyperion application processes requires this right in order for external authentication to work.

❍ The logged on user should be a domain user. The user running the application or application server of the Hyperion product should be a domain user rather than a local Windows user. See “Setting Up User Rights on Windows NT” on page 45 or “Setting Up User Rights on Windows 2000” on page 46, depending on which operating system you use.

Setting Up User Rights on Windows NT 7 From the Start Menu, select Programs > Administrative Tools (Common) > User Manager. 8 In the User Manager dialog box, select the appropriate user name. 9 Select Policies > User Rights. The User Rights Policy dialog box is displayed. 10 From the Right drop-down list box, select Access this computer from network. The users or groups who have the selected policy setting are shown in the “Grant To” list box. If the appropriate user is shown in this list box, click “Cancel” and skip to step 12. 11 To grant the selected right, click Add, and complete the Add Users and Groups dialog box. 12 In the User Rights Policy dialog box, check Show Advanced User Rights. 13 From the Right drop-down list box, select Act as part of the operating system. The users or groups who have the selected policy setting are shown in the “Grant To” list box. If the appropriate user is shown in the “Grant To” list box, click “Cancel” and skip the rest of this procedure. 14 To grant the selected right, click Add, and complete the Add Users and Groups dialog box.

Using Single Sign-on 45 Setting Up User Rights on Windows 2000 15 From the Start Menu, select Settings > Control Panel > Administrative Tools > Local Security Policy. This opens the “Local Security Settings” dialog box. 16 In the left-pane tree of the Local Security Settings dialog box, expand the folder named Local Policies. 17 Click the folder named User Rights Assignment, and, in the right area of the dialog box, double-click the policy named Access this computer from the network. The “Local Security Policy Setting” dialog box for the “Access this computer from the network” policy is displayed. 18 If the relevant user account has the policy checked, click Cancel and skip to step 23. 19 Click Add. 20 Select the name of the appropriate user or group needing the right. 21 Click Add. 22 Click OK. 23 In the right pane of the dialog box, double-click the policy named Act as part of the operating system. The “Local Security Policy Setting” dialog box for the “Act as part of the operating system” policy is displayed. 24 If the relevant user account has the policy checked, click Cancel and skip the rest of this procedure. 25 Click Add. 26 Select the name of the appropriate user or group needing the right. 27 Click Add. 28 Click OK.

UNIX Application Support for NT LAN Manager If you are implementing external authentication with an NTLM provider and wish to support the use of a UNIX machine for the client application, you must also ensure that the Hyperion NTLM Remote Server is installed on a Windows NT/2000 server.

➤ To provide support for NTLM authentication for a UNIX client application: 1 On the Windows NT/2000 server, install the Hyperion NTLM Remote Server. The installation program, setup.exe, is provided with the installation software for your Hyperion application. Run setup.exe. 2 Accept the license agreement and click Next. 3 On the Welcome page, click Next. 4 Choose a destination location for the NTLM Remote Server, and click Next. 5 Enter the host name and port number for the machine hosting the NTLM Remote Server, and click Next. 6 If you will be using Secure Sockets Layer with your NTLM deployment, select the option to support SSL and click Next.

46 Using Security For configuration information, see “Optional Configuration for NTLM” on page 57. 7 In the Start Copying Files dialog box, click Next to begin the installation. 8 Click Finish to complete the installation. 9 Run the remote server by choosing Start > Programs > Hyperion Solutions > NTLM Remote Server > Run NTLM Remote Server. 10 On the UNIX machine that hosts the application, ensure that the machine is configured as shown in Scenario 3 in the deployment scenarios section. 11 On the UNIX machine that hosts the application, modify the values in the tags in the section of WAACss.xml to tell the application where to find the remote NTLM server. For more information, see “Optional Configuration for NTLM” on page 57.

Configuration for External Authentication This section explains to administrators how to configure applications to support authentication of users that are stored in LDAP, Active Directory, or Windows NT LAN Manager (NTLM) external-authentication providers. Configuration also applies to supporting single sign-on, the ability of a user to access multiple Hyperion applications after logging on only once using external credentials. This section contains the following topics:

● “How Configuration Works” on page 47

● “Configuring the Preferred Logging Priority” on page 48

● “Configuring the Provider Search Order” on page 49

● “Configuring Token Timeout” on page 50

● “Configuring an LDAP or Active Directory Provider” on page 50

● “Configuring an NTLM Provider” on page 56

How Configuration Works Basic configuration is handled by means of editing property values in the WAACss.xml file. Property values must be configured to suit your application and provider scenarios. The properties are presented in the form of:

● XML tags representing property types

● Modifiable values of the XML tags, representing the values for each property

For each supported authentication scenario, there is a set of properties to add or edit in the sample.xml file, depending on the deployment scenario. To enable single sign-on in cases where one Hyperion product launches another, you must use a single XML configuration file that is shared by both product installations.

Using Single Sign-on 47 Note: Familiarize yourself with the contents of the WAACss.xml file by examining it in the Administration Tools or an XML-supporting browser, such as Internet Explorer version 5 or higher, that provides color-coding and the ability to expand and collapse sections. In Internet Explorer, the sections to modify appear dark and bold. The bold areas are the contents of the tags. For example, content. The actual tags, which you should not modify, appear lighter and are enclosed within angle brackets.

The WAACss.xml file contains the minimum set of properties that must be configured for your application and provider scenario.

Configuring the Preferred Logging Priority The following configuration requirement applies to LDAP, Active Directory, and NTLM providers. For additional requirements specific to either provider, see “Configuring an LDAP or Active Directory Provider” on page 50 or “Configuring an NTLM Provider” on page 56.

➤ To configure the error level setting for applications supporting external authentication and single sign-on: 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 Locate the section of WAACss.xml, which looks like the following but may have different values: DEBUG

3 Change the error-reporting value from DEBUG to the level of authentication-related error messages that you want the application to log. If the entire section, including the tags, is deleted, the default value of DEBUG is used. Do not delete only the values inside the tags. In the following list of valid values, each level is inclusive of the levels below it: DEBUG, which includes extensive information useful for debugging INFO, which includes information on the status of operations and requests WARN, which includes cautionary information, if relevant, for some operations and requests ERROR, which includes only statements pertaining to failed operations and requests FATAL, which includes only information about errors that result in a disconnection 4 Save the WAACss.xml file.

48 Using Security Configuring the Provider Search Order The search order provides the external authentication mechanism with the ability to access multiple providers in a sequential manner. Search order must be defined even if there is only a single authentication provider; in this case, the search order property has a single entry.

➤ To define the provider search order: 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 Locate the section of sample.xml, which looks like the following but may have different values: ntlmServer ldapServer msadServer

The type attribute for each section specifies a type of authentication repository: ntlm for Windows NT LAN Manager, ldap for a Lightweight Directory Access Protocol directory, or msad for Microsoft Active Directory. The value for each section is where you specify the name of each provider’s configuration. For example, you might replace the sample value ntlmServer with domain1 if your NT LAN Manager domain is called domain1. This name does not have to match the actual server name of the provider, but it does have to match the name of the provider’s configuration in the rest of the XML file. For example, if you change ntlmServer to domain1 in the search order section, you must also use domain1 as the value of the name attribute for the tag. 3 Move the sections around as needed to place the provider types in the order that they should be searched whenever a user tries to log on to a Hyperion application. It would make sense to place the provider containing the most users of Hyperion applications first in the search order, if that information is known. For example, in the following section, the NTLM provider would be searched first for user information. ntlmServer ldapServer msadServer

You may add or remove providers as needed. For example, you might add an ldapServer2 section if you have a second LDAP provider named ldapServer2. 4 If you are using an LDAP provider, between the appropriate tags, replace ldapServer with the desired name to represent the configuration for the LDAP server.

Using Single Sign-on 49 The name must be the same as the name you specify in the LDAP provider section, in step 3 on page 51. 5 If you are using an NT LAN Manager provider, between the appropriate tags, replace ntlmServer with the desired name to represent the configuration for the NTLM provider. The name must be the same as the name that you specify in the NTLM provider section, in step 3 on page 56. 6 Save the WAACss.xml file.

Configuring Token Timeout When an externally authenticated user logs in to a Hyperion application, a token is generated to contain the login credentials. You can configure the token to expire after a specified number of minutes, instead of the default of 480 minutes.

➤ To define the length of time a token is valid: 1 In a text editor, open WAACss.xml. 2 Locate the section of WAACss.xml, which looks like the following but may have different values: 60

3 Between the tags, enter the number of minutes that should pass in before a user is required to authenticate again. The default length of a token is 480 minutes (8 hours). In other words, if the element and all its contents are removed from the configuration file, the security platform will assign a default token timeout of 8 hours. 4 Save the.xml configuration file.

Configuring an LDAP or Active Directory Provider The instructions of this topic show how to modify the properties that apply to configuring the provider implementations for Lightweight Directory Access Protocol (LDAP). Use these instructions if your application supports an LDAP or Microsoft Active Directory provider.

Note: These instructions assume that you have already completed the generic configuration steps described in “Configuring the Preferred Logging Priority” on page 48 and “Configuring the Provider Search Order” on page 49.

This topic contains the following sections:

● “Basic Configuration for LDAP or Active Directory” on page 51

● “Optional Configuration for LDAP or Active Directory” on page 52

50 Using Security Basic Configuration for LDAP or Active Directory

➤ To complete basic configuration for LDAP: 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 If you are configuring for an LDAP directory such as iPlanet or Novell LDAP server, locate the section of WAACss.xml including and between the tags and . For example, true ldap://host:portNo/DIT cn=User Name userPassword ou=People ou=Groups

If you are configuring for Microsoft Active Directory, locate the section including and between the tags instead, and then configure the properties the same way as for iPlanet or Novell LDAP. 3 In the first line of the above section, change ldapServer or msadServer to the name you want to use to indicate the configuration for this LDAP or Microsoft Active Directory provider. The name must be the same as the name that you specified in the search order section, in step 4 on page 49. 4 Between the tags, leave the default value of true, or, if the specified provider is not a trusted LDAP or Active Directory provider, replace the value with false. If the entire section including the tags is deleted, the default value of true is used.

Tip: Do not delete only the values of the tags.

If the trust setting is true, a password is not present or required in the token generated upon user authentication. If the trust setting is false, a password is part of the token. 5 Between the tags, replace ldap://host:portNo/DIT with the URL that specifies the location of the LDAP or Active Directory provider. You must include the domainComponent attributes (DCs) in the URL.

Using Single Sign-on 51 The following is an example of a URL that includes a directory information tree (DIT): ldap://ldap_server:389/DC=company,DC=com

Note: Be sure to include no extra spaces in the URL.

6 Between the and tags, modify the sample values, cn=User Name and userPassword, with information from a user account that has read-only access to the directory stores. If you want to provide anonymous access, delete the entire and sections. Delete the tags and the values; do not delete only the values. 7 Between the tags for user, replace ou=People with the information that indicates the branch in the directory server that contains user entries. The user-URL property is relative to the URL specified for the LDAP or Active Directory provider. If you want the provider to search the whole directory specified by URL in the provider section, delete the entire section that is in the section. Do not leave the tags empty, without a value. For example, if users on the LDAP or Active Directory provider are stored in an organizational unit directory named People, the following sample is correct: ou=People

8 Between the tags for group, replace ou=Groups with the information that indicates the branch in the directory server that contains group entries. The group-URL property is relative to the URL specified in the provider section. If you want the provider to search the whole directory specified by the URL in the provider section, delete the entire section that is in the section. Do not leave the tags empty, without a value. For example, if groups for the LDAP or Active Directory provider are stored in an organizational unit directory named Groups, the following sample is correct: ou=Groups

9 Save the WAACss.xml file.

Optional Configuration for LDAP or Active Directory The following XML elements represent the complete configuration that can be specified for LDAP or Active Directory (MSAD). true ldap://host:portNo/DIT cn=User Name

52 Using Security userPassword simple ssl 200 dn ou=people uid givenname sn mail person organizationalPerson inetOrgPerson ou=Groups cn groupofuniquenames?uniquemember groupOfNames?member

➤ To complete optional configuration for LDAP or Active Directory: 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 Between the tags in the section for the LDAP or Active Directory provider, replace the sample value with the desired maximum number of entries that can be returned in a query. If the tags and their sample value are deleted from WAACss.xml, the default value is 100. To allow return of the entire set of entries fetched by a search query, you can set the value to 0 to indicate an unlimited allowed result size. This may not be advisable, because on very large query results, it might consume too much memory. 3 Between the tags, indicate the value that corresponds to any additional security protocol you are using for secure data transmission to and from the authentication provider. The only valid value for the tags in this release is ssl. If you are not using Secure Sockets Layer, delete the tags, and their sample value, from WAACss.xml. If you are using Secure Sockets Layer (SSL), also complete the following tasks:

❍ On the directory server, ensure that a certificate is installed and available.

Using Single Sign-on 53 ❍ On the Java Virtual Machine that runs your application, create a certificate database if one does not exist.

❍ On the Java Virtual Machine that runs your application, trust the Certificate Authority (CA) that issues the server certificate. The security platform uses the LDAP service provider from SUN to authenticate users stored externally in an LDAP-compatible directory such as Novell eDirectory, SunTM Open Net Environment (Sun ONE) (formerly iPlanet), or Microsoft Active Directory. The LDAP service provider runs on the Java Virtual Machine for your application. When SSL is used as the secure medium to connect to the directory server, the LDAP service provider of the security platform uses Java Secure Socket Extension (JSSE) software for its SSL support. For more information about setting up SSL, please see the documentation for your directory server and/or JRE. 4 Between the tags, modify the sample value to match an attribute in the directory that uniquely identifies entries. The attribute may be the DN, or a customized attribute such as employee_id, or any other attribute commonly used in the directory nodes of users and groups. If the section is deleted, the default value is dn. 5 Between the tags within the section, modify the sample value to match an attribute in the directory that uniquely identifies user entries. The attribute may be part of the DN, such as cn or uid, or a customized attribute, such as employee_id, or any other attribute commonly used in the directory nodes of users. If the section is deleted, the default value is cn. The following sample configuration states that the user names in which we are interested are using the “common name” attribute: cn

The sample above is correct if it is true that all user names are identified by cn = UserName, as is Autumn Smith in the following LDAP browser view of a corporate directory store:

The above example highlights a subset of the DN. However, the loginAttribute property can instead refer to an attribute under the directory node for the user; for example, loginAttribute can point to uid, as shown in the following entry detail:

54 Using Security 6 Between the tags within the section, replace the sample value to match the attribute associated with first-name entries in the directory. If the tags and their contents are deleted, the default value for the first-name attribute is givenname. 7 Between the tags within the section, replace the sample value to match the attribute associated with last-name entries in the LDAP directory. If the tags and their contents are deleted, the default value for the last-name attribute is sn. 8 Between the tags within the section, replace the sample value to match the name of the attribute that is actually mapped to e-mail addresses stored in your corporate directory. If the tags and their contents are deleted, the default value is mail. 9 In the section within the section, you may add tags and values if your corporate directory schema requires specialized object classes to describe users, and those object classes are not present in the existing entries. The provided (default) user object classes for LDAP are person, organizationalPerson, and inetOrgPerson. The provided (default) user object classes for Active Directory are person, organizationalPerson, and user. 10 Between the tags within the section, replace the sample value of cn to point to an attribute in the corporate directory through which a group entry can be discovered. The default value is cn if the section is deleted. The following sample states that the group names containing the relevant user entries are using the Common Name attribute: cn

11 In the section within the section, you may add tags and values if your corporate directory schema requires specialized object classes to describe groups, and those object classes are not present in the existing entries. The provided (default) group object classes for LDAP are groupofuniquenames?uniquemember and groupOfNames?member. The provided (default) group object class for Active Directory is group?member. For additional entries you make, the tag values must be of the format ObjectClassName?AttributeName For example: group?member where group is the name of the objectClass and member is the attribute that holds the distinguished Name of the member of this group. 12 Save the WAACss.xml file.

Using Single Sign-on 55 13 If your corporate information is protected by a security agent such as SiteMinder, see “Configuring for SiteMinder Single Sign-On” on page 58

Configuring an NTLM Provider The instructions in this section show how to modify the properties that apply to configuring the provider implementations for Windows NT LAN Manager (NTLM), if your application supports an NTLM provider. This section contains the following topics:

● “Basic Configuration for NTLM” on page 56

● “Optional Configuration for NTLM” on page 57

Basic Configuration for NTLM

➤ To complete basic configuration for NTLM, 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 Locate the following section of WAACss.xml (or, the entire section including and between the tags and : false THIS_IS_DOMAIN_NAME

3 In the first line of the above section, change ntlmServer to the desired name to indicate the configuration for this NTLM provider. The name must be the same as the name you specified in the search order section, in step 5 on page 50. 4 Between the tags, leave the default value of true, or replace the value with false if this is not a trusted NTLM provider.

❍ If the trust setting is true, a password is not present or required in the token generated upon user authentication. The user still must log in with a user name and password, but the password is not stored in the token.

❍ If the trust setting is false, a password is part of the token, and this is required for this NTLM provider. 5 Between the tags, replace THIS_IS_DOMAIN_NAME with the correct name of the Windows domain.

56 Using Security If a domain is specified, then the NTLM provider is responsible for performing operations on that domain. Alternatively, if the domain element is left empty ( for example, ), then the NTLM provider performs operations on all the trusted domains. 6 Save the WAACss.xml file.

Optional Configuration for NTLM The following XML elements represent the complete configuration that can be specified for NT LAN Manager. The bold elements are the optional configuration parameters explained in this section. The other parameters are explained in “Basic Configuration for NTLM” on page 56. false DOMAIN_NAME 300 //host:1099/NTLMImpl

➤ To complete optional configuration for NTLM, 1 In a text editor, open WAACss.xml.

Tip: You can also use the Administration Tools to update the WAACss.xml file.

2 Between the tags in the section for the NTLM provider, replace the sample value with the desired maximum number of entries that can be returned in a query. If the tags and their contents are deleted from WAACss.xml, the default value is 100 If the maxsize is set to zero, then no rows will be returned back to the application. 3 Between the tags that are within the tags:

❍ If you support Hyperion applications only on Windows platforms, delete the content of these tags, as their configuration applies only to support for UNIX clients accessing information stored in an NTLM provider.

❍ If you support external authentication using NTLM for Hyperion applications that run on UNIX, replace the sample content of the tags with the correct URL of the remote NTLM Provider. You must have installed the NTLM Remote Server as indicated in UNIX Application support for NT LAN Manager on page 17. 4 Save the WAACss.xml file.

Using Single Sign-on 57 5 If your corporate information is protected by a security agent such as SiteMinder, see “Configuring for SiteMinder Single Sign-On” on page 58.

Configuring for SiteMinder Single Sign-On

➤ If your corporate information is protected by a security agent such as SiteMinder and you want to enable single sign-on to web-based Hyperion applications through SiteMinder, 1 In a text editor, open sample.xml. 2 Add the following information (indicated by bold) to the end of the configuration file, after the section but before the line containing : FATAL

Note: The security agent configuration is applicable only to web-based Hyperion applications.

3 Save the sample.xml file. 4 Additionally, the SiteMinder administrator must set up protection for the appropriate Hyperion application's web resources. These resources could be HTML files, JSP files, ASP files, or other web-based resource files. To do this, the SiteMinder administrator needs to configure a "response" that would enable a HTTP header to be added by SiteMinder. This HTTP header carries the login name of the user and makes the login name available to the web resources (the Hyperion application's resources, in this case). The header must be configured in the response to have the name HYPLOGIN, and the value should be configured to be the login name of the authenticated user. For example, if you are using an LDAP directory and cn is the login name attribute configured in the security platform XML configuration file, then the HYPLOGIN header should carry the cn value corresponding to the authenticated user in the LDAP directory. The administrator can configure the header to SM_USERLOGINNAME, an attribute that holds the user ID as specified by the user in the login attempt. For more details, please refer to the "Responses and Response Groups" section of the Netegrity Policy Design Guide.

Sample Deployment Scenarios This section contains the following deployment scenarios as examples:

● “Scenario 1: Single LDAP Directory” on page 59

● “Scenario 2: Single Microsoft Active Directory” on page 60

● “Scenario 3: UNIX Application and Single NTLM Domain” on page 61

● “Scenario 4: Windows Application and Single NTLM Domain” on page 61

58 Using Security ● “Scenario 5: UNIX Application Against LDAP, Microsoft Active Directory, and NTLM” on page 62

● “Scenario 6: Windows Application Against LDAP, Microsoft Active Directory, and NTLM” on page 63

● “Scenario 7: Multiple Microsoft Active Directory Instances” on page 64

● “Scenario 8: Multiple LDAP Directory Instances” on page 65

● “Scenario 9: Multiple NTLM Domains with Trust Relationships” on page 65

● “Scenario 10: Multiple NTLM Domains Connected with Hyperion Remote Authentication Module” on page 66

● “Scenario 11: Single Sign-on with SiteMinder” on page 67

● “Deployment References from LDAP Product Vendors” on page 68

Scenario 1: Single LDAP Directory Figure 12 illustrates a deployment scenario that uses LDAP.

Figure 12 Authentication Against a Single Instance of an LDAP Directory

The configuration file resides on the application server, as do the Hyperion application binaries. The configuration for external authentication should be done as described in the rest of this document. The application server can be on UNIX, Windows NT 4.0 server, or Windows 2000 server. The directory server can be on UNIX, Windows NT 4.0 server, or Windows 2000 server. A secure SSL connection can optionally be used. The directory server and the application server can be combined into one server. In such a scenario, the application binaries and the directory server binaries reside on the same server. In the single LDAP directory scenario,

● all users must have the same prefix, such as cn or uid.

● all groups must have the same prefix, such as cn or ou.

● referrals are not supported.

● users and groups should exist under nodes, such as ou=People and ou=Groups, for optimal data-retrieval performance.

Configuring for SiteMinder Single Sign-On 59 A sample corporate directory schema follows:

Scenario 2: Single Microsoft Active Directory Figure 13 illustrates a deployment scenario that uses Microsoft Active Directory.

Figure 13 Authentication Against a Single Instance of Microsoft Active Directory

The configuration file resides in the application server, as do the Hyperion application binaries. The configuration for external authentication should be done as described in the rest of this document. The application server can be on UNIX, Windows NT 4.0 server, or Windows 2000 server. The directory server must be on a Windows 2000 server, because Microsoft Active Directory is a Windows 2000 implementation. A secure SSL connection can optionally be used. The directory server and the application server can be combined into one server. In this scenario the application binaries and the directory server binaries reside on the same server. In the single Microsoft Active Directory scenario,

● all users must have the same prefix, such as cn or uid.

● all groups must have the same prefix, such as cn or ou.

● referrals are not supported.

● users and groups should exist under nodes, such as cn=Users, for optimal data-retrieval performance. A sample corporate directory schema follows:

60 Using Security Scenario 3: UNIX Application and Single NTLM Domain Figure 14 illustrates a deployment scenario in which a UNIX-based application accesses information from a Windows NT LAN Manager domain controller. This implementation depends also on the Hyperion Remote Authentication Module, which must be configured and running on a Windows NT or 2000 machine. The Remote Authentication Module can be installed from the Hyperion Download Center. The Remote Authentication Module is needed because the external authentication mechanism depends on the NTLM support library file (.dll) for NTLM authentication, and dlls are not supported on UNIX.

Figure 14 Authentication from a UNIX-Based Application Server Against a Single Instance of NTLM

Note: The Hyperion Remote Authentication Module enables communication between NTLM and a UNIX-based application. Install the Remote Authentication Module from the Hyperion Download Center.

The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file (.dll) file is also required, for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM server can be on a Windows NT 4.0 server or a Windows 2000 server. The Hyperion Remote Authentication Module should be on Windows NT 4.0 server or Windows 2000 server. Combining the Remote Authentication Module with the NTLM Primary Domain Controller is not recommended. The Remote Authentication Module machine needs to be in the same domain as the NTLM Primary Domain Controller

Scenario 4: Windows Application and Single NTLM Domain Figure 15 illustrates a deployment scenario in which a Windows-based application accesses information from a Windows NT LAN Manager domain controller.

Configuring for SiteMinder Single Sign-On 61 Figure 15 Authentication from a Windows-Based Application Server Against a Single Instance of NTLM

The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file,cssNTLM.dll,is also required for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM Primary Domain Controller can be on a Windows NT 4.0 server or a Windows 2000 server.

Scenario 5: UNIX Application Against LDAP, Microsoft Active Directory, and NTLM Figure 16 illustrates a deployment scenario in which a UNIX-based application accesses information from multiple directory stores. The Hyperion Remote Authentication Module is required for access to the Windows NT LAN Manager domain, as in Scenario 3. Configuration of the search order becomes important in this scenario.

Figure 16 Authentication from a UNIX-Based Application Server Against an LDAP Directory, Microsoft Active Directory, and NTLM

62 Using Security Note: The Hyperion Remote Authentication Module enables communication between NTLM and a UNIX-based application. Install the Remote Authentication Module from the Hyperion Download Center.

The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file, cssNTLM.dll, is also required for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM Primary Domain Controller server can be on a Windows NT 4.0 Server or a Windows 2000 server. The Remote Authentication Module machine needs to be in the same domain as the NTLM Primary Domain Controller. For LDAP-compatible directories, a secure SSL connection can optionally be used. The configuration of the search order property in the WAACss.xml configuration file determines the order in which each directory store receives requests for information from the application. For example, the first instance of a requested user found while going through the search order is the instance that is used to retrieve and return information about the user to the application. Therefore, although there are three directories that can host user information, it is recommended that user information not be duplicated across the directories. Duplication can lead to the incorrect user object being authenticated. For information about configuring the search order, see “Configuring the Provider Search Order” on page 49.

Scenario 6: Windows Application Against LDAP, Microsoft Active Directory, and NTLM Figure 17 illustrates a deployment scenario in which a Windows-based application accesses information from multiple directory stores.

Figure 17 Authentication from a Windows-Based Application Server Against an LDAP Directory, Microsoft Active Directory, and NTLM

Configuring for SiteMinder Single Sign-On 63 The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file, cssNTLM.dll, is also required for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM Primary Domain Controller can be on a Windows NT 4.0 server or a Windows 2000 server. For LDAP-compatible directories, a secure SSL connection can optionally be used. The configuration of the search order property in the XML configuration file determines the order in which each directory store receives requests for information from the application. For example, the first instance of a requested user found while going through the search order is the instance that is used by the external authentication mechanism to retrieve and return information about the user to the application. Therefore, although there are three directories that can host user information, it is recommended that user information not be duplicated across the directories. Duplication can lead to the incorrect user object being authenticated. For information about configuring the search order, see “Configuring the Provider Search Order” on page 49.

Scenario 7: Multiple Microsoft Active Directory Instances When there are multiple Microsoft Active Directory instances which hold user authentication information, you must create a single instance of Active Directory which hosts all the user information. Enabling a single instance to use for external authentication is left to the individual installation. One solution is to enable replication between the instances to the master directory server, as shown in Figure 18.

Figure 18 Authentication with Multiple Microsoft Active Directory Instances

The configuration file resides on the application server, as do the Hyperion application binaries. The configuration for external authentication should be done as described in the rest of this document. A secure SSL connection can optionally be used.

64 Using Security Scenario 8: Multiple LDAP Directory Instances When there are multiple LDAP directory instances which hold user authentication information, you must create a single instance of LDAP which hosts all the user information. Enabling a single instance to use for external authentication is left to the individual installation. One solution is to enable replication between the instances to the master directory server, as shown in Figure 19.

Figure 19 Authentication with Multiple LDAP Directory Instances

The configuration file resides on the application server, as do the Hyperion application binaries. The configuration for external authentication should be done as described in the rest of this document.

Scenario 9: Multiple NTLM Domains with Trust Relationships When there are multiple Windows NT LAN Manager domains which hold user authentication information, one solution is to establish trust relationships between the domains, as shown in Figure 20.

Scenario 9: Multiple NTLM Domains with Trust Relationships 65 Figure 20 Authentication with Multiple Trusted NTLM Domains

The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file, cssNTLM.dll, is also required, for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM Primary Domain Controllers can be on Windows NT 4.0 servers or Windows 2000 servers.

Scenario 10: Multiple NTLM Domains Connected with Hyperion Remote Authentication Module When there are multiple Windows NT LAN Manager domains which hold user authentication information, an additional solution is to link the domains using the Hyperion Remote Authentication Module (compare to “Scenario 9: Multiple NTLM Domains with Trust Relationships” on page 65). This scenario eliminates the necessity of establishing trust relationships between the domains, as shown in Figure 21.

Figure 21 Authentication with Multiple Entrusted NTLM Domains

66 Using Security The Hyperion Remote Authentication Module gives users of Hyperion applications on Windows the ability to log in using multiple domains, without the need for the administrator to create trust relationships between the domains. In the figure above, Windows users may optionally log in using domain "D2" in addition to the more commonly used domain "D1," because the Hyperion Remote Authentication Module is running, giving access to domain "D2." Note that D1 does not trust D2. The configuration file resides on the application server, as do the Hyperion application binaries. The NTLM support library file (.dll) file is also required, for the NTLM connectivity. The configuration for external authentication should be done as described in the rest of this document. The NTLM Primary Domain Controllers can be on Windows NT 4.0 servers or Windows 2000 servers.

Scenario 11: Single Sign-on with SiteMinder SiteMinder is a Web Access Management Solutions provider sometimes employed by companies to manage and enforce authentication, authorization, and single sign-on for company Web resources. The Hyperion security platform enables single sign-on for a user into a web-based Hyperion application without challenging the user for credentials, as long as SiteMinder has already authenticated the user. Integration with SiteMinder requires configuration of the element in the XML configuration file. Figure 22 illustrates a scenario enabling single sign-on with SiteMinder and a Hyperion application using the Hyperion security platform:

Figure 22 Single Sign-on with SiteMinder as the Security Agent

The Hyperion application trusts the authentication and authorization information sent by SiteMinder with regards to the protected resources on the directory server. Therefore, the Hyperion security platform supports Tier 1 integration with SiteMinder.

Scenario 11: Single Sign-on with SiteMinder 67 The Web Agent is installed on a web server that intercepts requests for the Hyperion application's web resources, such as JSP files, ASP files, or HTML files on the application server. If these web resources are protected, the Web Agent issues a challenge for unauthenticated users. Once the user is authenticated, the policy server adds to the HTTP headers another header, named HYPLOGIN, whose value is the login name of the authenticated user. Thereafter, the HTTP request is passed on to the Hyperion application's web resources, and the login name is extracted from the headers. For more details on configuring the header HYPLOGIN and populating it, see “Configuring for SiteMinder Single Sign-On” on page 58.

Deployment References from LDAP Product Vendors iPlanet Directory Deployment Guide for v5.1: http://192.18.99.138/816-5609-10/816-5609-10.pdf iPlanet Directory Deployment Guide for v4.16: http://192.18.99.138/816-6679-10/816-6679-10.pdf Active Directory Deployment Guide: http://www.microsoft.com/technet/treeview/default.asp?url=/technet/prod technol/windows2000serv/deploy/add.asp

Setting up Single Sign-On Authentication for Application Builder This section describes the steps necessary to implement authentication and single sign-on for Application Builder.

➤ To set up Application Builder authentication: 1 Edit the web.xml file, to enable SSO security. As a default, the web.xml contained in the hab- samples.war file is set for J2EE security:

● Remove the comments for the WAACssAuthenticationServlet to enable SSO security. The WAACssAuthenticationServlet emulates the J2EE application servers authentication. The following snippet shows the code to uncomment: WAACssAuthenticationServletFilter CSS Authentication Servlet Filter Servlet filter that simulates J2EE authentication against CSS com.hyperion.waa.web.core.WAACssAuthenticationServletFilter AuthMethod FORM Provides the authentication method RealmName

68 Using Security Hyperion Application Builder Provides the realm name FormLoginPage /jsp/waa/admin/core/ADMINLogonPage.jsp Provides the form login page for authorization FormErrorPage /jsp/waa/admin/core/ADMINLogonErrorPage.jsp Provides the form error page for authorization RoleNames HAB_Admin Provides a comma delimited list of role names that can access the resources being filtered CssConfigFileName /WAACss.xml Provides the CSS configuration filename for authorization SecurityProviderClassNames com.sun.crypto.provider.SunJCE A comma delimited list of class names of security providers to register (needed for WebLogic)

● Uncomment the entries for CSS authentication: WAACssAuthenticationServletFilter ADMINApplicationServlet WAACssAuthenticationServletFilter *.jsp WAACssAuthenticationServletFilter /j_security_check WAACssAuthenticationServletFilter WAARepositoryContentServlet WAACssAuthenticationServletFilter

Scenario 11: Single Sign-on with SiteMinder 69 ADMINInterOpServlet

● Comment the entry for CSS authentication: User's with administrator rights HAB_Admin HAB_Admin

● Comment the , and entries for CSS authentication: Admin Application Protect all accessible servlets /ADMINApplicationServlet *.jsp Authorize known roles HAB_Admin FORM Hyperion Application Builder /jsp/waa/admin/core/ADMINLogonPage.jsp /jsp/waa/admin/core/ADMINLogonErrorPage.jsp Users with limited rights HAB_User Users with administrator rights HAB_Admin Users with read-write data access rights HAB_Analyst Users with read-only data access rights HAB_Viewer

2 Open the Administration Tools to edit WAACss.xml to point to the NTLM service.

● The following snippet shows the edited code:

70 Using Security false ldap:///dc=hyperion, dc=com simple dn ou=people uid givenname sn mail person organizationalPerson inetOrgPerson ou=Groups cn groupofuniquenames?uniquemember groupOfNames?member sf2 480 DEBUG

3 Stop and restart your Web application server. 4 To log on to the Sample Application, type the following URL in your Web browser: http://hostname:port/hab-samples/SMPApplicationServlet where hostname is the computer name, and port is the IP address for the Web application server.

Note: If you deployed Application Builder on your local computer, the hostname is localhost. If you are using Tomcat, the port is 8080.

Scenario 11: Single Sign-on with SiteMinder 71 72 Using Security Chapter Edit Member Tool 3

The Edit Member tool enables you to add, delete, and modify the members of a dimension from your browser, then save your selections in the OLAP data source. The procedures for managing dimension members can be found in the following topics:

● Accessing the Edit Member Tool

● Managing Dimension Members

Accessing the Edit Member Tool You access the Edit Member tool from the Application Builder Administration Tools home page.

➤ To access the Edit Member Tool: 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 Click Edit Member. The Edit Member data source selection page is displayed. 4 Drill down in the tree to select a data source, click OK. The Edit Members page is displayed. From this point, you can access the members of any dimension in the cube through the selected data source.

Managing Dimension Members The Administration Tools provide the capability for the administrator of an OLAP cube to add, delete, or modify the dimension of a cube down to the member level. The procedures for managing members can be found in the following topics:

● Configuring the Edit Members Tree

● Arranging the Member Order

● Editing Member Properties

● Deleting Members from a Dimension

Edit Member Tool 73 Configuring the Edit Members Tree You can determine the properties to display as columns in the dimension table by performing the following procedure.

➤ To modify the properties displayed in the dimension table:

Note: The changes made to the dimension table apply only to the dimension selected. Each dimension can have different column settings. The properties list varies from one dimension to another.

1 On the Edit Members page, click the Show Properties button, in the toolbar. The dimension properties list is displayed. 2 Perform one of the following:

● Select an unchecked property to add the column to the table.

● Select a checked property to remove the column from the table. 3 Repeat step 2 until only the desired columns are displayed. 4 Click Save to retain the changes.

The dimension properties table displays the choices you made.

Arranging the Member Order Members can be arranged in a particular order by performing the following procedure.

➤ To change the order in which members appear in the member list: 1 Select a member to move. 2 Perform one of the following:

● Click the Move Selected Up button to move the selected member up in the list.

● Click the Move Selected Down button to move the selected member down in the list. 3 Repeat steps 1 and 2 until the member order arrangement is complete. 4 Click Save to save all changes.

Editing Member Properties Adding or editing members is accomplished by accessing the Edit Member Properties page. You can arrange members by clicking on one of the following toolbar buttons.

● Edit Member - provides access to existing members for editing.

● Add Child Member - adds a child member to an existing member.

74 Edit Member Tool ● Add Sibling Above - adds a new child member above an existing member of a dimension.

● Add Sibling Below - adds a new child member below an existing member of a dimension.

In this way, you can maintain the structure of the member hierarchy within the dimension of a cube.

➤ To add or edit a member using the Edit Member tool: 1 On the Edit Members page, select a dimension from the Dimension list. The existing members of the dimension are displayed in the member table. 2 Perform one of the following:

❍ Select an existing member to modify and click Edit.

❍ Click Add Child Member to add a child member to the selected member.

❍ Click Add Sibling Member Above to add a member above the selected member.

❍ Click Add Sibling Member Below to add a member below the selected member. The Edit Member Properties page is displayed.

Note: There are required properties that must be defined for the member. They are identified by the icon. Both the required and optional properties differ from one dimension to another.

3 Enter the member property values as required. 4 When you complete entering values, click OK. The Edit Members page is displayed with the member list. 5 Click Save to save changes to the cube.

Deleting Members from a Dimension The Administration Tool provides access for administrators to manage dimensions and members without having to launch the OLAP administration tools. Members can be deleted from the dimension by the following procedure.

➤ To delete members from the dimension: 1 Select a dimension from the Dimension list. 2 On the Edit Members page, choose a member from the available members for the selected dimension. 3 Click Delete. The Delete confirmation dialog is displayed. 4 Click OK to delete the member. The member list on the Edit Members page is displayed again. 5 Click Save to save changes to the cube.

Managing Dimension Members 75 76 Edit Member Tool Chapter Repository Objects Tool 4

The Repository Objects Tool enables you to manage OLAP views and relational queries, as well as the folders that contain the other objects. From the Repository Objects Tool you can design views for your OLAP database and SQL queries for your relational database. You can also modify, delete and apply permissions to existing folders, data sources, views and queries. The procedures for managing repository objects are found in the following topics:

● “Accessing the Repository Objects Tool” on page 77

● “Managing Views” on page 78

● “Using and Scheduling Tasks” on page 201

Accessing the Repository Objects Tool You access the Repository Objects tool from the Application Builder Administration Tools home page.

➤ To access the Repository Objects Tool: 1 Open the Administration Tools in one of the following ways:

● Select Start > Programs > Hyperion Solutions > Application Builder > Launch Page, then click Administration Tools.

● Type the following URL in your Web browser: http://hostname:port/hab-admin/ADMINApplicationServlet

where hostname:port is the computer name or IP address and port of the Admin Tool. If you installed Application Builder on your computer, the hostname is localhost. If you are using Apache Tomcat, the port is 8080. 2 Click Repository Objects. The Select Repository Object page is displayed with the repository tree. 3 Select one of the two Load from radio buttons:

● Load from repository (default), continue with the section Using OLAP Views or “Using Relational Views.”

● Load from server, perform the remaining steps of the procedure. 4 Perform one of the following:

Repository Objects Tool 77 ● Locate a view or query by entering a file path in the provided text box and click Load.

● Click the Browse button to locate a view or query using the file explorer. 5 Click Edit. The Edit SQL Query or Edit View page is displayed, depending on the data source selected.

Managing Views View management provides the ability for users to store, edit and manage views for the cubes that the application uses to store data. Views can be stored in the repository or on the server. After the Select Repository Object tool is selected, you can select a view from either the repository or the server (Load from repository shown.) From the Select Repository Object page you can perform the following view management tasks:

● “Using OLAP Views” on page 78

● “Using Relational Views” on page 81

● “Creating Folders” on page 88

● “Deleting Views” on page 88

● “Running Views” on page 88

● “Setting Permissions” on page 89

In addition, there are also specific methods for performing tasks when creating or editing a view that are explained in the following section, “Creating or Editing Tasks” on page 81

Using OLAP Views Creating or editing an OLAP view consists of several procedures. The view is created to gain access to the data in the cube in an organized and efficient assembly of the extracted data. The following procedures will guide you through the process of creating or editing the view and exporting it to text format:

● Selecting the View and Data Source

● Selecting the Default Dimensions

● Data Filtering and Sorting

● Completing the Query Section

❍ Exporting the View to a Text File

Selecting the View and Data Source

➤ To select the view and data source of a cube: 1 On the Administration Tools home page, click Repository Objects.

78 Repository Objects Tool The Select Repository Object page is displayed. 2 Perform one of the following options:

❍ Click the radio button adjacent to an existing view and click Edit.

❍ Click Create and select an OLAP data source form the data source tree. The Edit View page is displayed. 3 Select an OLAP data source from the data source tree. 4 Click OK. The Edit View page is displayed with the Default section of the page expanded. 5 Modify the following sections of the Edit View page to meet your specific needs:

● Selecting the Default Dimensions

❍ Page - a selected location for dimensions.

❍ Row - a selected location for dimensions. (required)

❍ Column - a selected location for dimensions. (required)

● Data Filtering and Sorting

● Completing the Query Section

Selecting the Default Dimensions Performing this procedure places dimensions for editing in the next three sections of the Edit View Page. When you select a dimension for Page, Row, or Column, that section of the form expands to include the selected dimension in the form’s section for you to select members.

➤ To select default dimensions for the view: 1 Optional: Click the Lookup button to browse the Edit Member page to determine what dimensions and members are available. 2 In the dimension list, click the radio button adjacent to the dimension. 3 Click either the Page, Column, or Row button to move the dimension to the corresponding section of the Edit View page. 4 In the Page, Row and Column sections you can perform any of the following actions to manage your dimensions:

● Click Move Dimension to Default to return a dimension to the default list.

● Click Move Dimension to Page to move a dimension from a row or column to the Page section.

● Click Move Dimension to Column to move a dimension from a page or row to the Column section.

● Click Move Dimension to Row to move a dimension from a page or column to the Row section.

● Click the Up/Down Arrows to move a dimension up or down in the dimension list.

Managing Views 79 5 When you are finished, click the minus sign adjacent to each of the Default, Page, Row, or Column sections that are expanded.

Data Filtering and Sorting Data filtering and sorting provides you with the capability of applying a property value filter or an ascending or descending sort of data. When the Data section plus sign is clicked the Data section of the Edit Query page is displayed. At this time, the data filtering and sorting options are not yet implemented.

Completing the Query Section

➤ To complete the query section of the Edit View page:

Note: The text box contains the view string that you have been building and should require no modification.

1 Click the plus sign, , next to SQL Query to expand the section. 2 Optional: From the Folder drop down list select a folder to store the SQL query. The default is . 3 In the Name text box type a name for the query. 4 In the Description text box type a description of the view. 5 Click Save. The view is saved to the repository. 6 Click Run. The Result screen is displayed. 7 When you are finished reviewing the results, click OK. The Edit View screen is displayed. 8 Click Cancel to return to the Select View page.

Selecting Guided Analysis For information on Guided Analysis, see “To enable Guided Analysis links in a relational view or Olap view:” on page 167.

Exporting the View to a Text File You can export a view to a text file by performing the following procedure.

➤ To export the view to text: 1 In the Edit View page, click Export to Text. The Export to text file page is displayed.

80 Repository Objects Tool 2 In the Export to text file page, perform one of the following:

● In the Name text box append the name of the file to the path displayed.

● In the Name text box enter a relative or absolute path and filename.

● Using the Lookup button locate a place to store and name the text file. 3 Enter a brief description. 4 Click OK. The file is exported to the specified location and the Edit View page is displayed. 5 Click Cancel to return to the Select View page.

Creating or Editing Tasks A task executes a piece of code that performs a specific functionality. You group tasks into a task definition to perform functions, such as sending e-mail, generating a report, or generating an alert based on a condition. An alert is a task definition that performs a notification. For information on tasks, see “Using the Task Registry” on page 225.

Using Relational Views SQL query views are created, managed and stored in the repository. Query views can be loaded from either the repository or from a server and then persisted to the repository. Use the following procedures to create your relational views:

● Navigating SQL Queries

● Creating or Editing SQL Queries

● Running Views

Navigating SQL Queries In addition to the navigation buttons discussed in the Navigating Application Builder Administration Tools section of this help system, there are additional SQL query navigation buttons that are used in the following procedures.

Note: The above options are only available when the applicable object is selected.

Creating or Editing SQL Queries Whether you are creating a new, or editing an existing SQL query views, the following procedures are the same. Some of the procedures are not required in order for a query to run. The procedures are as follows:

Note: The procedures that are required for the query to run without errors are indicated by an asterisk (*) after the topic.

Managing Views 81 ● Selecting Queries*

● Selecting Tables for the Query*

● Selecting Columns*

❍ Managing Advanced Columns

● Applying Filters to the Query

❍ Deleting Filters

● Applying a Group By

● Sorting Columns

● Completing the Relational View*

❍ Exporting the Query to a Text File

Selecting Queries

➤ To select a new or existing query: 1 On the Administration Tools home page, click Repository Objects. The Select Repository Object page is displayed. 2 Perform one of the following options:

● Click the radio button next to an existing SQL query and click Edit.

● Click the Create icon and select View. The Select Data Source page is displayed. 3 Select a relational data source from the data source tree. 4 Click OK. The Edit SQL Query page is displayed with the Select Tables section of the page expanded.

Selecting Tables for the Query When you are building a query against a relational database, you must start by selecting the tables the query will access data from. The first section of the form used to create a query on the Edit SQL Query page is the Select Tables section.

Note: Throughout these procedures, it is recommended that you use the plus sign (+) to expand sections to complete them, and click the minus sign (-) to collapse sections of the form.

➤ To select a table or tables for the SQL query: 1 In the Select tables section of the Edit SQL Query page, highlight the table in the Available Tables list. 2 Click Select Table. The table is added to the Selected Tables list. 3 Repeat steps 1 and 2 until all desired tables are selected.

82 Repository Objects Tool 4 Click the minus sign adjacent to Select Tables to collapse the form section. 5 Select columns for the query. For more information, see the section, “Selecting Columns.”

Selecting Columns After you select the tables for the query, you need to select the columns from the list of available columns. You can refer to the option buttons described in the table below:

Option Description

Select Columns: Moves the highlighted column to the Selected Columns list

Deselect Columns: Removes the highlighted column from the Selected Columns list to the Available Columns list

Select Columns Advanced: When a column in the Available Columns list is selected, this option provides the ability to apply a function to the column before selecting it

Select All Columns: Moves all available columns to the Selected Columns list

Deselect All Columns: Removes all of the columns from the Selected Columns list to the Available Columns list

Note: The above options are only available when the applicable object is selected.

➤ To select columns for a SQL query:

1 On the Edit SQL Query page, click the plus sign, , next to Select Columns to expand the section. 2 In the Select Columns section of the Edit SQL Query page, highlight the column in the Available Columns list. 3 Optional: Apply a function or expression to the column. For more information, see the section “Managing Advanced Columns.” 4 Click Select Column. The column is added to the Selected Columns list. 5 Repeat steps 1 and 2 until all desired columns are selected.

6 Click the minus sign, , adjacent to Select Columns to collapse the section. 7 Optional: Apply filters to the query. For more information, see the section “Applying Filters to the Query.”

Managing Views 83 Managing Advanced Columns You can apply functions or expressions to a column before adding the column to the query by performing the following procedure.

➤ To apply a function or enter an expression to the column of a SQL query: 1 On the Edit SQL Query page, select a table to add to the query. 2 Click the Advanced Columns button. The Select Columns Advanced page is displayed. 3 Select a function from the drop-down list of available functions:

❑ Avg

❑ Count

❑ Max

❑ Min

❑ Sum 4 In the Display As text box type a name. 5 Click the Enter an Expression radio button. The Expression section of the page is displayed. 6 Click inside the expression text box. Type an expression. 7 Select a table column name from the drop-down list. 8 In the Display As text box type a name for the expression. 9 When you are finished creating the function and/or expression, click OK. The Edit SQL Query page is displayed. 10 To continue building the SQL query, return to Step 3 in the Selecting Columns procedure.

Applying Filters to the Query Applying a filter to a query enables you to tune the data that is extracted by filtering out unnecessary data with the query.

➤ To apply a filter to a SQL query:

1 On the Edit SQL Query page, click the plus sign, , adjacent to Filter to expand the section. 2 Optional: In the Filter section of the Edit SQL Query page, click the Remove Duplicated Rows check box to automatically remove duplicate rows.

3 Click the Add Filter option to display the filter columns. 4 Select an operator from the list. 5 Select a table column.

84 Repository Objects Tool 6 Select a function from the list. 7 Type or look up a value. Enter open and close parentheses when you use a string.

Note: When more than one filter is applied, move them up and down with the arrows, , to modify the priority. The filter at the top of the list is performed first.

8 Click the minus sign, , adjacent to Filter to collapse the section. 9 Optional: Apply a Group By to one or more columns in the query. See the “Group By” topic for more information.

Deleting Filters When a filter is no longer necessary, you can delete the filter by performing the following procedure.

➤ To delete a filter : 1 In the Filter section of the Edit SQL Query page, select the check box adjacent to filter.

2 Click Delete Filter, , to remove a filter from the list.

Applying a Group By Use the Group By section of the Edit SQL Query page to select a column in which to group your information.

➤ To apply a Group By on one or more columns of a SQL query:

1 On the Edit SQL Query page, click the plus sign, , adjacent to Group By to expand the section. 2 In the Available Group By Columns list, highlight the column. 3 Click Select Group by Column. The column is added to the Selected Group By Column list. 4 Repeat steps 1 and 2 until all columns are selected.

5 Click the minus sign, , adjacent to Group By to collapse the form section. 6 Go to the topic Sorting Columns to apply a sort criteria to the columns of the SQL query.

Managing Views 85 Sorting Columns You can sort the columns of a SQL query by using sort criteria. This enables you to display and organize the information in the columns so you can work with the data more easily. You can use the following options to sort columns:

Option Description

Select Columns Ascending: Moves the highlighted column to the Selected Columns list.

Select Columns Descending: Moves the highlighted column to the Selected Columns list.

Deselect Column: Moves selected column to the Available Columns list.

Deselect All Columns: Removes all of the tables from the Selected Columns list to the Available Columns list.

Note: The above options are only available when the applicable object is selected. CTRL-click to select more than one object in a list.

➤ To apply sort criteria to one or more columns of a SQL query:

1 On the Edit SQL Query page, click the plus sign adjacent to Sort to expand the section. 2 In the Available Sort Columns list, highlight the column. 3 Select one of the following:

● Click Select Columns Ascending.

● Click Select Columns Descending. The column is added to the Selected Sort Columns list. 4 Repeat steps 1 and 2 until all columns are selected.

5 Click the minus sign, , adjacent to Sort to collapse the form section. 6 Go to the topic Completing the Relational View to complete the SQL query.

Completing the Relational View In this section of the Edit Relational View page you can provide the information required to complete, save, run, and export the query.

86 Repository Objects Tool ➤ To complete the query section of the Edit SQL Query page:

Note: The text box contains the query string that you have been building and should require no modification.

1 On the Edit SQL Query page, click the plus sign, , next to SQL Query to expand the section. 2 Optional: From the Folder drop down list select a folder to store the SQL query in. 3 In the Name text box type a name for the query. 4 In the Description text box type a description of the query. 5 Select an access type from the Access list. The list includes:

● A specific user - Makes the contents of the folder available to a specific user

● Private - Makes the contents of the folder private to the creator of the folder

● Public - Makes the contents of the folder public to all users 6 Click Save. 7 Click Run. The Result screen is displayed. 8 When you are finished reviewing the results, click OK. The Edit SQL Query screen is displayed.

Exporting the Query to a Text File The query can be exported to a text file by performing the following procedure.

➤ To export the query to a text file: 1 In the Edit SQL Query page, click Export to Text. The Export to text file page is displayed. 2 In the Export to text file page, perform one of the following:

● In the Name text box append the name of the file to the path displayed.

● In the Name text box enter a relative or absolute path and filename.

● Using the Lookup button, locate a place to store and name the text file. 3 Enter a brief description. 4 Click OK. The file is exported to the specified location and the Edit SQL Query page is displayed.

Managing Views 87 Creating Folders Views can be stored in a folder hierarchy system of your design, within the repository. The following procedure describes how to create a folder.

Note: You cannot copy a cube view from one folder to another.

➤ To create a folder for storing views: 1 On the Select Repository Object page of the Repository Objects tool, click the Create icon and select Folder. The Edit Folder page is displayed. 2 Optional: Select a folder from the list of Folders. The default folder is . 3 In the Name text box type a name. 4 Enter a brief description. 5 Click Save. The folder is created in the repository for storing views. 6 Repeat steps 2-5 to add more folders, or click Cancel to return to the Select View page.

Deleting Views The following procedure enables you to delete views that are no longer necessary to retain.

➤ To delete a view from the Select Repository Objects window: 1 On the Select Repository Object window, select a view from the list of views. 2 Click Delete. The confirm delete dialog is displayed. 3 Make one of the following choices:

● Click OK to delete the view.

● Click Cancel to keep the view.

Running Views Use the following procedure for running an existing view.

➤ To run a v iew : 1 On the Select Repository Object page, select a view from the list of views. 2 Click Run. The View Results page is displayed.

88 Repository Objects Tool 3 After viewing the results, click Cancel. The Select Repository Object page is displayed.

Setting Permissions You can set the permissions for a view or folder in order to specify groups or individuals and what they can or cannot do with the query. These permissions are set by the following procedure.

➤ To modify the permissions for a view: 1 On the Select Repository Object page of the Repository Objects tool, select an object and click Permissions. The Edit Permission page is displayed. 2 Select the name of the user or group in the list, if necessary. 3 Select one or more of the applicable permissions to assign to the object. 4 Optional: Select Setting User Permissions and Special Permissions to refine the permissions. 5 When you are finished setting the permissions, click OK.

Using Permissions You can use set permissions on users, views, and folders. In the following example, a view with HAB_analyst permissions to create, delete, exec, list, read, and write, is moved to a folder with hab-viewer permissions to list and read.

➤ To set permissions on objects: 1 Create a view, for example view_1. for information on creating either SQL views or OLAP views, see “Creating or Editing SQL Queries” on page 81, or “Using OLAP Views” on page 78 2 Assign HAB_Analyst to view_1. 3 Create a folder; for example, folder_1. For information on creating a folder, see “Creating Folders” on page 88 4 Assign the folder, folder_1, with HAB_Viewer permissions. For information on setting permissions, see “Setting Permissions” on page 89. 5 Move view_1 to folder folder_1. 6 The user can now only have the folder permissions of listing and reading view_1.

Managing Views 89 90 Repository Objects Tool Chapter XML Setup Tool 5

The XML Setup Tool is provided to manage the XML files used to administer your application. The XML files are stored in the repository for access and maintenance. The following XML file tools define the purpose of the file types for your system:

● Annotation XML Setup - This cascading annotation can be set up by name to apply an annotation down to the cell level of a cube or a relational table.

● Cell Format XML Setup - This XML file gives a names space to a cell format for either a cube view or a relational query.

● Data Source XML Setup - This XML file is used to create, edit, and manage hierarchical folders, OLAP data sources, relational data sources, cubes, and ADM pool objects.

● Drill Through XML Setup - This tool uses an XML file that establishes the path from an application's OLAP cube to a target relational system using SQL queries.

● Grid Export XML Setup - This tool defines the output of a cube view, query information, or grid to one of several formats: PDF, RTF, HTML, Excel, Power Point, or plain text.

● Single Sign-on XML Setup - This tool configures an XML file to use Single Sign-on.

● Task Registry Setup - This tool adds custom tasks to a task registry XML file. All the tasks defined in the task registry file are available when you use the Repository Object tool to edit or create tasks.

In the XML Setup Tool is a list of XML files for each of the setup utilities. The WAAFileDescriptions.properties adds a description to each XML file listed on the "XML Setup" tab. These are sample XML files provided in the repository. You can also create your own or modify the existing files with the XML Setup Tool. In order to gain access to the XML Setup Tool, the topic Accessing XML Files addresses the procedure for starting administration of the XML files. For more detailed information about XML file setup, see Hyperion Application Builder Web Application Architecture Developer’s Guide.

XML Setup Tool 91 Accessing XML Files When you access the XML Setup Tool from the Administration Tools home page, the default set up page is Data Source Setup. From this page you can manage any of the XML files. When editing or creating one of the XML file types, you must select that XML Setup tool or the following dialog is displayed.

The sample Application Builder XML files are accessible from one of the following locations:

● The WAAGridExport.xmlis located in: [/webapps]/hab-admin/WEB- INF/classes/com/hyperion/waa/utility/core/export/

● All other XML files are located in: [/webapps]/hab-admin/WEB-INF/classes/

Note: is the drive and directory where your application server is installed with Application Builder. Within the application server installation, you may define an optional directory, such as shown in [/webapps] for convenience.

➤ To access the XML Setup Tool. 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 Click XML Setup. The XML Setup page is displayed:

92 XML Setup Tool The XML Setup page lists all of the available XML files in the directory path shown. You can navigate to the location of other XML files by entering an alternative path.

Annotation XML Setup An annotation is text data that is store at the cell level, there are two types of annotations; global and regional. The difference between global and regional is their proximity to the cell of the data source. A global annotation allows for annotations to be applied across the data source. A regional annotation is applied to more specific locations in the data source. In a cascading affect, the specific regional annotation supersedes the generalized global annotation. Annotations can be applied to both OLAP and relational data source types. The XML files are separate for each data source type and are explained in greater detail in the following sections:

● Creating OLAP Annotations

● Creating Relational Annotation XML Files

For additional information regarding annotation XML files, see “Annotation XML Setup” on page 93.

Creating OLAP Annotations This section describes how to create an OLAP annotation XML file that can then be attach the annotation to a cube at the cell level by calling it in a view. For additional information regarding OLAP annotation XML files, see Chapter 6 and Appendix D in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Note: This section assumes you have started and logged into the Administration Tools and selected the XML Setup tool.

Annotation XML Setup 93 ➤ To create an OLAP annotation XML file in the XML Setup Tool: 1 Click on Annotation in the XML Setup Tool toolbar menu. The Annotation Setup page is displayed.

2 Click Create OLAP annotation. The Cell Format Setup page is displayed.

The following procedures are accomplished from the Cell Format Setup page. There are several optional and required tasks to perform when accomplishing an annotation setup. These tasks include:

● Choosing a Data Source - This required task selects the OLAP cube that the annotation is connected to.

94 XML Setup Tool ● Creating Groups for Annotations - Optionally, you can create a group structure for storing annotations. This becomes required when adding a local region annotation to a new data source.

● Creating OLAP Annotation XML Files - This task modifies a local region annotation type and is the closest to the cube. The local region annotation supersedes the global region annotation.

Choosing a Data Source The first step in creating an annotation is to select the data source that the annotation is applied to.

➤ To select a data source: 1 On the Cell Format Setup page, perform one of the following:

● Click the Root object. Then click the OLAP Data Source button to add a data source.

● Select a Cube in the tree. Click Edit to edit an existing data source. The Select Source page is displayed.

2 Choose one of the following:

● Click Use Data Source Tree to select a data source from the data source tree. Navigate the tree until you locate the desired data source.

● Click Use Direct Connection to enter direct connection information. The Select Source page displays the fields required for a direct connection.

Annotation XML Setup 95 a. Select one of the following connection types:

❍ Local - this is a connection to a data source on the local computer.

❍ Remote - this is a connection to another computer. b. Provide the following data source connection information:

❍ Server - the name of the server

❍ Schema - the name of OLAP cube schema

❍ Cube - the name of the OLAP cube

❍ Remote Server - the name of the remote server (remote connection type only)

❍ Driver - select a driver from the list of available drivers

❍ Connection Parameters - parameters that set specific conditions for the connection

❍ User ID - a valid authorized user

❍ Password - a valid password for the user ID 3 Click OK. The data source for the annotation is selected.

Creating Groups for Annotations Regional annotations can be stored in groups to help you manage the annotations

➤ To create a group to store regional annotations: 1 On the Cell Format Setup page, select a cube and click the Group button. The Edit Properties page is displayed.

96 XML Setup Tool 2 In the Name text box enter a name for the group. 3 In the Description text box enter a brief description. 4 Click OK. The group is added to the data source tree in the Cell Format Setup page.

Creating OLAP Annotation XML Files After you create an annotation XML file, you need to configure the behavior of the XML file.

➤ To edit an annotation XML file: 1 On the Annotation Setup page, Perform one of the following:

● Select an OLAP annotation XML file, click Edit.

● Click Create. The Cell Format page is displayed.

2 In the data source tree, click Edit. 3 Select the global or local region object.

Annotation XML Setup 97 The Edit Properties page of the global or local region is displayed (Local Region shown in the figure.)

4 Perform one of the following:

❍ Select the Attachable check box to the right of one of the dimensions in the list. This allows all members returned by the query to have annotations attached.

❍ Select the option button to the left of one of the dimensions in the list. Click Lookup Selection. The Edit Member page is displayed.

Note: For more information on using the Edit Member tool, see the Edit Member Tool section.

a. Select one or more check boxes adjacent to the list of members. b. Click OK. The Edit Properties page for dimensions is displayed. 5 Click OK.

98 XML Setup Tool The OLAP Annotation XML file is updated. 6 Click OK again. The Save page is displayed.

7 Append the name of the annotation XML file to the end of the path in the Name text box. 8 In the Description text box enter a brief description. 9 Click OK. The XML file is saved to the repository and is displayed in the list of XML files on the Annotation Setup page.

Creating Relational Annotation XML Files Relational annotation XML files provide you with the ability to apply annotations to a relational data source. The XML file is created, then stored in the repository and then called by a SQL query to apply it. Creating a relational annotation XML file is a series of tasks that include:

Note: The following procedures assume that you are logged on to the Administration Tools, and have selected the XML Setup Tool from the menu.

● Accessing the Relational Annotation XML Setup

● Selecting a Server

● Selecting a Relational Database

● Defining Groups

● Selecting Columns in the Database

● Selecting Table and Column Objects

For additional information regarding relational annotation XML files, see Chapter 6 and Appendix D in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Annotation XML Setup 99 Accessing the Relational Annotation XML Setup

➤ To select the Relational Annotation XML Setup tool: 1 On the XML Setup page, click on Annotation. The Annotation Setup page is displayed. The available XML files are listed.

2 Click Create relational annotation. The Annotation Setup page is displayed the relational tree.

Selecting a Server

➤ To select a server for the relational XML file: 1 On the Annotation Setup page select the root object.

100 XML Setup Tool 2 Click the Server button on the toolbar. The Server Edit Properties page is displayed.

3 In the Server Edit Properties page, enter a value for the server Name. 4 Click OK. The server is added to the tree on the Annotation Setup page.

Selecting a Relational Database

➤ To select the relational database for the relational annotation XML file: 1 On the tree of the Annotation Setup page, select the server. 2 Click the Database button on the toolbar. The Database Edit Properties page is displayed.

3 Enter the Name of a database on the selected server. 4 Click OK. The Annotation Setup page is displayed with the added database object.

Defining Groups Group objects are created as containers of column and Table/Column selections.

➤ To create a group for the relational annotation XML file: 1 On the Annotation Setup page, select an existing database.

Annotation XML Setup 101 2 Click the Folder button on the toolbar. The Group Edit Properties page is displayed.

3 Enter a name for the group. 4 Enter a brief description for the group. 5 Click OK. The group is added to the tree on the Annotation Setup page.

Selecting Columns in the Database

➤ To select columns in the database to attach annotations to: 1 On the Annotation Setup page select one of the following:

❍ A relational database in the tree.

❍ A group in the tree. 2 Click the Columns button on the toolbar. The Columns Edit Properties page is displayed.

3 Enter a name for the column. 4 Click the Lookup button for the query value. 5 Select the Attachable check box so you can attach annotations to the column.

102 XML Setup Tool 6 Click OK. The column is added to the database or group object it was created in.

Selecting Table and Column Objects

➤ To select table and column objects: 1 On the Annotation Setup page, select an existing Column of a database or group. 2 Click the Table, Column button on the toolbar. The Table, Column Edit Properties page is displayed.

3 Enter a table name. 4 Enter a column name. 5 Click OK. The Annotation Setup page is displayed with the Table and Column object in the tree. 6 Click OK. The relational annotation Save page is displayed.

7 Perform one of the following:

● In the Name text box, append the name of the relational annotation XML file you are creating to the end of the path displayed.

● In the Name text box, enter a relative or absolute path and name for the XML file. 8 Enter a brief Description.

Annotation XML Setup 103 9 Click OK. The Annotation Setup page is displayed with the XML file list that includes the new relational annotation XML file.

Cell Format XML Setup Formatting can be defined for either a cube in an OLAP database or a relational database down to the cell level. Formatting can then be applied by calling the formatting XML file in the view or query accessing the specified database. The process of creating or editing cell format XML files is described in the following sections:

● Accessing the Cell Format Tool

● Creating OLAP Cell Format XML Files

● Creating Relational Cell Format XML Files

For additional information regarding cell format XML files, see “Cell Format XML Setup” on page 104 and Chapter 9 in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Accessing the Cell Format Tool

➤ To access the Cell Format Tool: 1 In the Administration Tool, select XML Setup from the menu. 2 On the XML Setup page select Cell Format from the menu. The Cell Format Setup page is displayed.

104 XML Setup Tool 3 From the Cell Format Setup page you can create or edit an OLAP or a relational cell format. For more information on creating the two types of cell format XML files, see the sections Creating OLAP Cell Format XML Files and “Creating Relational Cell Format XML Files.”

Creating OLAP Cell Format XML Files The process of creating an XML file that points to a specific cell in an OLAP database in order to apply cell formatting, is described in the following sections:

● Selecting an OLAP Data Source

● Defining a Format Definition

● Setting the Formatting of Cells

❍ Setting OLAP Numeric Cell Format Values

❍ Setting Date/Time Cell Format Values

After you complete these procedures you save the information to a cell format XML file after setting the formatting. For additional information regarding OLAP cell format XML files, see Chapter 6 and Appendix C in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Selecting an OLAP Data Source The first step in the process of applying cell formats is selecting the data source that the formats are applied to.

Cell Format XML Setup 105 ➤ To select an OLAP data source for the cell format: 1 On the Cell Format Setup page, click Create OLAP cell format. The Cell Format page is displayed with the Cell Format tree. 2 With the root object selected, click the OLAP Data Source button on the toolbar. The Select Source page is displayed.

3 Perform one of the following:

Note: For more information on data sources, see “Data Source XML Setup.”

● Choose a data source from the tree.

● Select Use Direct Connection, and follow the Direct Connection instructions. 4 Click OK. The Cell Format Setup page is displayed with the new data source connection in the tree.

Defining a Format Definition A format definition object is a container for storing the properties of the cell formatting that will be applied to the designated cells.

➤ To define the format definition: 1 From the Cell Format Setup page, select the data source for the definition, and click the Format Definition button on the toolbar.

106 XML Setup Tool The Format Edit Properties page is displayed.

2 In the Name text box, enter the required Name. 3 Enter the missing text in the text box. 4 Enter the no access text in the text box. 5 Enter the zero text in the text box. 6 Click OK. The Cell Format Setup page is displayed with the format definition in the tree.

Setting the Formatting of Cells You can format cells with a cascading effect from the page, row, and column, down to the cell level. If formatting is applied at the page, row, or column level it is applied to all the cells on the page, row or column. If a format is applied to a cell, it supersedes a format applied at the column, row, or page. A format applied at the column or row supersedes a format applied at the page level. Setting the parameters of a format are broken down into the following procedures:

● Setting OLAP Numeric Cell Format Values

● Setting Date/Time Cell Format Values

Setting OLAP Numeric Cell Format Values

➤ To set the numeric cell format: 1 In the tree on the Cell Format Setup page, select a format definition. 2 Select one of the following:

● Click the Page Format button on the toolbar.

● Click the Row Format button on the toolbar.

● Click the Column Format button on the toolbar.

Cell Format XML Setup 107 The Page Edit Properties page is displayed with the numeric format as the default. 3 Modify the following format values to suit your needs:

Note: For more detailed information on cell formats, see Chapter 6 and “Setting Up Formatting XML Files” on page 291Appendix C in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Name Value

Index The required numeric index of the page, column, and/or row at which the cell format is applied. More than one index may be required.

Type Select one of the following from the list.

● None - for the Double.toString() result, which is the default.

● Number - for a locale based number.

● Percent - is the percentage for a locale based percent.

● Currency - is the currency for a locale based currency.

● Pattern - is the pattern for a pattern specification.

Scaling Factor Indicates the number to scale by. For example, if you are calculating a percentage, set this to 100. A positive value will scale up, while a negative value will scale down.

Locale This value identifies the locale to use for the current session.

Pattern This value indicates the pattern to use for integers and floating point numbers.

Group Size This value indicates the size of the group for the comma placement. For example, if the number 3000 has a groupingSize of 3, the result will display as 3,000. If you set the grouping size to 0, a comma is not placed in the number.

Always Show Decimal This value sets the decimal separator to always show. Separator

Minimum Integer Digits Specifies the minimum number of digits to display before the decimal separator. Leading zeros are added if necessary. For example, the number 5 with minimumIntegerDigits set to 3 = 005.

Maximum Integer Digits Specifies the maximum number of digits to display before the decimal separator. Digits are truncated or rounded if necessary. For example, the number 005000, with the maximumIntegerDigits set to 4 the number 5000 is displayed. With the number 5000 and the maximumIntegerDigits set to 1 the number 5 is displayed.

Minimum Fraction Digits Specifies the minimum number of digits to display after the decimal separator. Trailing zeros are added if necessary. For example, the number1.25 with minimumFractionDigits set to 4 = 1.2500.

Maximum Fraction Digits Specifies the maximum number of digits to display after the decimal separator. Digits are truncated or rounded after the decimal separator if necessary. For example,.12299 with the maximumFractionDigits set to 3 will display as 1.22.

Negative Prefix Specifies the prefix to use with a negative number; for example, an open sign parenthesis “(“.

Negative Suffix Specifies the suffix to use with a negative number; for example, a closed sign parenthesis “)“.

108 XML Setup Tool Name Value

Positive Prefix Specifies the prefix to use with a positive number; for example, an open sign parenthesis “(“.

Positive Suffix Specifies the suffix to use with a positive number; for example, an closed sign parenthesis “)“.

4 When all cell format values are set, click OK. The new cell format is displayed in the tree of the Cell Format Setup page. 5 On the Cell Format Setup page, click OK. The Save page is displayed.

6 Perform one of the following:

● In the Name text box, append the name of the OLAP cell format XML file you are creating to the end of the path displayed.

● In the Name text box, enter a relative or absolute path and name for the XML file. 7 Enter a brief description. 8 Click OK. The Cell Format Setup page is displayed with the XML file list that includes the new relational annotation XML file.

Setting Date/Time Cell Format Values

➤ To set the numeric cell format: 1 On the Cell Format Setup page, select a format definition in the tree. 2 Select one of the following:

● Click the Page Format button on the toolbar.

● Click the Row Format button on the toolbar.

● Click the Column Format button on the toolbar. The Edit Properties page is displayed with the numeric format as the default. 3 Click Date/Time Format.

Cell Format XML Setup 109 The Edit Properties for Date/Time display.

4 Modify the following format values to suit your needs:

Note: For more detailed information on Date/Time formats, see Chapter 6 and Appendix C in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Name Value

Index Indicates the required numeric index of the page, column, and/or row to which the cell format is applied. More than one index may be required.

Type Indicates the type of formatting. Valid types are:

● None - for the Date.toString() result, which is the default

● Date - for a locale based date

● Time - for a locale based time

● Date/Time - for a locale based date and time

● Pattern - for a pattern specification

Style Specifies the general style to use when displaying the date, time, and date/time format. Valid styles and examples for April, 10, 1998 and 3:58:45 PM are:

● Default - 10-Apr-98 and 3:58:45 PM

● Short - Example, 4/10/98 and 3:58 PM

● Medium - Example, 10-Apr-98 and 3:58:45 PM

● Long - Example, April 10 and 1998 and 3:58:45 PM PDT

● Full - Example, Friday, April 10, 1998 and 3:58:45 o’clock PM PDT

Locale Identifies the locale to use for the current session.

Pattern Specifies the date, time, and date/time formats by date and time pattern strings, for example: “yyyy.MM.dd G ‘at’ HH:mm:ss z” is displayed as “2001.07.04 AD at 12:08:56 PDT“

5 When all values are set, click OK.

110 XML Setup Tool The new cell format is displayed in the tree of the Cell Format Setup page. 6 Click OK on the Cell Format Setup page. The Save page is displayed.

7 Perform one of the following:

● In the Name text box, append the name of the OLAP cell format XML file you are creating to the end of the path displayed.

● In the Name text box, enter a relative or absolute path and name for the XML file. 8 Enter a brief description. 9 Click OK. The Cell Format Setup page is displayed with the XML file list that includes the new relational annotation XML file.

Creating Relational Cell Format XML Files To creating a relational cell format XML file so that you can apply cell formatting to a relational database is accomplished by performing the following procedures:

● Accessing the Relational Cell Format Setup Tool

● Selecting a Server

● Selecting a Database

● Defining a Format Definition

● Defining a JDBC Connection

● Setting the Cell Formatting

For additional information regarding relational cell format XML files, see Chapter 6 in the Hyperion Application Builder Web Application Architecture Developer’s Guide and Appendix C “Using a Relational Formatting XML File” on page 291.

Accessing the Relational Cell Format Setup Tool The following procedure provides the steps to access the XML setup tool for applying cell formatting to a relational data source.

Cell Format XML Setup 111 ➤ To access the Relational Cell Format Setup tool: 1 On the Administration Tools menu click XML Setup. The XML Setup page is displayed. 2 On the XML Setup page click Cell Format. The Cell Format Setup Page is displayed. 3 Click Create relational cell format. The Cell Format Setup page is displayed.

Selecting a Server This procedure selects the server where the cell formatting is applied.

➤ To select a server for the relational cell format XML file: 1 On the relational Cell Format Setup page, select the root of the tree. 2 Click the Server button on the toolbar. The server Properties page is displayed.

3 Enter a name in the text box. 4 Click OK. The server name is displayed in the tree of the Cell Format Setup page.

Selecting a Database This procedure selects the database on the server that the cell formatting is applied.

➤ To select a database for the relational cell format setup XML file: 1 In the tree on the Cell Format Setup page, select an existing server object. 2 Click the Database button in the toolbar. The database Edit Properties page is displayed.

112 XML Setup Tool 3 Enter a name for the database in the text box. 4 Click OK. The Cell Format Setup page is displayed with the database as a child object in the tree.

Defining a Format Definition A format definition must be created for the database where the cell form is applied. The following procedure assists you in defining the format definition.

➤ To create a format definition for the relational cell format XML file: 1 In the Cell Format Setup page object tree, select an existing database. 2 In the toolbar, click the folder Format Definition button. The format definition Edit Properties page is displayed.

3 Enter the required name in the text box. 4 Enter a null text in the text box. 5 Click OK. The object tree on the Cell Format Setup page is displayed with the format definition object.

Created along with the format definition are two default objects to assist in the cell formatting process. Generic numeric format and date/time format objects are created automatically as children of the format definition. To perform the procedures that manage the two format types see Setting Relational Numeric Cell Format Values and “Setting Date/Time Cell Format Values.”

Cell Format XML Setup 113 Defining a JDBC Connection In order for the XML file to communicate with the database that you selected, a JDBC connection must be made. Java Database Connectivity (JDBC) is a programming interface that lets Java applications access a database via the SQL language. The following procedure contains the steps you need to complete to establish the JDBC connection.

➤ To create a JDBC connection for the relational cell format setup XML file: 1 In the tree of the Cell Format Setup page, select an existing format definition. 2 Click the JDBC button on the toolbar. The JDBC Edit Properties page is displayed.

3 Enter an existing data source value in the text box. 4 Enter a valid user ID for the data source. 5 Enter a valid password for the user ID. 6 Click OK. The JDBC object is added to the format definition object in the tree of the Format Cell Setup page.

Setting the Cell Formatting Formatting of cells is handled using a cascading effect from the columns, row, and column, down to the cell level. If formatting is applied to multiple columns or rows, it is applied to all of the cells in the columns or rows. If a format is applied to a cell, it supersedes a format applied to columns or rows. This means that formats applied at the single column or row supersedes the multiple column formats as well. The process of setting the format values at the cell, column, or row is the same. The following procedures explain this in detail:

● Setting Relational Numeric Cell Format Values

● Setting Date/Time Cell Format Values

114 XML Setup Tool Setting Relational Numeric Cell Format Values

➤ To set the numeric cell format: 1 On the Cell Format Setup page, select a format definition in the tree. 2 Click one of the following:

● The Page Format button on the toolbar.

● The Row Format button on the toolbar.

● The Column Format button on the toolbar. The Edit Properties page is displayed with the numeric format as the default.

3 Modify the following format values to suit your needs:

Note: For more detailed information about numeric cell formatting, see Chapter 6 and Appendix C in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Cell Format XML Setup 115 Name Value

Index Indicates the required numeric index of the table, column, and/or row to which the cell format applies. More than one index may be required.

Type Select one of the following from the list.

● None - for the Double.toString() result, which is the default.

● Number - for a locale based number

● Percent - is the percentage for a locale based percent

● Currency - is the currency for a locale based currency

● Pattern - is the pattern for a pattern specification

Scaling Factor Indicates the number to scale by. For example, if you are calculating a percentage, set this to 100. A positive value scales up, while a negative value scales down.

Locale Identifies the locale to use for the current session.

Pattern Indicates the pattern to use for integers and floating point numbers

Group Size This value indicates the size of the group for the comma placement. For example, if the number 3000 has a groupingSize of 3, the result will display as 3,000. If you set the grouping size to 0, a comma is not placed in the number.

Always Show Decimal Indicates to always show the decimal separator Separator

Minimum Integer Digits Specifies the minimum number of digits to display before the decimal separator. Leading zeros are added if necessary. For example, the number 5 with minimumIntegerDigits set to 3 = 005.

Maximum Integer Digits Specifies the maximum number of digits to display after the decimal separator. Digits are truncated or rounded after the decimal separator if necessary. For example,.12299 with the maximumFractionDigits set to 3 will display as 1.22.

Minimum Fraction Digits Specifies the minimum number of digits to display after the decimal separator. Trailing zeros are added if necessary. For example, the number1.25 with minimumFractionDigits set to 4 will display as 1.2500.

Maximum Fraction Digits Specifies the maximum number of digits to display after the decimal separator. Truncates or rounds digits after the decimal separator if necessary. For example,.12299 with the maximumFractionDigits set to 3 = 1.22.

Negative Prefix Specifies the prefix to use with a negative number; for example, an open sign parenthesis “(“.

Negative Suffix Specifies the suffix to use with a negative number; for example, a closed sign parenthesis “)“.

Positive Prefix Specifies the prefix to use with a positive number; for example, an open sign parenthesis “(“.

Positive Suffix Specifies the suffix to use with a positive number; for example, an closed sign parenthesis “)“.

4 When all cell format values are set, click OK.

116 XML Setup Tool The new cell format is displayed in the tree of the Cell Format Setup page. 5 Click OK on the Cell Format Setup page. The Save page is displayed.

6 Perform one of the following:

● In the Name text box, append the name of the OLAP cell format XML file you are creating to the end of the path displayed.

● In the Name text box, enter a relative or absolute path and name for the XML file. 7 Enter a brief description. 8 Click OK. The Cell Format Setup page is displayed with the XML file list that includes the new relational annotation XML file.

Setting Date/Time Cell Format Values

➤ To set the numeric cell format: 1 On the Cell Format Setup page, select a format definition in the tree. 2 Click one of the following:

● The Page Format button on the toolbar.

● The Row Format button on the toolbar.

● The Column Format button on the toolbar. The Edit Properties page is displayed with the numeric format as the default. 3 Click Date/Time Format. The Edit properties for Date/Time display.

Cell Format XML Setup 117 4 Modify the following format values to suit your needs:

Note: For more detailed information on Date/Time cell formatting, see Chapter 6 and Appendix C in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Name Value

Index Indicates the required numeric index of the columns and/or row to which the cell format is applied.

Type Indicates the type of formatting. Valid types are:

● None - for the Date.toString() result, which is the default.

● Date - for a locale based date.

● Time - for a locale based time.

● Date/Time - for a locale based date and time.

● Pattern - for a pattern specification.

Style Specifies the general style to use when displaying the date, time, and date/time format. Valid styles and examples for April, 10, 1998 and 3:58:45 PM are:

● Default - 10-Apr-98 and 3:58:45 PM

● Short - Example, 4/10/98 and 3:58 PM

● Medium - Example, 10-Apr-98 and 3:58:45 PM

● Long - Example, April 10 and 1998 and 3:58:45 PM PDT

● Full - Example, Friday, April 10, 1998 and 3:58:45 o’clock PM PDT

Locale Identifies the locale to use for the current session

Pattern Date, time, and date/time formats are specified by date and time pattern strings. Example: “yyyy.MM.dd G ‘at’ HH:mm:ss z” is displayed as “2001.07.04 AD at 12:08:56 PDT“

118 XML Setup Tool 5 When all values are set, click OK. The new cell format is displayed in the tree of the Cell Format Setup page. 6 Click OK on the Cell Format Setup page. The Save page is displayed.

7 Perform one of the following:

● In the Name text box, append the name of the relational cell format XML file you are creating to the end of the path displayed.

● In the Name text box, enter a relative or absolute path and name for the XML file. 8 Enter a brief description. 9 Click OK. The Cell Format Setup page is displayed with the XML file list that includes the new relational annotation XML file.

Data Source XML Setup The Data Source tool handles the XML generation for several data source nodes. It includes forms for objects such as hierarchical folders, OLAP data sources, relational data sources, cubes, and pools. You can use the forms to create, edit, and manage these objects. You use the Data Source tool for the following tasks:

● Modifying the debug, locale, and encryption node settings. For more information see “Modifying the Node Settings.”

● Managing ADM pools. For more information, see “Managing ADM Pools.”

● Managing folders. For more information, see “Managing Folders.”

● Managing OLAP and relational data sources. For more information, see Managing OLAP Data Sources and “Managing Relational Data Sources.”

● Managing cubes. For more information, see “Managing Folders.”

For additional information regarding data source XML files, see “Setting up OLAP Data Sources and ADM Pooling” on page 267, and “Setting Up Relational Data Sources” on page 279.

Data Source XML Setup 119 Accessing the Data Source Tool You access the Data Source Tool from the Application Builder Administration Tools home page.

➤ To access the Data Source Tool. 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 Click Data Source. The Data Source Setup page is displayed:

Navigating the Data Source Tool In addition to the navigation features available throughout Application Builder Administration Tools, the Data Source Tool has several navigation features specifically for managing the Data Source tree. The following table describes the Data Source Tool navigation features:

Navigation Feature Description

Moves the selected node up or down one row

Move Selected Up / Move Selected Down buttons

Opens the selected node's Properties screen for editing

Note: By changing the ID or name of the node in the Edit Properties screen, you Edit button create a new node without modifying the existing node.

120 XML Setup Tool Navigation Feature Description

Cuts the selected node and the Paste Child Node option is displayed

Cut button

Pastes the last node you cut to the selected location

Paste button

Deletes the selected node until you save your changes

Delete button

Saves your changes to the Data Source node tree.

Note: No changes to the node tree are retained unless you click this button. There is no confirmation that changes will be lost when you navigate away from the node tree. Save button

Selecting and Synchronizing the Data Source XML Files It is necessary for you to select a data source XML file to store the data source information into. It is also necessary to synchronize the data source XML file with the repository. The following procedure shows you how to select and synchronize the sample file or a customized one to store in the repository.

➤ To select the WAADataSources.xml or a custom file: 1 Click on Data Source in the XML Setup page menu. The Data Source Setup page is displayed.

2 Type the path to the directory of the XML file.

Data Source XML Setup 121 3 Click Create. The Data Source XML file is selected and the Data Source Setup screen is displayed showing the data source node tree.

➤ To synchronize the data source XML file:

Note: This procedure is required when any changes to the data sources are made. Changes can consist of a modification or addition of data sources to an existing XML file or the creation of another data source XML file.

1 On the Data Source Setup page, select the data source XML file.

2 Click the Synchronize, , button. The synchronize confirmation dialog displays.

3 Click OK. The Data Source Setup page refreshes and the data sources in the XML file are added to the ATF repository.

Populating the Data Source XML File Before you can execute the WAADataSource.xml file, you must populate it with information for identifying, editing, and managing the data sources for your application. The Data Source tool includes the following forms that you can use to populate the file:

● Folder - This form identifies the folder that contains all other components that are displayed hierarchically in the node tree. For more information, see “Managing Folders.”

● OLAP Data Source - This form generates the XML required to establish an OLAP database source data connection. For more information, see “Managing OLAP Data Sources.”

● Relational Data Source - This form generates the XML required to establish an relational database source data connection. For more information, see “Managing Relational Data Sources.”

● Cube - This form identifies the cube that enables you to connect to an OLAP data source. For more information, see “Managing Cube Nodes.”

122 XML Setup Tool Modifying the Node Settings You can modify the Debug, Locale, and Encryption node settings for the current node and any of its children. You edit these settings on the Debug/Locale/Encryption Edit Properties page.

Note: You cannot edit the server node.

➤ To modify the node settings: 1 From the Data Source Setup page, select a node in the node tree.

2 Click Edit Debug/Locale/Encryption. The Debug/Locale/Encryption Edit Properties page is displayed.

. 3 Do one or more of the following:

● To turn the debug feature on or off, select the Debug check box for the selected node and its children. Off is the default.

● Change the language to one of the following:

❍ English (Default)

❍ French

❍ German

❍ Japanese

● Select the Encryption check box to turn password encryption on or off in Application Builder Administration Tools. 4 Do one of the following: a. Click OK to create a folder and return to the node tree on the Data Source Setup page. b. Click Cancel to return to the node tree on the Data Source Setup page without creating a folder.

5 Click the Save button, .

Data Source XML Setup 123 Managing ADM Pools You can use ADM pools of users as a means of reducing bandwidth requirements on the system. It is logical to base user groupings on similar connection usage requirements. Managing the pools includes these tasks:

● Creating or Editing Pool Configurations

● Deleting Pool Configurations

● Adding or Editing Pool Nodes

● Deleting Pool Nodes

For additional information about managing ADM pools, see Appendix A in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Creating or Editing Pool Configurations ADM pool configurations are created and applied to data source connections in order to manage user connectivity. The configurations you create with the following procedure are selected when creating pool nodes.

➤ To create and edit ADM pool configurations: 1 On the Data Source Setup page, click Edit PoolConfig. The Select pool configuration page is displayed.

2 Perform one of the following: a. Click Create. b. Select an existing pool configuration and click Edit. The PoolConfig Edit Properties page is displayed.

124 XML Setup Tool

3 On the PoolConfig Edit Properties page, enter or change the pool configuration settings:

● ID - The ADM pool's unique identifier; for example, PP1

● Max - The maximum number of open ADM connections that can be at one time

● Min - The minimum number of ADM connections that can be open at one time

● Timeout - The length of time a connection can be inactive before it is returned automatically to the ADM pool

Note: The minimum number of ADM connections, specified with the Min setting, stay open regardless of the Timeout setting.

● Ratio - The ratio between the number of ADM instances and the number of connection instances. For example, you specify a ratio of 1/2 or 0.5 to create one connection for every two ADM users.

● Timeout Interval - The frequency, in seconds, with which inactive connections are checked

● Retry Interval - The waiting time, in seconds, between attempts to acquire a connection

● Retry Times - The number of times to retry acquiring a connection

● Auto Check - Whether a background thread checks for frozen connections. If this is true, a background thread checks for frozen connections. If this is false, no action is taken. The default is false. 4 Do one of the following: a. Click OK to create or change the configuration and return to the Select Pool Configuration page. b. Click Cancel to return to the node tree on the Data Source Setup page without creating or changing a configuration.

5 Click the Save button .

Data Source XML Setup 125 Deleting Pool Configurations Deleting an ADM pool configuration removes it from the list of configurations. It is deleted permanently only when you save your changes to the pool configuration.

➤ To delete a pool configuration: 1 From the Select Pool Configuration page, select the pool configuration you want to delete.

2 Click Delete, . A confirmation dialog is displayed. 3 Click OK. 4 Click Cancel to return to the node tree on the Data Source Setup page.

5 Click the Save button, , to delete the connection permanently.

Adding or Editing Pool Nodes You can add an ADM pool node to the tree with a specific pool configuration by following the procedure.

➤ To add or edit a pool node: 1 On the Data Source Setup page, do one of the following:

● To add a new pool node, click the Pool button,

● To edit a pool node, select an existing pool node in the tree and click Edit, . The Pool Edit Properties page is displayed.

2 On the Pool Edit Properties page, enter or edit the following settings:

126 XML Setup Tool ● Name - The name of the data source; for example, Power User

● Pool Config ID - The unique identifier for the pool configuration, which you select from a drop-down list of available configurations. Pool config IDs can be added by performing procedure “Creating or Editing Pool Configurations.”

● User Name - Your user name for a accessing the connection pool

● Password - The password for the user name to access the connection pool 3 Do one of the following:

● Click OK to create a folder and return to the node tree on the Data Source Setup page.

● Click Cancel to return to the node tree on the Data Source Setup page without creating a folder.

4 Click Save, .

Deleting Pool Nodes A necessary part of administrating a data source is removing unnecessary ADM pool nodes in the tree.

➤ To delete a connection pool configuration: 1 On the Select Pool Configuration page, select the pool configuration you want to delete.

2 Click the Delete button, .

3 Click the Save button, . The pool node is deleted permanently.

Managing Folders Folders contain other nodes in the tree. They can contain any of the following:

● Additional folders

● OLAP data sources

● Relational data sources

● Pools

Managing folders includes adding folders to the node tree and removing folders from the node tree by performing the following procedures:

● Adding Folders to the Node Tree

● Removing Folders from the Node Tree

Data Source XML Setup 127 Adding Folders to the Node Tree You add folders to the node tree on the Edit Properties - Folder page:

➤ To add a folder to the node tree: 1 On the Folder Edit Properties page, select a parent folder. 2 On the Data Source Setup page, click the Folder button in the Add Child toolbar. The Edit Properties page is displayed.

3 In the Name text box enter a name for the new folder. 4 In the Description text box enter a brief description of the folder. 5 Do one of the following:

● Click OK to create the folder and return to the node tree on the Data Source Setup page.

● Click Cancel to return to the node tree on the Data Source Setup page without creating a folder.

6 Click the Save button, .

Removing Folders from the Node Tree To remove empty or unnecessary folders from the node tree, perform the following procedure.

➤ To remove a folder from the node tree: 1 On the Data Source Setup page, click the button for the folder you want to delete from the tree.

2 Click the Delete button, . The node tree refreshes.

3 Click the Save button, .

Managing OLAP Data Sources Managing OLAP data sources includes the following tasks:

128 XML Setup Tool ● Adding or Editing OLAP Data Sources

● Deleting OLAP Data Sources

For additional information about managing OLAP data sources, see Appendix A in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Adding or Editing OLAP Data Sources

➤ To add or edit OLAP data sources: 1 In the Data Source Setup page perform one of the following:

● Select a folder to create an OLAP data source, click OLAP Data Source in the toolbar.

● Select an existing OLAP data source node, click Edit in the toolbar. The OLAP Data Source Edit Properties page is displayed.

2 On the OLAP Data Source Edit Properties page, specify or change the following settings:

● Name - The name of the data source; for example: SSDemo

● Description - A description of the data source

● Driver - The driver for the data source; for example, Hyperion Essbase Analytic Services (HssEssDriver)

● Server - The name of the server on which the data source resides; for example, localhost

● Application - The name of the application to which the data source belongs; for example, SSDemo

Data Source XML Setup 129 Note: All of the settings are required except for the description.

3 Do one of the following:

● Click OK to create the folder and return to the node tree on the Data Source Setup page.

● Click Cancel to return to the node tree on the Data Source Setup page without creating a folder.

Deleting OLAP Data Sources A necessary part of administrating a data source is removing unnecessary OLAP data source nodes from the tree. To delete an OLAP data source: 4 On the Data Source Setup page, select the data source you want to delete from the tree.

5 Click the Delete button, .

6 Click the Save button, . The data source is deleted permanently.

Managing Relational Data Sources Managing relational data sources includes the following tasks:

● Adding or Editing Relational Data Sources

● Deleting Relational Data Sources

For additional information about managing relational data sources, see Appendix B in the Hyperion Application Builder Web Application Architecture Developer’s Guide.

Adding or Editing Relational Data Sources

➤ To add or edit OLAP data sources: 1 In the Data Source Setup page perform one of the following:

● Select a folder to create an relational data source, click Relational Data Source in the toolbar.

● Select an existing relational data source node, click Edit in the toolbar. The Relational Data Source Edit Properties page is displayed.

130 XML Setup Tool 2 On the Relational Data Source Edit Properties page, specify or change the following settings:

● Name - The name of the data source; for example, Application Builder Query Data

● Description - A description of the data source

● JNDI - The URL for the data source; for example, Application Builder

Note: All of the settings are required except for the description.

➤ To add connection parameters to the relational data source: 1 In the text box above the Connection Parameters table, enter a Name. 2 In the text box above the Connection Parameters table, enter a value for the parameter. 3 Click Add. The connection parameter is displayed in the table. 4 Click the OK. The Data Source Setup page is displayed.

Deleting Relational Data Sources A necessary part of administrating a data source is removing unnecessary relational data source nodes from the tree. To delete a relational data source: 5 On the Data Source Setup page, select the data source you want to delete from the tree.

6 Click Delete, .

Data Source XML Setup 131 7 Click Save, . The data source is deleted permanently.

Managing Cube Nodes Managing cube nodes for an OLAP data source includes the following tasks:

● Adding or Editing Cube Nodes

● Deleting Cube Nodes

Adding or Editing Cube Nodes You use the Cube Edit Properties page to add and edit cube properties:

➤ To add or edit a cube node: 1 Do one of the following:

● To add a cube node, click the Cube button .

● To edit an existing cube node, select the cube node and click the Edit button .

The Cube Edit Properties page is displayed.

2 On the Cube Edit Properties page, enter or change the following settings:

● Name - The display name of the cube; for example, Basic

● Description - A brief description of the cube; for example, Basic Cube 3 Do one of the following:

● Click OK to create or change the cube node and return to the node tree on the Data Source Setup page.

● Click Cancel to return to the node tree on the Data Source Setup page without creating or changing the cube node.

4 Click the Save button, .

132 XML Setup Tool Deleting Cube Nodes A necessary part of administrating a data source is removing unnecessary OLAP cube nodes from the tree. To delete a cube node: 5 From the node tree on the Data Source Setup page, select the cube node you want to delete.

6 Click the Delete button, .

7 Click the Save button, . The cube node is deleted permanently.

Drill Through XML Setup You use drill through to navigate from the summarized and calculated data stored in an OLAP data source to detailed data stored in a relational data source. Drill through queries are written in SQL. OLAP databases are optimized for analysis of summary data, but summary data is insufficient for many applications. You can implement drill through in those applications to drill from OLAP summary data to supporting or detailed transactional data in a relational database. For example, you might use an OLAP data source to analyze retail sales for the first quarter in the Eastern region. Detailed data, such as a list of customers who purchased a particular product in a particular size, is not used during the normal course of analyzing business performance. However, as you analyze sales results, you may want to view this detailed information using the drill through function. To use the Drill Through tool, you need to understand the following:

● The basic concepts, features, and tables of your selected data source. For example, if you are using Oracle, you need an understanding of Oracle schema and administrative tasks.

● How to set up JDBC pooling for your relational data source. For more information, refer to the relevant section on creating and configuring a JDBC data source in the application server chapters of the Hyperion System 9 BI+ Application Builder J2EE Installation Guide.

The following procedures will guide you through the process of creating a drill through:

● Accessing the Drill Through Setup

● Managing Drill Through Mappings

● Defining the WAA Drill Through Source

● Defining Drill Through Targets

● Defining Drill Through Queries

● Defining Global Mappings

Drill Through XML Setup 133 For additional information regarding drill through XML setup files, see “Setting Up Relational Data Sources” on page 279.

Accessing the Drill Through Setup You access the Drill Through tool from the Application Builder Administration Tools home page.

➤ To access the Drill Through tool. 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 From the tools menu, select XML Setup. 4 Click Drill Through. The Drill Through Setup page is displayed:

Managing Drill Through Mappings Accessing the Drill Through tool displays the Drill Through Setup page, which shows the drill through tree. The drill through tree is the hierarchical view of the components required to establish the WAA drill through mappings. You use the Drill Through tool for three specific tasks:

● Defining the WAA Drill Through Source

● Defining Drill Through Targets

● Defining Drill Through Queries

● Defining Global Mappings

134 XML Setup Tool A WAA drill-through navigates from an OLAP data cell to corresponding data in a relational data source.

Defining the WAA Drill Through Source When you set up a drill through, your first task is to define the OLAP data source. You can edit the source definition for an existing drill through.

➤ To create or edit a source definition: 1 On the Drill Through Setup page, do one of the following in the drill through tree:

● To create a new data source definition, click the Source button, .

● To edit an exiting source definition, select the source and click the Edit button, . A page that shows only OLAP data sources in the drill through tree is displayed. 2 Select an OLAP data source in one of these ways:

● To use the data source tree as the data source, which is the default, click Use Data Source Tree.

● To set up a direct OLAP connection to a different source, click Use Direct Connection to display the Select Source page.

a. Select one of the following connection types:

❍ Local - this is a connection to a data source on the local computer.

❍ Remote - this is a connection to another computer. b. Provide the following data source connection information:

❍ Server - the name of the server

❍ Schema - the name of OLAP cube schema

❍ Cube - the name of the OLAP cube

Drill Through XML Setup 135 ❍ Remote Server - the name of the remote server (remote connection type only)

❍ Driver - select a driver from the list of available drivers

❍ Connection Parameters - parameters that set specific conditions for the connection

❍ User ID - a valid authorized user

❍ Password - a valid password for the user ID 3 Click OK to return to the Drill Through Setup page. 4 On the Drill Through Setup page, select one of the following to expand the drill through tree:

● Global Mapping

● Global Region

Defining Drill Through Targets When you set up a drill through, you must define its target, which is the relational database that contains the detail data the drill through will access. You can edit the target definition of an existing drill through.

➤ To select or edit a target definition: 1 On the Drill Through Setup page, do one of the following in the drill through tree:

● To define a target for a new drill through, select a source node and click the Target button,

.

● To edit the target definition for an existing drill through, select a target node and click the

Edit button, . The Select Target page is displayed:

136 XML Setup Tool 2 Enter the following information in the text boxes:

Text Box Information

Id A unique ID for the target

Name The name of the target node

Description A brief description of the target node

3 Select a source node from the tree.

4 Click the OK button, , to return to the Drill Through Setup page.

5 Click the Save button, .

Defining Drill Through Queries After you define the source and the target for a new drill through, you complete the process of creating the drill through by defining the drill through query. The query specifies the connection between the source and the target. You can edit a query for an existing drill through.

➤ To define a drill through query: 1 On the Drill Through Setup page, expand the OLAP data source for the drill through in the tree.

2 Select the target node and click the Drill Through button, . The Target Query page is displayed, showing the Inclusion/Exclusion List:

Drill Through XML Setup 137 3 Click the Lookup and Add button, . 4 Do one of the following:

● To create a new query, click Create. For more information, see “Conversion Tool.”

● To edit the query of an existing drill through, select the query from the list and click the

OK button, . 5 Select a dimension from the Inclusion/Exclusion List. 6 Do one of the following:

● Select the Drillable check box. This allows all members returned by the query to be accessible to the OLAP data source.

● Clear the Drillable check box to exclude the dimension’s data from the OLAP data source.

7 Optional: Click the Look Up Selection button, , to apply the query to the Inclusion/Exclusion list.

8 Click the OK button, , to add the drill through to the Target node as a child.

9 Click the Save button, , to save the drill through query definition.

Defining Global Mappings To define a global mapping for your drill through provides a drill through that is accessible to other drill throughs for the same data source.

➤ To define a global mapping: 1 In the drill through tree on the Drill Through Setup page, select a source in the drill through tree. 2 Select the Global Mapping node.

3 Click the Edit button, , to display the Global Mapping page. 4 Click the JDBC drop down list to select the JDBC connection. 5 Select a dimension from the list. 6 Select a dimension member from the list of members and click Create. 7 Click Save to save the changes to the cube.

138 XML Setup Tool Grid Export XML Setup This tool defines the output of a cube view, query info, or grid to one of several formats: PDF, RTF, HTML, Excel, Power Point, or plain text. The following tasks provide the procedures for accessing, creating, and modifying export XML files:

● Accessing the Grid Export Setup

● Creating or Editing Grid Export XML Files

For additional information regarding grid export XML setup files, see “Setting Up Export XML Files” on page 315.

Accessing the Grid Export Setup You access the Grid Export Setup from the Application Builder Administration Tools home page.

➤ To access the Grid Export Setup: 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 From the tools menu, select XML Setup. 4 Click Grid Export. The Grid Export Setup page is displayed:

Note: For your use, a sample WAAGridExport.xml file is located in the following directory: /webapps/hab-admin/WEB- INF/classes/com/hyperion/waa/utility/core/export/. is the drive and directory where your application server is installed with Application Builder.

Grid Export XML Setup 139 ➤ To locate and edit the sample WAAGridExport.xml file: 1 In the path text box of the Grid Export Setup page, perform one of the following:

● Type in the path to the sample or a customized WAAGridExport.xml.

● Click the Browse button to navigate to the sample or a customized WAAGridExport.xml. 2 Click the Load button. The Grid Export Setup page is displayed with the XML file in the list.

Creating or Editing Grid Export XML Files

Note: This section assumes that you are on the Grid Export Setup page and have located where you want to put a Grid Export XML file.

➤ To create or edit a grid export XML file: 1 Perform one of the following: a. On the Grid Export Setup page, click Create grid export. The Grid Export Setup page is displayed without pre-existing parameters. b. On the Grid Export Setup page, select an existing XML file, and click Edit. The Grid Export Setup page is displayed, possibly with pre-existing parameters.

2 Optional: Click Default XSLT Parameters. The Edit Properties page is displayed. a. Enter a parameter name into the first text box. Example: PageWidth. b. Enter a value that the parameter is equal to, in the text box. Example: 80. c. Click the Add button. d. Repeat steps a-c until all of the desired parameters are entered into the XSLT parameters table for the grid you are exporting.

140 XML Setup Tool e. Click OK. 3 Click Create to edit the properties of the export definition. The Edit Properties page of the export definition is displayed.

Note: The fields that contain a red asterisk adjacent to the property icon, are required fields.

4 Provide the following values for the export definition properties:

● Name - Enter a name for the export definition. Example: 2002Actuals

● Type - Select a file type of XSLT, PDF, RTF, or Debug. Example: RTF.

● MIME Type - Select a MIME type from the drop down list. Example: text/rich text.

● XSLT File - Type in a relative or absolute path or look up an existing XSLT file. Example: WAAGridToRTF.xslt 5 Optional: Enter the name and value of any additional XSLT parameters, and click Add after each. Example: PageWidth name equals 80 (characters) value. 6 When all required properties are set and any additional parameters are defined, click OK. The grid export definition is displayed in the list on the Grid Export Setup page. 7 Click Save As. The Save page is displayed.

Grid Export XML Setup 141 8 In the Name text box, append a name for the XML file to the path. 9 In the Description text box, enter a brief description of the grid being exported. 10 Click OK. The XML file is added to the list of Export Grid XML files.

Single Sign-on XML Setup Single sign-on is the ability of a user to access multiple Hyperion applications after logging on only once. The user is externally authenticated the first time he logs in. External authentication means that the user login information needed by Hyperion applications is stored outside the applications. The information is maintained in a central authentication directory, such as Lightweight Directory Access Protocol (LDAP) Directory, Microsoft Active Directory, or Windows NT LAN Manager. To enable single sign-on between Hyperion applications that launch one another, you must use a single XML configuration file that is shared by multiple product installations. For setup information regarding single sign-on, see the “Using Single Sign-on” on page 41. This tool configures a Application Builder single sign-on XML hab-samples file, called WAACss.xml. You use the following procedures for managing the single sign-on XML file:

● Accessing the Single Sign-on Setup

● Creating or Editing Single Sign-on XML Files

Accessing the Single Sign-on Setup You access the Single Sign-on Setup from the Application Builder Administration Tools home page.

➤ To access the Single Sign-on Setup: 1 Start Application Builder to display the Application Builder Launch Page. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 From the tools menu, select XML Setup. 4 Click Single Sign-on. The Single Sign-on Setup page is displayed.

142 XML Setup Tool Figure 23 Single Sign-on Setup page

Note: For your use, a sample WAACss.xml file is located in the following directory: /webapps/hab-admin/WEB-INF/classes/ where is the drive and directory where your application server is installed with Application Builder.

➤ To locate and edit the sample WAAcss.xml file: 1 On the Single Sign-on page, in the Directory on server to look for text box, specify a path to the sample or customized WAACss.xml in one of the following ways:

● Type the path.

● Click the Browse button to navigate to the file. 2 Click the Load button. The Single Sign-on Setup page is displayed with the XML files in the list.

Creating or Editing Single Sign-on XML Files The following steps are required before implementing external authentication and single sign- on with Hyperion applications. 3 Decide how you will implement the security platform: from an application, or from an application server. 4 Decide which of the supported authentication providers, on which platforms, to make available in the security realm. See Table 7 for information about authentication providers and platforms. Table 7 Supported Authentication Providers and Platforms

Lightweight Directory Microsoft Active Access Protocol (LDAP) NT LAN Manager (NTLM) Directory

Windows NT 4.0 X X X

Windows 2000 X X X

Single Sign-on XML Setup 143 Table 7 Supported Authentication Providers and Platforms

Lightweight Directory Microsoft Active Access Protocol (LDAP) NT LAN Manager (NTLM) Directory

Windows XP X X X

UNIX X X - Requires installation of X NTLM Remote Server

5 If you are implementing security using an NTLM provider and are using a UNIX system as the client application computer, ensure that the NTLM remote server is installed on a Windows NT or Windows 2000 server. Install the NTLM remote server from the Hyperion application’s installation software.

Note: This section assumes that you are on the Single Sign-on Setup page and have located where you want to put a Single Sign-on XML file.

➤ To create or edit a single sign-on XML file: 1 On the Single Sign-on page, choose one of the following:

● To create a Single Sign-on XML file, click Create Single Sign-on.

● To edit a single sign-on XML file, select an existing file and click Edit. The Domain Single Sign-on Setup page is displayed. 2 On the Domain Single Sign-on Setup page, take one of the following actions:

● To create a domain, click Create. The Edit Properties page is displayed.

● To edit a domain, select the domain and click Edit. The Edit Properties page is displayed.

● To reorder the domain search, select a domain and click the corresponding arrow, then click Save. The search order enables the external authentication mechanism to access multiple providers in a sequential manner.

● To delete a provider, select the provider and click Delete. 3 Provide the following values for the domain definition for one of the following providers:

Note: The fields that contain a red asterisk adjacent to the property icon are required fields. For more information about setting up Secure Sockets Layer (SSL) protocol, please see the documentation for your directory server or JRE or both.

● NTLM

❍ Name - Enter a name for the provider definition. Example: HAB4

❍ Trusted - If a password is not present or required in the token generated upon user authentication, set Trusted to True. If a password is part of the token, set Trusted to False. If the entire section including the tags is deleted, the default value of true is used.

144 XML Setup Tool ❍ Max Size - Enter the desired maximum number of entries that can be returned in a query. Example: 200.

❍ Domain - Enter the name of the NTLM domain.

❍ Remote Server - Enter the name of the NTLM server.

● Lightweight Directory Access Protocol (LDAP) or Microsoft Active Directory server (MSAD)

❍ Name - Enter a name for the provider definition. Example: HAB4.

❍ Trusted - If a password is not present or required in the token generated upon user authentication, set Trusted to True. If a password is part of the token, set Trusted to False. If the entire section including the tags is deleted, the default value of true is used.

❍ Max Size - Enter the desired maximum number of entries that can be returned in a query. Example: 200.

❍ URL - Enter the URL that specifies the location of the LDAP or Active Directory provider.

❍ User DN - Enter the user name Directory Node (DN) from a user account that has read-only access to the directory stores. To provide anonymous access, do not enter a name.

❍ Password - Enter the password from a user account that has read-only access to the directory stores.

❍ Authentication Type - Enter the authentication type. For example, simple.

❍ Authentication Protocol - Enter the value that corresponds to any additional security protocol you are using for secure data transmission to and from the authentication provider. The only value for this is ssl. If you are not using Secure Sockets Layer, leave this value empty.

❍ Identity Attribute - Enter a value to match an attribute in the directory that uniquely identifies entries. For example, the attribute may be DN, or a customized attribute such as employee_ID, or any other attribute commonly used in the directory nodes of users and groups. The default is dn.

❍ User URL - Enter the information that indicates the branch in the directory server that contains user entries.

❍ User Login Attribute - Enter a value to match an attribute in the directory that uniquely identifies user entries. The attribute may be part of the DN, such as cn or uid, or a customized attribute, such as employee_ID, or any other attribute commonly used in the directory nodes of users.

❍ User First Name Attribute - Enter the first name to match the attribute associated with first-name entries in the directory.

❍ User Surname Attribute - Enter the last name to match the attribute associated with last-name entries in the LDAP directory.

❍ User E-mail Attribute - Enter the e-mail address entry to match the attribute that is actually mapped to e-mail addresses stored in your corporate directory.

Single Sign-on XML Setup 145 ❍ User Object Class - Enter values if your corporate directory schema requires specialized object classes to describe users. The provided (default) user object classes for LDAP are person, organizationalPerson, and inetOrgPerson. The provided (default) user object classes for Active Directory are person, organizationalPerson, and user.

❍ Group URL - Enter values if your corporate directory schema requires specialized object classes to describe the branch in the directory server that contains user entries.

❍ Group Name Attribute - Enter a value to match an attribute in the directory that uniquely identifies group names.

❍ Group Object Class - Enter values if your corporate directory schema requires specialized object classes to describe groups. 4 When all required properties are set and any additional parameters are defined, click OK. The single sign-on definition is displayed in the list on the Single Sign-on Setup page. 5 To save your changes, take one of the following actions:

● After editing an XML file, click OK.

● After creating an XML file, click Save As or Save. The Save page is displayed.

a. In the Name text box, append a name for the XML file to the path. b. In the Description text box, enter a brief description of the XML file. c. Click OK. The XML file is added to the list of single sign-on XML files.

Task Registry Setup A task executes a piece of code that performs a specific functionality. A developer can create custom tasks, then use this tool to register the custom tasks and assign them names. For an overview of the task registry, see “Initializing the Task Registry” on page 202 and “Using the Task Registry” on page 225. The WAATaskRegistry.xml file is the default task registry file. The task registry XML file contains name and value pairs that define a task name and a Java class respectively. The task name appears in the task user interface. The Java class contains a list of Java classes which define individual tasks. Following is the default WAATaskRegistry.xml file:

146 XML Setup Tool "-//Hyperion Solutions Corporation//DTD Atf Task Registry Manager 7.0//EN" "contextroot:/WEB- INF/dtds/com/hyperion/atf/services/task/AtfTaskRegistryManager_7_0.dtd">

For example, the General tasks that appear on the user interface are listed in AtfTaskProvider.java. The following snippet from AtfTaskProvider.java lists 3 java classes that define the Conditionals, Database Metadata, and Database tasks public AtfTaskProvider() { m_rastClassName = new String[] { "com.hyperion.atf.services.task.AtfConditionalsTask", "com.hyperion.atf.services.task.AtfDatabaseMetaDataTask", "com.hyperion.atf.services.task.AtfDatabaseTask",

The following example describes how to use this tool to add a custom task to the task registry. For example, if you created a custom e-mail task in the CustomEmailTask.java file, and you want it to appear as My E-mail (Custom Task) on the User Interface, you would define a java class, such as NewTaskList.java that lists the CustomEmailTask.java file. Then use the task registry tool to enter the name = My Email(Custom Task) and value = NewTaskList. The NewTaskList.java file would contain the following code: package com.hyperion.atf.services.task; /** * This class provides a task provider. A task provider specifies the task * classes that are available for task definitions. */ public class NewTaskList { public AtfTaskProvider() m_rastClassName = new String[] { "com.hyperion.atf.services.task.CustomEmailTask" ) }

Note: For examples of tasks see the Java classes listed in AtfTaskProvider.java or WAATaskProvider.java.

The following figure shows the resulting user interface, in a task definition builder:

Task Registry Setup 147 Figure 24 Task Registry

➤ To create a task registry XML file: 1 From the XML Setup tab, select the Task Registry tab. 2 Click the Create Task Registry button at the bottom of the page. 3 Enter the Name and Value pairs. 4 Click the Add icon to add the name and value pair to the task registry.

148 XML Setup Tool Chapter Conversion Tool 6

The repository conversion tool enables you to migrate the Application Builder 2.5 release of your repository to the 3.0 and higher release of the Analysis Tools Framework (ATF) repository.

Note: A conversion is not necessary if you migrate the Application Builder 3.0 release of your ATF repository to the 7.0 release of the ATF repository.

The Analysis Tools Framework is a lightweight services framework that provides integrated authorization security and repository services. Topics covered in the Conversion Tool are:

● Accessing the Conversion Tool

● Converting a Repository

For additional information on the ATF repository, see “Using the ATF Repository” on page 29. During the ATF repository conversion process there are a number of activities performed that are silent to the administrator. A group called HAB_USER is created. Users that have private views or queries are added to the group during conversion. The HAB_USER group is assigned create, read, list and write special permissions to folders, and special permissions to create, delete, read, list, write, change owner and change permission on OLAP views and relational queries. Several directories are created in the repository. The following table lists the directories and their purpose: Table 8 Additional Application Tools Framework Repository Directories

Directory Name Contents

/hyperion The parent directory that stores any Hyperion related data.

/hyperion/olap Stores all converted public and group owned OLAP views.

/hyperion/relational Stores all converted public and group owned relational queries.

/users/ Stores all private OLAP views and relational queries, is the owner/user.

/system A hidden folder that contains objects which are used by the system and are not to be modified

Conversion Tool 149 Table 8 Additional Application Tools Framework Repository Directories

Directory Name Contents

system/datasource/olap A hidden folder that stores all OLAP data sources defined in the WAADataSource.xml file.

system/datasource/relational A hidden folder that stores all relational data sources defined in the WAADataSource.xml file.

Accessing the Conversion Tool You access the Conversion tool from the Application Builder Administration Tools home page.

➤ To access the Conversion Tool: 1 Start Application Builder to display the Application Builder launch screen. 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 Click Conversion. The Conversion page is displayed.

Converting a Repository There are two different ways to establish the location of a repository. The default method is by using the Java Naming and Directory Interface (JNDI) and entering the data source. The other method is by using a direct connection to your database.

➤ To conver t a JNDI repositor y : 1 On the Conversion page, select the JNDI option button and enter your data source.

150 Conversion Tool Note: Steps 2 and 3 are only required for release 2.5 repositories that are built in WebSphere.

2 Enter a valid User ID, if necessary. 3 Enter a valid password, if necessary. 4 Click Run. The repository is converted.

➤ To convert a repository using a direct connection: 1 On the Conversion page, select the brand of your release 3.0 repository:

● Microsoft Sql Server

● MySQL

● Oracle

● DB2 The Conversion page is displayed with additional fields. 2 Enter the following information into the form:

● Server - The name of the server on which the database resides

● Database - The name of the database

● User ID - A valid user name, the default is habdbuser

● Password - A valid password, the default is habdbuser

● Connection - For display purposes only, no input required 3 Click Refresh. The direct connection string is displayed in the Connection box. 4 Click Run. The repository’s conversion process is displayed.

Converting a Repository 151 152 Conversion Tool Chapter Security Tool 7

The Security Tool provides the administrators with the ability to administer users in the ATF repository. From this tool you have the capability of adding, editing, or deleting users, groups, and object types in the ATF repository. From the Security Tool you are able to set or modify permissions to users, groups, and object types down to permissions and special permissions. This tool includes specific topics such as:

● Accessing the Security Tool

● Managing Users

● Managing Groups

● Managing Object Types

Within managing the users, groups, and object types topics are the more specific procedures for administrating each. You add users and groups in your Web Application server before adding them to the repository for both external authentication and single sign-on, or J2EE authentication. The user names in your Web Application server must match the user names in the ATF repository.

Note: If you enter a user name in the repository and it does not exist as a user in the Web application server, the user will fail J2EE authentication.

For WebLogic, WebSphere and Sun ONE, you create users through the specific Web App server console. For Apache Tomcat, you add users by editing the tomcat-users.xml file. The tomcat-users.xml file is located in \conf\. is the location where Jakarta TomCat is deployed. For additional information regarding security, specifically related to single sign-on, see the “Using Single Sign-on” on page 41.

Accessing the Security Tool You access the Security tool from the Application Builder Administration Tools home page.

➤ To access the Securit y Tool: 1 Start Application Builder to display the Application Builder launch screen.

Security Tool 153 2 Click Administration Tools to display the Application Builder Administration Tools home page. 3 Click Security.

Managing Users Managing users consists of procedures for creating or editing, setting permissions, or deleting users. The following procedures will guide you through the process of managing users:

● Creating or Editing Users

● Deleting Users

● Setting User Permissions and Special Permissions

Creating or Editing Users When first accessing the Security Tool, the Users page is displayed with the list of current users.

➤ To create or edit a user: 1 On the Users page, perform one of the following:

● Select an existing user and click Edit.

● Click Create. The User page is displayed. 2 In the Name text box, enter or edit a name for the user. 3 In the Password text box, enter or modify the password for the user. 4 From the Available Groups column, select the group to which you want the user to belong by using the

Select, , button, move the group to the Selected Groups column. You can use the Select, Deselect, Select All, and Deselect All buttons to move objects from one column to the other.

Note: The Everyone group is required and cannot be removed from the Selected Users column.

5 Click OK. The user is created and the Users page is displayed showing the new user in the list of users.

Deleting Users

➤ To delete a user from the repository: 1 From the Users page of the Security Tool, select the user to delete. 2 Click Delete.

154 Security Tool The delete confirmation is displayed. 3 Perform one of the following:

● Click Cancel to discontinue deleting the user. The user remains in the user list.

● Click OK to delete the user. The user is removed from the user list.

Setting User Permissions and Special Permissions User permissions are a set of specific permissions that apply to similar users. Special permissions are individual actions that can be granted or withheld from individual users. the following procedure gives you the steps to set a user’s authorization level in your application.

Note: The user performing the following procedure must have Change Permissions or Super Admin group privileges. Click Cancel to terminate the operation at any time.

➤ To set a user’s permissions: 1 In the User’s page of the Security Tool, select a user. 2 Click Set Permission. The user Permissions page is displayed. 3 Select all necessary permission choices for the user. 4 Click Special Permissions. The Special Permissions page is displayed. 5 Select the appropriate special permissions to apply to the user. 6 When you make all of the permission choices, click OK. The Permissions page is displayed. 7 Click OK. The Users page is displayed and the changes are made to the repository.

Managing Groups Groups are containers of users with similar permission requirements that can be applied to all users in the group. Changes to the permissions of a group profile affects the permissions of all users in the group, unless otherwise specifically assigned to an individual user. The procedures used to manage groups are as follows:

● Accessing Groups

● Creating or Editing Groups

Managing Groups 155 ● Setting Permissions and Special Permissions for Groups

Accessing Groups

➤ To access the Groups page: 1 Ensure that you are on the Security tool page of the Administration Tools. 2 On the Security Tool page, click Groups.

The Groups page is displayed. The hierarchical display of groups shows the users as children to each group.

Note: A user can be a member of more than one group.

Creating or Editing Groups You can create or edit groups of users and store them in the ATF repository by performing the following procedure.

➤ To create a new or edit an existing group: 1 On the Groups page, click Create.

156 Security Tool The Group properties page is displayed.

2 In the Name text box, modify the existing or type a new name for the group. 3 From the Available Users column, select the group to which you want the user to belong by using the Select

button, , move the group to the Selected Groups column. You can use the Select, Deselect, Select All, and Deselect All buttons to move objects from one column to the other.

Note: The Administrator user is a default user and should not be removed.

Setting Permissions and Special Permissions for Groups

➤ To set permissions and special permissions to a group: 1 In the Groups page of the Security Tool, select a group from the list to set the permissions. 2 On the Groups page, click Set Permissions. The Permissions page is displayed.

Managing Groups 157 3 Select the permissions you want to apply to the group. 4 Click Set Special Permissions. The Edit Special Permissions page is displayed.

5 Check the boxes of the special permissions you want to apply to the group. 6 When you make all of the permission choices, click OK. The Permissions page is displayed. 7 Click OK.

158 Security Tool The Groups page is displayed and the changes are made to the repository.

Managing Object Types The Administration Tool provides administrators with the capability to manage permissions for all of the objects in the repository, including the following object types:

● OLAP View- Defines an OLAP view object type. You can create an instance of this object using the useOlapView tag.

● Relational View - Defines a relational view object type. You can create an instance of this object using the useRelationalView tag.

● OLAP Data Source - Defines an OLAP data source object type. This is created when the data source xml file is initialized or synchronized.

● Relational Data Source - Defines the relational data source object type. This is created when the data source XML file is initialized or synchronized.

● Scheduled Task Definition - Defines a scheduled task definition object type. You can create an instance of this object using the Administration Tools or the task tags.

● Task Definition - Defines a task definition object type. You can create an instance of this object using the Administration Tools or the task tags.

The following sections provide the procedures to set object type permissions:

● Setting Special Permissions for Object Types

● Setting Object Type Permissions

Setting Special Permissions for Object Types You can apply special permissions to your object types by performing the following procedure.

➤ To set special permissions for an object type: 1 On the Security Tool page, click Object Types from the menu. The Object Types page is displayed.

Managing Object Types 159 2 Select an object type from the list. 3 Click Set Special Permissions. The Edit Permission page is displayed.

4 From the drop down list choose one:

● User (Default)

● Group 5 Select a user or group from the list that is displayed. 6 Check the appropriate permissions to apply to the group from the following list:

● Change Owner - In conjunction with Change Permissions, the user is permitted to change the owner of an object in the repository.

160 Security Tool ● Change Permissions - This allows a user to change the permissions of other users.

● Create - This allows the user to add objects to the repository.

● Delete - This grants the permission to delete objects from the repository.

● List - This grants the permission to call a list of the objects in the repository.

● Read - This gives a user read permissions.

● Write - This allows the user to update objects in the repository. 7 Click OK. The Object Types page is displayed.

Setting Object Type Permissions

➤ To set the permissions for an object type: 1 On the Security Tool page, click Object Types from the menu. The Object Types page is displayed.

2 Select an object type from the list. 3 Click Set Permissions. The Edit Permission page is displayed.

Managing Object Types 161 4 From the drop down list choose one:

● User (Default)

● Group 5 Select a user or group from the list that is displayed. 6 Check all applicable permissions from the list of permissions. 7 Click OK. The Object Types page is displayed.

162 Security Tool Chapter Managing Shared Services 8 Models Tool

This chapter explains Shared Services as it is implemented in Application Builder. This document contains the following topics:

● “Overview” on page 163

● “Configuring Application Builder for Shared Services” on page 164

● “To enable Guided Analysis links in a relational view or Olap view:” on page 167

● “Setting Up Guided Analysis” on page 166

● “To enable Guided Analysis links in a relational view or Olap view:” on page 167

● “About Managing Metadata” on page 167

● “About Sharing Metadata” on page 168

● “About Sharing Data” on page 168

● “Working with Projects” on page 168

● “Working with Models” on page 173

● “Sharing Data” on page 188

Overview Shared Services provides a database, organized into projects, in which applications can store, manage, and share metadata models. A model is a file or string of content that contains an application-specific representation of data. Models are of two types, dimensional hierarchies and non-dimensional application objects. Dimensional hierarchies include information, such as entities and accounts. Non-dimensional application objects include security files, member lists, calculation scripts, and web forms. The process of copying a model from local, or application, storage to storage in the Shared Services is known as exporting the model. The process of copying a model from the Shared Services to local storage is known as importing the model.

Managing Shared Services Models Tool 163 The following table lists the high level tasks that you can perform with Shared Services and the built in functionality of Application Builder:

Task For Information

Guided Analysis “To enable Guided Analysis links in a relational view or Olap view:” on page 167

Importing and Exporting Models “Working with Models” on page 173

Versioning “Tracking Model History” on page 182

The following table lists the high level tasks that you can perform with Shared Services if you customized your applications built with Application Builder:

Task For Information

Managing Metadata “About Managing Metadata” on page 167

Sharing Metadata “About Sharing Metadata” on page 168

Sharing Data “About Sharing Data” on page 168

Configuring Application Builder for Shared Services Hyperion System 9 Shared Services™ maintains dynamic information for all registered products. You use Application Builder with Shared Services to perform the following tasks:

● To import, export and track versions of relational views and OLAP views. For example, you can import views into Shared Services from a development environment and them export them into a production environment. Additionally Shared Services maintains full version control of all the views it stores.

● To create guided analysis links. Guided analysis functionality enables links from OLAP or relational views to other Hyperion reports or views.

The following procedures presumes that you have installed Application Builder and Shared Services installed.

Accessing Manage Models You register Application Builder in the Administration Tools, in the Manage Models Tool.

➤ To access the Manage Models Setup Tool: 1 Start Application Builder to display the Application Builder Launch screen. 2 To display the Application Builder Administration Tools home page, click Administration Tools. 3 Click Manage Models. The Registration page opens.

164 Managing Shared Services Models Tool From this window the following functionality if available:

● “Registering Application Builder” on page 165

● “Working with Models” on page 173

Registering Application Builder Before you can access Shared Services functionality, you must register Hyperion System 9 Application Builder with Shared Services.

➤ To register Application Builder with Shared Services: 1 Start Application Builder to display the Application Builder Launch screen. 2 To display the Application Builder Administration Tools home page, click Administration Tools. 3 Click Manage Models. The Registration page opens. 4 Provide the following product information:

● Register Product - Click to register a product with Shared Services; for example, Application Builder.

● Register Server - Click to register a guided analysis server. See “Information to Register a Guided Analysis server:” on page 165.

● Information Stored with the Product:

❍ Hyperion Shared Services Server - the name of the server where Shared Services server resides

❍ Hyperion Shared Services Port - the name of port where the Shared Services server port resides

● Information for the Shared Services engine:

❍ Product Code - Code name of the product you wish to register

❍ Product Version - Version of the product

❍ Full Product Name - Name of the product

❍ Product Description - Description of the product

❍ Default Project - Project name where exported models will go. Since there can be multiple projects for one product, Shared Services needs to know the project name.

❍ Enter one of the following Single sign-on options:

❑ If you are using single sign-on functionality, select the Use Single Sign-on check box.

❑ If you are not using Single Sign-on to register your product, de-select the Use Single Sign-on check box. You must enter the User ID and Password of your product.

● Information to Register a Guided Analysis server:

Configuring Application Builder for Shared Services 165 ❍ Product Server URL - URL of the product your are registering; for example: C:\Program Files\Hyperion\ApplicationBuilder\7.0.0\

❍ Product Instance Name

❍ Properties File: WAAGuidedAnalysis.Properties - File name referenced in web.xml. Name of the file that holds the URLs of the Products used for Guided Analysis. This web.xml reference must match the name in the -admin\web-inf\classes directory. 5 Click OK.

Setting Up Guided Analysis Guided analysis functionality enables links from OLAP or relational data to other Hyperion reports. For example, you can easily navigate from any Application Builder report to related financial reports (rendered in HyperionReports™), unstructured content (using Hyperion Central™) and interactive out-of-the-box analysis (rendered in Hyperion Analyzer™).

➤ To enable Guided Analysis, you must perform the following set-up tasks: 1 Configure the users that set-up and implement guided analysis, as single sign-on users. Single sign-on users have access to Shared Services which maintains product registration information needed to implement guided analysis. For detailed instructions on how to set-up single sign-on users, see the “Using Single Sign-on” on page 41.

Note: Single sign-on users are automatically added as Shared Services users the first time they access Shared Services.

2 You can use Shared Services or a properties file to register products for use with guided analysis. The advantage to using Shared Services is that all registered products are maintained dynamically. So if a product is added or changed Shared Services is automatically updated and Hyperion System 9 Application Builder automatically has access to that information. If you use a properties file, the other product’s must set up property files and you must access them. If a property file changes, you will not know unless you re-access it.

● To use Shared Services, do the following:

❍ Install and configure the Shared Services server that maintains product registration information. For detailed instructions, see the Hyperion System 9 Shared Services Installation Guide.

❍ Register your product in Shared Services, using the Manage Models tool in the Administration Tools. For detailed instructions, see “Registering Application Builder” on page 165.

● To use a properties file, do the following:

❍ Set-up the WAAGuidedAnalysis.properties file.The following snippet displays a listing of the server name and URL of a linked product:

166 Managing Shared Services Models Tool RelatedContent.Server.Name.0=Hyperion Application Builder on Server# RelatedContent.Server.URL.0= http://hostname:port- admin/WAARepositoryContentServlet?sso_token=$SSO_TOKEN$&path=%2f where hostname:port is the computer name or IP address and port of the related content server.

Setting up Guided Analysis Links Guided Analysis links access to other Hyperion Product reports from an Olap view or relational view.

➤ To enable Guided Analysis links in a relational view or Olap view: 1 Start -Admin and click Repository Objects. 2 Select a relational view or Olap view and click Edit. The Edit View screen is displayed. 3 Click Guided Analysis. The Guided Analysis screen is displayed. 4 In the Guided analysis window, perform one or more of the following:

● To link to a view, from the Guided Analysis section, select a view and click the Add to Guided Analysis icon to move the view to the selected content box.

● To add a URL to the Selected Content section, in the URL section, enter a URL and click the Add to Guided Analysis icon.

● To see the details of each selected content, select it in the Selected Content section. The Details section displays the label, default action, and available action.

About Managing Metadata Shared Services stores metadata models belonging to applications. The Shared Services provides a separate application project for each application. Shared Services provides basic management functionality for models, such as

● Version tracking

● Access control

● Synchronization between models in the application and corresponding models in the Shared Services

● Ability to edit model content and set member properties of dimensional models

● Ability to rename and delete models

See “Working with Models” on page 173 for detailed information about models.

About Managing Metadata 167 About Sharing Metadata Shared Services also enables applications to share common models with other applications and products. The mechanism to support sharing of models is a common shared project. Rather than create a web of connections among multiple applications, each application stores its common models in a common shared project. The administrator must first share the application with the common project. After this is done, the administrator selects the application models to share. Models can be private (non-shared) or they can be shared. The ability to create filters, which identify the parts of a model to import, enables the sharing of models between applications when models are not completely identical. See “Working with Shared Projects” on page 169 for the basic workflow of setting up and implementing sharing among applications.

About Sharing Data In addition to enabling the sharing of metadata among applications, Shared Services enables the movement of data between applications. The means to move data are data integrations that define the data to be moved from a source project to a destination project. Data integrations can be run manually or scheduled to run at a specific time. Data integrations can also be placed in groups and run sequentially. Before data can be moved between projects, the models for both the source and destination project must be synchronized between the Shared Services and the application. See “Sharing Data” on page 188 for details about moving data between applications.

Working with Projects Metadata models are stored in project directories in the Shared Services. The Shared Services has two types of projects, application projects and shared projects. Application projects are used by applications to store their models. Shared projects enable applications to share models with other applications.

Working with Application Projects Shared Services manages models at the application level. Each application that is registered with Shared Services has a corresponding project in the Shared Services in which it stores its Shared Services models. An application has exclusive use of this project, which is known as a application project. Each application has access to a single application project. To put a local copy of a model under control of Shared Services, you export the model to the application directory in the Shared Services. To make a model in the Shared Services available to an application, you import the model to the application.

168 Managing Shared Services Models Tool Shared Services provides project management capabilities to manage models. For example, you can perform the following tasks, among others:

● Track model versions

● Control access to models

● Edit member properties in dimensional models

● Synchronize models between the application and the Shared Services

See “Working with Models” on page 173 for detailed information about how to manage models in application projects.

Working with Shared Projects Shared projects enable you to share models among applications and with other products. The Shared Services uses common shared projects to support sharing models. A common shared project defines the information that is common between two or more applications. Within a common shared project, an application can have private models or shared models. The following example outlines the process for sharing models between applications or products: 5 App1 exports its models to Shared Services. The models are stored in the project for App1 in the Shared Services. 6 App1 selects a project to share with, for example, Common. 7 App1 designates specific models for sharing. When a model is shared, it is available for use with other applications. 8 App2 selects the Common.Shared project. 9 App2 selects models in the shared project. The shared models are displayed in the Model Listing view of the application project for App2. A shared model does not physically reside in the application’s private project, but rather resides in the shared project associated with the application’s project. The application project contains a link to the shared project, but you can perform actions on a shared model as if it did physically reside in the application project. The reason for the ‘physical’ reference is what heppens when you stop sharing. However, I’ll probably remove it per janette.

A project that is shared can have both private models and shared models in the Model Listing View. Private models are for the exclusive use of the application associated with the project. Shared models are available to any application that shares with the same shared project. Filters enable you to designate which part of a shared model to use in an application. In this way, you can share models with other applications if the models share a core set of common members; the models are not required to be identical. When you import a shared model, the filter removes members that you have not designated as common. See “Filtering the Content of Models” on page 181 for information on creating filters.

Working with Projects 169 Managing Projects Shared Services enables you to create, rename, and delete projects. You can manage both application projects and shared projects.

Creating Projects Shared Services enables you to create both application projects and shared projects. An application uses one project exclusively. For many products, an application project is created for an application by the registration process. Products that use the registration process to create an application project do not need to manually create an application project. The ability to create an application project manually is provided for products that do not implement automatic project creation. An application can use multiple shared projects to store models. Shared Services provides one shared project called Common. Other shared projects must be created by application users or administrators.

➤ To create a project: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. A list of projects is displayed. 3 Click Add. 4 In the Project Name field, type a name for the project. 5 Select Shared to create a shared project, or leave Shared blank to create an application project. 6 Click Create to create the project or Cancel to cancel the operation.

Renaming Projects You can rename an application project, but not a shared project. You need Manage permission to rename a project.

➤ To rename a project. 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. A list of projects is displayed. 3 Select the project to rename and click Rename. 4 Type a new name for the project. 5 Select Rename to rename the project or Cancel to cancel the operation.

170 Managing Shared Services Models Tool Deleting Projects You can delete a project only when it contains no models. You need Manage permission to delete a project.

➤ To delete a project: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. A list of projects is displayed. 3 Select the project to delete and click Delete.

Selecting a Shared Project To be able to share models with other applications, you must share an application project with a shared project.

➤ To select a shared project: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Share tab. A list of shared projects is displayed. 3 Select the project with which to share. 4 Click Share to begin sharing the application project with the shared project you specified.

After you have set up access to a shared project, you can designate models to share. See “Sharing Models” on page 180. You can stop sharing access to a shared project at any time. When you do so, models that are shared with the current application are copied into the application project.

➤ To stop sharing with a shared project: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Share tab. A list of shared projects is displayed. 3 Select the project with which to stop sharing. 4 Click Stop Sharing to stop sharing with the designated project.

Assigning Permissions to Projects You can assign access permissions at the project level that apply to all new models in the project. If you do not explicitly set project permissions, the default is to grant Manage permission to the owner and Admin user. All other users are denied all privileges.

Working with Projects 171 To assign access to individual models, see “Assigning Permissions to Models” on page 185.

➤ To assign permissions to projects: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. 3 Select a project and click Access.

Note: You can assign access permissions only to an application project. All users have access to a shared project, though you can restrict access on a model-by-model basis in a shared project.

You can see the permissions that have been assigned to users and groups for this project. 4 To add users or groups, click Add. The Available Users / Groups box displays users who have been authenticated as Shared Services users. If a user you want is not on this list, contact the Shared Services administrator, who can use the Shared Services Configuration Console to add authenticated users. 5 In the Available Users / Groups box, click or use Ctrl click to select users or groups to assign to this model. Press the right arrow key (>) to move the selected users and groups to the Selected Users and Groups box; or use the double arrow (>>) to move all users and groups to Selected Users and Groups.

Note: Group names are preceded by an asterisk (*).

6 Assign permissions to the selected users and groups by checking one of the Grant, Deny, or None boxes for the Read, Write, and Manage permissions. See “Permissions” on page 184 for details about the Read, Write, and Manage permissions and the Grant, Deny, and None actions that you can apply to each permission. 7 Click Add to assign the new permissions.

Editing Permissions to Projects You can edit the permissions of individual users and groups for access to projects. You must have Manage permission for a project to change permissions for it.

➤ To edit permissions to projects: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. 3 Select a project and click Access. You can see the permissions that have been assigned to users and groups for this project. 4 To edit the permissions for particular users or groups, select one or more users or groups and click Edit. The box shows the permissions currently assigned to the selected user or users.

172 Managing Shared Services Models Tool Note: The icon indicates an individual user and the icon indicates a group of users.

5 Change permissions for the selected user or group by checking one of the Grant, Deny, or None boxes for the Read, Write, and Manage permissions. See “Permissions” on page 184 for details about the Read, Write, and Manage permissions and the Grant, Deny, and None actions that you can apply to each permission. 6 Click Update to accept the changes or Cancel to cancel them.

Deleting Permissions to Projects You can delete all permissions for users and groups to the models in a project. You must have Manage permission for a project to delete access to it.

➤ To delete access to the models in a project: 1 From the Hyperion Application Builder Home page, click Manage Models. 2 If it is not already selected, select the Available Projects tab. 3 Select a project and click Access. You can see the permissions that have been assigned to users and groups for this project. 4 To delete the permissions for particular users or groups, select one or more users or groups and click Delete.

Note: When you click Delete, the permissions are immediately removed, and no warning message is displayed.

Working with Models Shared Services enables you to store and manage models in the Shared Services. The Model Listing view shows the models that are in the Shared Services.

➤ To see the Model Listing view: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab.

Figure 25 shows a sample Model Listing view.

Working with Models 173 Figure 25 Model Listing View

Note: If the current project is new, the view may show no models. Application models are not displayed in the Model Listing until you explicitly export them to the Shared Services. See “Synchronizing Models” on page 175 for information.

At the bottom of the page, the Model Listing view shows the current project and owner and the shared project for the current project. The Model Listing view lists information about each model in the Shared Services

● Model name

● Model type

● Last time the model was updated

● Whether the model is locked and who locked it

● If the model has a filter attached (indicated by the icon)

You can see only the models to which you have at least Read access. If you do not have access to a model, it is not displayed in the Model Listing view. Icons indicate where models are located:

indicates a model in the application product directory.

indicates a model in the Shared Services.

indicates a model that is in both the product directory and the Shared Services.

indicates a shared model. From the Model Listing view, you can perform any of the following operations:

● View and edit members and member properties in dimensional models. See “Viewing and Editing Model Content” on page 178.

● Filter content that is imported to an application from a shared model. See “Filtering the Content of Models” on page 181.

● Compare the latest application version of a model to the latest version stored in the Shared Services. “Comparing and Merging Models” on page 176.

174 Managing Shared Services Models Tool ● Track model history. See “Tracking Model History” on page 182.

● View model properties. See “Viewing and Setting Model Properties” on page 187.

● Rename models. See “Renaming Models” on page 179.

● Delete models.

You can synchronize the Shared Services version of a model with the application version, by importing the model from the Shared Services to the application, or by exporting the model from the application to the Shared Services. To do so, select the Sync tab. See “Synchronizing Models” on page 175. You can share a model with other applications. To do so, select the Share tab. See “Sharing Models” on page 180.

Synchronizing Models The Model Listing view displays the latest version of each model in Shared Services. Shared Services also tracks models in the application and determines whether a version of each model resides in the application only, in the Shared Services only, or in both places. When the latest version of a model resides in both the application and in Shared Services, the application and Shared Services are said to be synchronized, or in sync, with regard to that model. If a model is out of sync, you can synchronize it by importing the model to the application or exporting the model to Shared Services, depending on where the latest version resides. You need Write permission to synchronize a model.

➤ To synchronize models: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. All models in Shared Services are displayed. 3 Click Sync. Shared Services lists all models in Shared Services and in the application. The Sync Operation field provides a recommended operation to apply to each model, as follows:

● If a model exists in the application but not in Shared Services, the sync operation is Export to Shared Services. You cannot change this operation. If you select the model, when you synchronize, the specified model is copied to the Shared Services.

● If a model exists in Shared Services but not in the application, the sync operation is Import From Shared Services. You cannot change this operation. If you select the model, when you synchronize, the specified model is copied to the application.

Working with Models 175 ● If a model exists in both the application and Shared Services, the sync operation is Select Sync Operation. You can use the scroll box to select either Export to Shared Services, or Import From Shared Services. Models with Select Sync Operation have a Compare button that enables you to see the differences, if any, between the application and Shared Services versions of the model. 4 Optional: For models with Select Sync Operation, compare the latest version of the model in Shared Services to the model in the application by clicking the Compare button. The latest version of the model in Shared Services is compared to the latest version in the application. The contents of the two models are shown line-by-line in a side-by-side format. Shared Services Version refers to the model in Shared Services, Product Version refers to the model in the application. For information on resolving differences between the models, see “Comparing and Merging Models” on page 176. After you resolve the differences in a model, you are returned to the Sync Preview page. 5 Select each model that you want to synchronize. For models with Select Sync Operation, select either Export to Shared Services or Import From Shared Services, depending on whether the application or Shared Services has the latest version of the model. 6 After you select all models needing synchronization and, as necessary, specify the sync operation, click Sync to synchronize the selected models or Cancel to cancel the operation. A progress message is displayed during the sync operation. 7 To see a report of the operations that have been completed, click Report. 8 To update the message, click Refresh. 9 To return to the model listing, click OK.

Comparing and Merging Models At any time, you can compare a model in Shared Services to its corresponding version in the application. The latest version in Shared Services is compared to the model in the application. To compare different versions in Shared Services, see “Tracking Model History” on page 182. After comparing versions of a model, you can merge any differences into a new version of the model.

➤ To compare the application representation of a model with Shared Services representation of the model: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. The list of models shows the last modification date for the model in Shared Services. 3 Select the Sync tab. A list of models in Shared Services and in the application is displayed. 4 Click the Compare button next to the Sync Operation box for the model of interest.

176 Managing Shared Services Models Tool The latest version of the model in Shared Services is compared to the latest version in the application. The contents of the two models are shown line-by-line in a side-by-side format. Shared Services Version refers to the model in Shared Services. Product Version refers to the model in the product application. Color coding highlights any differences between the content of the two models, as follows:

❍ Red indicates that the highlighted text has been deleted from the model.

❍ Green indicates that the highlighted text has been inserted in the model.

❍ Blue indicates that the highlighted text has been changed. 5 Use the Next and Prev buttons to page through the model comparison if necessary. 6 Click OK to return to the Sync tab view. 7 After you understand the differences between the two versions of the model, click the Merge action button to merge the two versions of the model, or Back to return to the Model Listing view. Differences between the model are resolved automatically and a new version of the model is created. See “Merging Models” on page 177 for more information. 8 Click Save to save the merged version of the model or Back to return to the Model Listing view.

Merging Models The following matrix shows how model management resolves conflicts when comparing two versions of a model and merging the differences into a new version of the model. The Shared Services does a line-by-line comparison of the models. In the table, A denotes the existing content of a line. A1 represents a change to the line containing content A, and Deleted A indicates that the entire line containing A has been deleted from the model. A dash (–) indicates that the model did not contain a line with content A.

Table ix Merge Differences Resolution

Resolution in Merged # Version 1 Version 2 Model

1 Deleted A Changed to A1 Resolve manually

2 Changed to A1 Deleted A Resolve manually

3 Changed to A1 Changed to A2 Resolve manually

4 A Deleted A Delete A

5 Deleted A A Delete A

6 A – Insert A

7 – A Insert A

8 Changed to A1 A Update to A1

Working with Models 177 Table ix Merge Differences Resolution

Resolution in Merged # Version 1 Version 2 Model

9 A Changed to A1 Update to A1

10 A A Versions are identical

You must resolve the first three situations manually. For example, if the merge screen shows that a line has been deleted from one version and changed in another version, (cases 1 and 2), or if the same line has been changed to something different (case 3), you must decide on which version to accept. All other cases are decided automatically and a merged version is created in the Shared Services respository.

Viewing and Editing Model Content The Shared Services interface provides an editor that enables you to directly view and edit the content of models in Shared Services. You can use the editor only with dimensional mode. You need Read permission to view the content of a model. You need Write permission to edit a model. The editor enables you to manage dimension members by doing the following:

● Add a sibling or a child to a member

● Change the description of a member

● Move a member up or down in the hierarchy

● Edit dimension member properties

➤ To view or edit dimension members: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model name and click View. The dimension editor shows the members of the selected model. 4 Use the editing keys to make changes, such as adding or deleting members, or moving members up or down in the dimensional hierarchy.

Note: You can hold down the Shift key while pressing the expand or collapse button to expand or collapse all members of the hierarchy at once.

5 Click Validate to perform a simple validation check.

178 Managing Shared Services Models Tool The validation check verifies the following and lists any exceptions:

❍ That you have not created names that are too long (20 characters for Hyperion Financial Management, 80 characters for Hyperion Planning)

❍ That you have not created any duplicate names 6 Click Save to save the changes you have made and to create a new version of the model in Shared Services.

You can make changes to the settings of member properties of dimensional models and save the changes to a new version of the model.

➤ To edit member property settings: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model name and click View. The dimension editor shows the members of the selected model. 4 Select a member and click Edit. The Member Edit window provides separate tabs for properties that are unique to a particular product, for properties that are common to multiple products, and for other properties. For example, the HP tab contains properties unique to Hyperion System 9 Application Builder, the HFM tab contains properties unique to Hyperion System 9 Financial Management, and the Common tab contains properties common to Hyperion System 9 Financial Management and Hyperion System 9 Application Builder. 5 Select a tab and use the editing keys to change member property settings as desired. 6 In the Member Edit window, click Save to save the property settings you have made. 7 In the Member Edit window, click Close to close the window. 8 Click Save to save the changes you have made and create a new version of the model, or click Back to return to the Model Listing view.

Renaming Models Shared Services enables you to rename models in Shared Services. For example, you might want to rename a model if two applications want to share dimensional models that are named differently. For example, one application uses plural dimension names and the other application uses singular names. To share the models requires renaming one or both of them to a common name. Renaming a model changes the name only in Shared Services. The internal representation of the name does not change. If you import a new version of a renamed model to the application, the new version retains the original name. You need Write access to a model to rename it.

Working with Models 179 ➤ To rename a model 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model and click Rename. 4 Type a new name in the text box and click Rename to save the new name or Cancel to cancel the name change.

Sharing Models You set up the sharing of models between applications by designating a common shared project to be used by two or more applications. See “Working with Shared Projects” on page 169 and “Selecting a Shared Project” on page 171 for details about shared projects. You select two types of models to share:

● You designate models in the application project in Shared Services to share with other applications

● You select models from a shared directory that have been made available for sharing by another application.

➤ To share models: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 Select the Share tab. The Available Models box shows models from the application project in Shared Services that have not been shared (marked with an asterisk) and models that have been placed in the shared directory by other applications. 3 Select one or more models to share (use the Ctrl key to select multiple models) and use the arrow keys to move the models to Shared Models. 4 Click OK to begin the sharing operation. 5 Click Refresh to update the status of the operation. 6 Click Report to view information about the status of the operation, including whether it was successful and the reason for failure if the operation failed. 7 Click OK to return to the Model Listing view.

The Model Listing View shows both private and shared models. The icon indicates a shared model.

180 Managing Shared Services Models Tool When you export a model from an application to an application project in Shared Services, if the model is shared, the shared directory is updated with the new version of the model at the time of export. In the same way, when you import a shared model from an application project in Shared Services to an application, it is the model in the shared directory that is actually copied to the application. You can stop sharing a model at any time. When you stop sharing a model, a copy of the model is created in the application project in Shared Services.

➤ To stop sharing a model: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 Select the Share tab. 3 In Shared Models, select one or more models to remove from sharing. Use the Ctrl key to select multiple models. 4 Use the arrow keys to move the selected models to Available Models. 5 Click OK. The selected models are removed from sharing and a copy of each is made to the current application project in Shared Services.

Filtering the Content of Models When you share models with other applications or products, it is possible that the models have most members in common, or have a common core of members, but do not have all members in common. Shared Services enables you to write a filter that retains specified members of the shared model to remove when the model is imported to an application. For example, a Financial Management application exports an account dimension and shares it in a common shared directory. A Planning application decides to use the account dimension from the Financial Management application and links to the shared account dimension. The Planning application conducts budgeting on profit and loss accounts only and therefore does not require any balance sheet accounts from the account dimension. The Planning application writes a filter that removes the Total Assets member and all of its descendants and the Total Liabilities member and all of its descendents. You can write filters for dimensional models only. Writing filters requires Write access to a model.

➤ To write a new filter or to modify an existing filter: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Check the box next to a model name to select it and click Filter.

Working with Models 181 The Members List box shows the members of the model and the Filtered Out Members box shows members that are to be retained in the model on import. 4 From the Members List box, select a member. 5 Use the arrow keys to move the selected member from the Members List box to the Filtered Out Members box. The text box with the arrow keys indicates how much of the hierarchy is to be filtered, as follows:

● Descendants (Inc). Filters the selected member and all of its descendants.

● Descendants. Filters descendants of the selected member (but not the member itself).

● Member. Filters the selected member only. You can move selected members back to Members List from Filtered Out Members with the arrow key, or move all members back with the double arrow key. 6 Repeat the two previous steps until you have selected as many members to retain as desired. 7 Click Save to save the filter or Cancel to cancel the changes you have made.

The filter icon in the Model Listing view, indicates a model has an attached filter.

➤ To delete an existing filter: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Check the box next to a model name to select it and click Filter. The Members List box shows the members of the model and the Filtered Out Members box shows members that have been selected to be filtered from the model on import. 4 Click Delete.

Tracking Model History

Merging Models in a Different Project

➤ To merge the differences between the product representation of a model and a model in a different project of the repository: Shared Services maintains a version history for each model in Shared Services, if versioning is enabled for the model. To see if versioning is enabled for a model and to enable versioning if it is not enabled, see “Viewing and Setting Model Properties” on page 187.

➤ To view the version history of a model in Shared Services: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab.

182 Managing Shared Services Models Tool 3 From the list of models, select one model and click History. Shared Services displays a list of model versions, including the person who updated the version, the update date, and comments for each model. 4 From the version list, you can perform any of the following tasks:

● View the contents of any model. i. Click a version. ii. Click View. See “Viewing and Editing Model Content” on page 178 for more information.

● Compare any two model versions to each other. i. Select any two versions. ii. Click Compare. The contents of the two model versions are shown line-by-line in a side-by-side format. See “Comparing and Merging Models” on page 176 for more detailed information. a. Click Merge to merge differences between the versions and create a new version, or Back to return to the list of models without making any changes.

● Replace the current model in the application with a version in the list. i. Select any version. ii. Click Import. The specified version is imported to the application and replaces the current model.

Managing Permissions to Models Shared Services enables you to manage access permissions to models in projects independent of any Hyperion Application Builder application. You assign permissions on a model-by- model basis to individual users or to groups of users. You can also assign permissions at the project level.

Note: The Shared Services administrator can assign project-wide permissions by using the Shared Services Configuration Console. see the Hyperion Hub Administrator’s Guide for details.

User names and passwords are managed by an external authentication provider, so they must be created externally—using NTLM, LDAP, or MSAD—before they can be added to Hyperion Application Builder. The Shared Services administrator adds authenticated users to Shared Services by using Shared Services Configuration Console. The Shared Services administrator also creates and manages groups by using Configuration Console. See the Hyperion Hub Administrator’s Guide for details. When projects are created in Shared Services, all permissions are denied for all users, except for the user who created the project. The creator of the project or the administrator (the admin user) must assign permissions for the new project. To access specific models in Shared Services, users must be assigned access rights individually or inherit access rights by being part of a

Working with Models 183 group that is assigned access rights. If an individual user is assigned to a group and the access rights of the individual user conflict with those of the group, the rights of the individual user rights take precedence. To give users access to models other than their own, an administrator must add the users and assign their permissions.

Permissions Model management provides the following types of permissions:

● Read. The ability to view the contents of a model. You cannot import a model if you have only Read access to it.

● Write. The ability to change a model. Write access includes the ability to export, import, and edit a model. Write access does not automatically include Read permission. You must assign Read permission explicitly, in addition to Write permission, if you want a user to have these permissions.

● Manage. The ability to create new users and change permissions for users. Manage access does not automatically include Read and Write permissions. You must assign Read and Write permission explicitly, in addition to Manage permission, if you want a user to have these permissions.

The following table summarizes the actions that a user can take in regard to a model with each of the permissions.

Table x Access Permissions

Access Permission

Action Read Write Manage

Sync No Yes Yes

Import No Yes Yes

Export No Yes Yes

View Yes Yes Yes

Filter No Yes Yes

Compare Yes Yes Yes

History Yes Yes Yes

Set Properties Yes Yes Yes

Assign Access No Yes Yes

Share No Yes Yes

Assign Permissions No No Yes

184 Managing Shared Services Models Tool Table x Access Permissions

Access Permission

Action Read Write Manage

Edit No Yes Yes

Rename No Yes Yes

You can apply permissions to groups and to individual users. Users are automatically granted the permissions of the groups to which they belong. You can, however, explicitly add or deny permissions to a user to override group permissions. For each type of access permission (Read, Write, and Manage), you must apply one of the following actions:

● Grant. Explicitly grant the permission to the user or group. Granting permissions to a member of a group overrides permissions inherited from the group. For example, if a group is denied a permission, you can explicitly grant the permission to a member of the group.

● Deny. Explicitly deny the permission to the user or group. Denying permissions to a member of a group overrides permissions inherited from the group. For example, if a group is granted a permission, you can explicitly deny the permission to a member of the group.

● None. Do not apply the permission to the user or group. Not applying a permission is different from denying a permission. Not applying a permission does not override permissions inherited from a group. Specifying None for particular permissions for individual users enables you to apply permissions on a group basis.

Note: If a user belongs to groups with mutually exclusive permissions to the same model, permissions that are assigned override permissions that are denied. For example, if a user belongs to a group that denies Read access to a particular model and belongs to another group that assigns Read access to the model, the user in fact is granted Read access to the model.

Assigning Permissions to Models You assign permissions on individual models in projects. You assign permissions on the models to individual users or to groups of users. You must have Manage permission for a model to assign permissions to it.

Note: Permissions can also be applied at the application project level. Project permissions apply to all new models. The default is to grant Manage permission to the owner and Admin user. Everyone else is denied all privileges. To set project-level permissions, see “Assigning Permissions to Projects” on page 171.

Users inherit the permissions of the groups to which they belong. Permissions that you assign to an individual user, however, override any group permissions that the user inherits.

Working with Models 185 ➤ To assign permissions to models: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model and click Access. You can see the permissions that are assigned to users and groups for the selected model. 4 To add users or groups, click Add. The Available Users and Groups box displays users who are authenticated as Shared Services users. If a user you want is not on the list, contact the Shared Services administrator who can use Shared Services Configuration Console to add authenticated users. 5 In the Available Users and Groups box, click or use Ctrl click to select users or groups to assign to this model. Press the right arrow key (>) to move the selected users and groups to the Selected Users and Groups box; or use the double arrow (>>) to move all users and groups to Selected Users and Groups.

Note: Group names are preceded by an asterisk (*).

6 Assign permissions to the selected users and groups by checking one of the Grant, Deny, or None boxes for the Read, Write, and Manage permissions.

Note: Assigning (or denying) a permission does not implicitly assign (or deny) any other permissions; that is, assigning Write permission does not implicitly assign Read permission, and assigning Manage permission does not implicitly assign Read and Write permission. Likewise, denying Read permission does not implicitly deny Write and Manage permissions, and denying Write permission does not implicitly deny Manage permission. You must explicitly assign all permissions you want a user to have.

See “Permissions” on page 184 for details about the Read, Write, and Manage permissions and the Grant, Deny, and None actions that you can apply to each permission. 7 Click Add to assign the new permissions.

Editing Permissions to Models You can edit the permissions of individual users and groups on individual models. You must have Manage permission for a model to change permissions for it.

➤ To edit permissions to models: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model name and click Access. You can see the permissions that are assigned to users and groups for the selected model.

186 Managing Shared Services Models Tool 4 Check the box next to one or more users or groups and click Edit. The box shows the permissions currently assigned to the selected users or groups.

Note: The icon indicates an individual user and the icon indicates a group of users.

5 Change permissions for the selected user or group by checking one of the Grant, Deny, or None boxes for the Read, Write, and Manage permissions. See “Permissions” on page 184 for details about the Read, Write, and Manage permissions and the Grant, Deny, and None actions that you can apply to each permission. 6 Click Update to accept the changes or Cancel to cancel them.

Deleting Permissions to Models You can delete all permissions for users and groups to individual models. You must have Manage permission for a model to delete access to it.

➤ To delete access to a model: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model name to and click Access. You can see the permissions that are assigned to users and groups for the selected model. 4 Check the box next to one or more users or groups and click Delete.

Note: When you click Delete, the permissions are immediately removed, without a warning message being displayed.

Viewing and Setting Model Properties Shared Services provides property data for each model in the Shared Services. You can view all model properties and set selected properties. Shared Services displays the following model properties:

● Creator. Name of the user who created the model.

● Updated By. Name of the person who updated the model. If there have been no updates, the name of the creator is listed and the Updated Date is the same as the Created date.

● Created Date. The date on which the model was created in (exported to) Shared Services.

● Updated Date. The date on which the model was last updated in Shared Services.

● Versioning. Whether versioning is enabled. If versioning is not enabled, you can enable it by changing this setting. Once versioning is enabled, however, you cannot disable it.

● Lock Status. Whether the model is locked or unlocked. You can change this setting to lock the model for your exclusive use or to unlock the model to allow other users to work with it.

Working with Models 187 ● Share Information. Share information is provided if the model is shared with a shared project.

❍ Source Project. The name of the shared project.

❍ Source Model. The path to the model in the shared project.

❍ Transformation The name of the transformation, if any, that Shared Services applies to the model to make it usable to the application.

You need Read access to view model properties and Write access to change model properties.

➤ To view or change model properties: 1 From the Hyperion Application Builder Administration Tools page, click Manage Models. In the Manage Models Registration window, click Manage Models. 2 If it is not already selected, select the Available Models tab. 3 Select a model and click Properties. You can see the properties for the model. 4 As desired, you can make the following changes to model properties:

● If versioning is not enabled, enable it by clicking the Enable button next to Versioning. After versioning is enabled, model management maintains a version history for the model. You cannot disable versioning for a model after you enable it.

● Lock or unlock the model by clicking the Lock or Unlock button next to Lock Status. 5 Click OK to return to the previous page and save any changes you have made or Cancel to cancel any changes you have made. Need a cancel to cancel enabling, or OK/Save.

Sharing Data Shared Services enables you to move data between applications. The means to move data is a data integration. A data integration specifies the following:

● Source product and project

● Destination product and project

● Source dimensions and members

● Destination dimensions and members A data integration wizard is provided to facilitate the process of creating data integrations. Administrator privileges are required to create data integrations. A Hyperion Application Builder user is able to run data integrations. Data integrations can be run manually or scheduled to run at a specific time. Data integrations can also be placed in groups and run sequentially.

188 Managing Shared Services Models Tool Prerequisites to Moving Data Between Projects Before data can be moved between projects, the models for both the source and destination project must be synchronized between Shared Services and the application. See “Synchronizing Models” on page 175 for more information. Although Hyperion Application Builder and Shared Services provide tools to create integrations, the movement of data between applications, particularly applications from different products, requires that you be intimately familiar with the data. Describe the ‘wipe’ operation that is required to make Supress Empty work. See “Creating or Changing a Data Integration” on page 190.

Managing Data Integrations Admin privileges are required to perform most data integration functions. A user without admin privileges can view (including filtering the view) and run integrations. An admin can view, run, create, edit, copy, and delete an integration.

➤ To access all data integration functionality, click Hyperion Application Builder > Manage Data. A list of integrations is displayed. The list includes the name, the source project, and the destination project. Project names identify the product, application, and project in the form:

Product.Application.Project For example, HFM.App1.beta Group integrations do not have a source and destination; each integration in the group specifies a source and destination. A group icon (GRP) in the source and destination columns identifies group integrations. The link, View group details, lists the integrations in the group. You can perform any of the following functions from the Integrations page:

● Create, edit, or copy an integration, see “Creating or Changing a Data Integration” on page 190.

● Create a data integration group; see “Grouping Integrations” on page 198.

● Delete an integration; see “Deleting Integrations” on page 194.

● Run, or schedule to run, an integration; see “Scheduling Integrations” on page 195.

Filtering a List of Integrations By default, all available integrations are displayed. You can filter the list, based on the source product and project, and the destination product and project.

Sharing Data 189 ➤ To filter the integration list: 1 Click Hyperion Application Builder > Manage Data.

Note: A list of integrations is also displayed when you are creating an integration group. In this case, begin with step 2.

A list of integrations is displayed. The integrations for all products and projects are shown by default. Two combination boxes, Source and Destination are displayed above the Filter View button. Each combination box has two drop down boxes, the first to specify a product and the second to specify a project. If you select a product from the first Source or Destination box, the second box is populated with the projects for the selected product. 2 Select a product from the first Source or Destination drop down box or from both. The second Source or Destination drop down box is populated with the projects for the selected product. 3 Select a particular project or leave All Registered Projects selected. You can select one project only. 4 Click Filter View to update the list based on the selections you made. The filter allows integrations to be displayed that act on a particular source product or project, or on a destination product or project, or on a combination of both. For example, if you specify HBM, all projects for the source, and Planning, all projects for the destination, the list includes all integrations whose source is Hyperion System 9 Business Intelligence Platform™ or whose destination is Planning. The following examples illustrate the different combinations of product and project you can specify in the Source and Destination combination boxes

● If a source product is specified and the three other drop down boxes specify all, the list shows all integrations with the specified source product.

● If source product and project are specified, and the two destination fields specify all, the list shows all integrations with the specified source project.

● If a source product and destination product are specified, and the two project drop down boxes specify all, the list shows all integrations from the given source product to the given destination product. If an integration is bidirectional (allows transposition), and either source-to-destination or destination-to-source matches the given products, the integration is listed.

Creating or Changing a Data Integration Shared Services provides a data integration wizard to enable the process of moving data between applications. To create a new integration or edit an existing integration: 5 Click Hyperion Application Builder > Manage Data.

190 Managing Shared Services Models Tool A list of integrations is displayed. 6 Take one of the following actions:

● Click New to start the integration wizard and create a new integration.

● Select an integration and click Edit to start the integration wizard and edit an existing integration.

● Select an integration and click Copy to start the integration wizard and make changes to an existing integration to create a different integration with a new name. The first page of the wizard is displayed. For a new integration the fields are blank. For an integration to be edited or copied, the fields are populated with existing values. 7 Enter information for the fields and decide whether to select the options identified by check boxes.

Field Description Integration Name A text box for a unique name for the integration. For an edited integration, this field is read-only and cannot be changed. To rename an integration, copy the integration to a new name, then delete the original integration. Source A combination text box to identify the source for the data. The first box contains a drop down list of products registered with Shared Services. When you specify a product, the second box is populated with projects belonging to the product. When you specify a project, the third box is populated with data sources. Data sources include elements like Hyperion System 9 Application Builder Plan Type. If you select a project that does not require or support data sources, "Default Data Source" is displayed in a disabled field that you cannot change. Destination A combination text box to identify the destination for the data. The first box contains a drop down list of products registered with Shared Services. When you specify a product, the second box is populated with projects belonging to the product. Bi-directional A check box that determines the direction in which the integration can be run. If it is not checked, data is moved from the source to the destination. If it is checked, the user can choose either direction when scheduling or running the integration. System Override A check box that allows writing to read-only fields in the destination project. Suppress Empty A check box that allows the integration, for performance reasons, to not transfer missing cell (#missing) values. To assure that data is transferred successfully with this option specified, you must prepare the destination database before running the integration. See “Prerequisites to Moving Data Between Projects” on page 189 for details. Notes A text box that enables you to enter optional comments and notes.

8 Click Next to go to the next page of the wizard.

Sharing Data 191 A list of dimensions for the source and destination projects is displayed. This page of the Create Integration wizard enables you to specify the dimensions that are equivalent (shared) for the purposes of this integration. By default, dimensions with the same name in each project are shared by the wizard. A line between dimensions indicates that they are shared. The next page of the wizard enables you to pick ranges of members from the shared dimensions to define the slice of data that will be transferred.

Note: You are not required to identify every dimension that is in fact identical. The reason to identify shared dimensions is to specify the dimensions for which you want to move a range of members. For any particular integration, if you are interested in a single member for a dimension, you can leave the dimension unshared.

9 Take one or more of the following actions:

● Specify the shared dimensions. A dimension can be shared with a single dimension in the other project only. To share dimensions, select a dimension in each project and click Share. A line is drawn between the two dimensions.

● Unshare any dimensions that are shared by default but that you do not want to share for this integration. Select a dimension in either project and click Unshare; or click Unshare All to remove sharing from all dimensions.

● Return to the default shared dimensions by clicking Default. 10 Click Next to go to the next page of the wizard. The screen displays dimensions in two categories:

❍ Shared Dimension Members. Dimensions identified as shared on the previous wizard page.

❍ Common POV. The remaining dimensions, that is, those not identified as shared. Each POV uses the same background POV members and a unique set of dynamic POV members. You specify the dynamic POVs. 11 Select shared dimension members: a. Select the Select Members menu control next to a shared dimension. b. Select From Source or From Destination. A list of members from the source or destination project is displayed. c. Select one or more members from the dimension. d. Click Select. You can also specify a function to identify a set of members. For example, type Match(*) or AllMembers() to specify all members that are the same for the dimension in both projects. When you run the integration with a function, the function only transfers data for members that are common to each project. However, the integration must iterate through every member identified by the function, for both projects. For example, the following table shows members from a time dimension for two projects:

192 Managing Shared Services Models Tool Project 1 (Source) Project 2 (Destination)

1997 1999

1998 2000

1999 2001

2000 2002

2001 2003

-- 2004

If you specify an AllMembers() function, the integration must check all 11 members, however, data is transferred from 1999 - 2001 to 1999 - 2001 only, because these years are common to both projects. Warning messages are returned for the other years.

Note: You must select at least one member from each dimension in Common Members, or specify a function that identifies a common member.

12 Optional. Create POVs. You can create one or more POVs but are not required to create any POVs. That is, you can create a single POV using background POV dimensions, you can use dynamic POVs to create multiple POVs, or you can leave the POV dimensions blank. The Common POV section shows all the dimensions not identified as shared on the previous wizard page. The dimensions from the source and destination projects are shown in separate columns. Initially, all dimensions are in the Background POV section and the Dynamic POV section is blank. a. Select the magnifying glass next to a dimension in the source project. b. Select a single member from the list of members. c. Repeat steps a and b for the rest of the dimensions in the source project for which you want to select a member.

Note: You can leave background POV dimensions blank if the project does not require a value for them.

d. Select the magnifying glass next to a dimension in the destination project. e. Select a single member from the list of members. f. Repeat steps d and e for the rest of the dimensions in the destination project for which you want to select a member.

Note: You can leave background POV dimensions blank if the project does not require a value for them.

Sharing Data 193 g. Use the Dynamic POV icon next to a dimension to move it from the Background POV section to the Dynamic POV section. h. Click Add to create a POV based on the static and dynamic members you have selected. i. Optional. Select a different member for the dynamic POV and click Add to create another POV. You can repeat this step by selecting different members for the dynamic POV and clicking Add each time. The numbering in the lower right corner identifies the POV, for example, POV 3 of 5. You can navigate to each POV using the left and right arrow keys. You can also move the dimension in the Dynamic POV section back to the Background POV section and move a different POV to the dynamic section and create another set of POVs by repeating this step. j. Optional. Replace the content of any POV you have already created. i. Use the arrow keys in the lower right corner to navigate to a POV you have created. ii. Change the content in the one of the Dynamic POV fields. iii. Click Replace to create a new POV. When run, the integration will copy the data from the dimension member or members in the source project list to the dimension member or members in the destination project list. 13 Optional. Click View All to see a list of the POVs that have been created. 14 Optional. Remove a POV. a. Click the left (<) or right (>) paging icon to navigate to a POV that has been created. b. Click Remove to remove the POV. 15 Save the integration, or cancel the changes you have made by taking one of the following actions:

● Click Save to save the integration. The Create Integration window remains open. You can make additional changes to the integration and save it again when finished.

● Click Save and Close. The integration is saved and the list of integrations is displayed. To schedule the new integration to run, see “Scheduling Integrations” on page 195.

● Click Save and Run. The integration is saved and the page to schedule an integration to run is displayed; see “Scheduling Integrations” on page 195.

● Click Cancel. Any changes you made since the last save are lost. If it is a new group and it has not been saved yet, no group is created.

Deleting Integrations You can delete integrations that are no longer useful.

➤ To delete an integration: 1 Click Hyperion Application Builder > Manage Data. A list of integrations is displayed.

194 Managing Shared Services Models Tool Note: If the integration of interest is not displayed, check the Filter View Source and Destination drop down boxes to see if the list of integrations is filtered. See “Filtering a List of Integrations” on page 189 for information about how to filter the integration list.

2 Select one or more integrations to delete. 3 Click Delete. A delete confirmation message is displayed. 4 Click OK to delete the selected integration or integrations or Cancel to cancel the delete operation.

Scheduling Integrations You can run an integration immediately or schedule it to run at a particular date and time. You can also place an integration in a group and schedule the group to run. See “Grouping Integrations” on page 198 and “Scheduling Group Integrations” on page 200.

➤ To schedule an integration to run: 1 Click Hyperion Application Builder > Manage Data. A list of integrations and integration groups is displayed.

Note: If the integration of interest is not displayed, check the Filter View Source and Destination drop down boxes to see if the list of integrations is filtered. See “Filtering a List of Integrations” on page 189 for information about how to filter the integration list.

2 Select an integration to run.

Note: You can select one integration only at a time to schedule for running.

3 Optional. If the integration is bi-directional, the source and destination project can be reversed. Select a project from the Source drop down box and the Destination drop down box automatically shows the other project, which will be used as the destination.

Note: If the source and destination projects are the same, it can be confusing with a bi-directional integration to know which way the data is being moved. The first entry in the Source drop down box is the original, default source project.

4 Click Run. A popup window is displayed to schedule the integration to run. 5 To run the integration immediately, click OK.

Immediately is selected by default.

Sharing Data 195 6 To schedule the integration to run at a particular time, click Schedule for and scroll to select the month, day, and time in the drop down boxes. 7 Click OK to schedule the integration or Cancel to cancel the operation. The integration you scheduled is added to the list of scheduled integrations. For information on viewing scheduled integrations, see “Viewing the Status of an Integration” on page 196.

Managing Scheduled Integrations When you schedule an integration, it is added to the list of scheduled integrations. The scheduled integration list includes integrations that are waiting to run (pending), integrations that are currently running (running), integrations that have been cancelled (cancelled) and integrations that have already run (completed or failed). Integrations remain on the list until you remove them. You can perform the following actions on integrations on the scheduled integration list:

● View the status of a running, completed, or failed integration; see “Viewing the Status of an Integration” on page 196.

● Cancel a running integration; see “Canceling an Integration” on page 196.

● Run a copy of an integration; see “Copying an Integration to Run” on page 197.

● Reschedule an integration; see “Rescheduling an Integration” on page 197.

● Remove an integration from the list of scheduled integrations; see “Removing an Integration” on page 198.

Viewing the Status of an Integration The scheduled integration page lists all integrations.

➤ To view all scheduled integrations, click Hyperion Application Builder > Scheduled Integrations. The Status column indicates whether an integration is pending, running, completed, or failed. To view details about a completed or failed integration, click the Failed or Completed link in the Status column.

Canceling an Integration You can cancel an integration that is scheduled to run or in progress (running).

➤ To cancel an integration: 1 Click Hyperion Application Builder > Scheduled Integrations. 2 Select an integration. You can select a single integration only.

196 Managing Shared Services Models Tool 3 Click Cancel. A confirmation message is displayed. 4 Click OK to cancel the integration or Cancel to cancel the operation.

Copying an Integration to Run You can schedule the same integration to run multiple times by making a copy of the integration and scheduling the copy to run.

➤ To schedule a copy of an integration to run: 1 Click Hyperion Application Builder > Scheduled Integrations. 2 Select an integration. You can select a single integration only. 3 Click Run Copy. A popup window is displayed to schedule the integration to run. 4 To run the integration immediately, click OK.

Immediately is selected by default. 5 To schedule the integration to run at a particular time, click Schedule for and scroll to select the month, day, and time in the drop down boxes. 6 Click OK to schedule the integration or Cancel to cancel the operation. The integration you scheduled is added to the list of scheduled integrations. You can schedule an integration multiple times, which results in the integration being listed multiple times on this page.

Rescheduling an Integration You can reschedule an integration that is waiting to run to a different date or time.

➤ To reschedule an integration: 1 Click Hyperion Application Builder > Scheduled Integrations. 2 Select an integration. You can select a single integration only. 3 Click Reschedule. A popup window is displayed to reschedule the integration to run. 4 To run the integration immediately, click OK.

Immediately is selected by default. The currently scheduled month, day, and time are displayed in the Schedule for combination boxes.

Sharing Data 197 5 To schedule the integration to run at a particular time, click Schedule for and scroll to select the month, day, and time in the drop down boxes. 6 Click OK to schedule the integration or Cancel to cancel the operation.

Removing an Integration You can remove an integration that is pending to run or one that has already run (completed or failed).

➤ To remove an integration: 1 Click Hyperion Application Builder > Scheduled Integrations. 2 Select an integration. You can select multiple integrations to remove. 3 Click Remove. A confirmation message is displayed. 4 Click OK to remove the integration or integrations you have selected; or select Cancel to cancel the operation.

Grouping Integrations You can create groups of integrations to run at the same time. Before creating a group, you must first create individual integrations that can be added to a group; see “Creating or Changing a Data Integration” on page 190. In the group, you specify the order in which to run the integrations.

➤ To create or edit an integration group: 1 Click Hyperion Application Builder > Manage Data. A list of integrations is displayed. 2 Take one of the following actions:

● To create a blank new group, click New Group. A Create Integration Group page with blank fields is displayed.

● To create a new group with a list of integrations, select one or more integrations from the list of saved integrations, and click New Group. A Create Integration Group page with populated fields is displayed.

● To edit an existing group, select the group and click Edit. A Create Integration Group page with populated fields is displayed. 3 Type a name for the group, or change the name for an existing group. The name must be unique among existing group and integration names. 4 Optional. Type or change comments in the notes field.

198 Managing Shared Services Models Tool 5 Optional. Unselect the Stop on error check box. Stop on error is selected by default. If one of the integrations encounters an error while running, the group stops running. Unselect the box if you want the group to continue executing when an error is encountered. 6 Click Next to go to the next page.

Note: If you click Save or Save and Close, the group (name and notes) is saved. You can edit the group later and add integrations.

7 Select one or more integrations from Available Integrations. You can nest an integration group within another group, therefore the list of integrations includes integration groups in addition to individual integrations. For an individual integration, the list displays the source and destination product and directory. For a group, click on the View group details link to see the integrations contained in the group.

Note: You can filter the list of available integrations to show a more useful list. See “Filtering a List of Integrations” on page 189.

8 Click Add to copy the selected integrations to Selected Integrations. The selected integrations are copied, not moved, to Selected Integrations. You can add an integration multiple times if you want to run it more than once. 9 Optional. If you are editing an existing group, or if you add integrations that you want to remove, select one or more integrations in Selected Integrations and click Remove to remove them from the group. You can click Remove All to remove all integrations from the group. Integrations are run in the order that they are shown in Selected Integrations. 10 Optional. Select an integration and click the up or down arrow keys to move the integration up or down in the list to change the order in which it is run. 11 Save the group, or cancel the changes you have made by taking one of the following actions:

● Click Save to save the group. The Create Integration Group window remains open. You can make additional changes to the group and save it again when finished.

● Click Save and Close. The group is saved and the list of integrations is displayed. To schedule the new group to run, see “Scheduling Group Integrations” on page 200.

● Click Save and Run. The group is saved and the page to schedule a group to run is displayed; see “Scheduling Group Integrations” on page 200.

● Click Cancel. Any changes you made since the last save are lost. If it is a new group and it has not been saved yet, no group is created.

Sharing Data 199 Scheduling Group Integrations You can run an integration group immediately or schedule it to run at a particular date and time.

➤ To schedule a group to run:

Note: If you selected Save and Run when you created the integration group, the page to run the integration group is displayed. Skip to step 4.

1 Click Hyperion Application Builder > Manage Data. A list of integrations and integration groups is displayed.

Note: If the group of interest is not displayed, check the Filter View Source and Destination drop down boxes to see if the list of integrations is filtered. See “Filtering a List of Integrations” on page 189 for information about how to filter the integration list.

2 Select a group to run.

Note: You can select one group only at a time to schedule for running.

3 Click Run. A page is displayed to schedule the group to run. 4 To run the group immediately, click OK.

Immediately is selected by default. 5 To schedule the group to run at a particular time, click Schedule for and scroll to select the month, day, and time in the drop down boxes. 6 Click OK to schedule the group or Cancel to cancel the operation.

The group you scheduled is added to the list of scheduled integrations. For information on viewing scheduled integrations, see “Viewing the Status of an Integration” on page 196.

200 Managing Shared Services Models Tool Chapter Using and Scheduling Tasks 9

You use tasks to create, schedule and distribute reports and to send alerts. An alert sends a message to a file, database, or user based on a threshold value. Tasks can use unique properties for each user and define who receives a report based on a threshold value. The task framework also enables you to define thresholds using ECMA script. Tasks and scheduled tasks are saved in the ATF repository. From the Repository Object page in the Administration Tools, you can create the following tasks:

● Report Distribution - Generate an OLAP or relational report and send it as an attachment in e-mail. You can also format the report and export it to another format, such as PDF or HTML. For an example, see “Create a Report Distribution” on page 210.

● Scheduled Report Distribution - Schedule a report distribution to run at a certain time or interval. For an example, see “Scheduling a Report Distribution” on page 214.

● Alerts - Based on a threshold value, append a notification message to a file or database, or generate an e-mail. For example, you can use scripting functionality to test for a threshold value in a report. You can also specify complex conditions using ECMA script and the objects created by tasks. For an example, see “Create an Alert” on page 215 or “Creating a Complex Alert” on page 218.

● Adding Subscribers - You can change the recipients of a report distribution, scheduled report distribution, or alerts. For an example, see “Adding Subscribers” on page 218.

A task executes a piece of code that performs a specific functionality. You group tasks into a task definition to perform functions, such as sending e-mail, generating a report, or generating an alert based on a condition. All task definitions have an ID, name, description, and knowledge of ancestors. A typical task definition consists of a hierarchical tree of tasks, where tasks are either nested or siblings. You can also use JSP tags to create a task definition builder and a schedule definition builder. For information on how to use tags to build task definition builders and schedule definition builders, see the “Using Tasks Alerts and Scheduling Tags” chapter in the Hyperion System 9 BI+ Application Builder J2EE Web Application Architecture Guide.

Using and Scheduling Tasks 201 Initializing the Task Registry The task registry contains a list of tasks that are used to build a task definition and are documented in “Using the Task Registry” on page 225. The following default tasks are provided:

● General - Loads the com.hyperion.atf.services.task.AtfTaskProvider.java tasks.

● Core - Loads the com.hyperion.waa.utility.core.WAATaskProvider.java tasks.

● OLAP - Loads the com.hyperion.waa.utility.olap.WAATaskProvider.java tasks.

● Relational - Loads the com.hyperion.waa.utility.relational.WAATaskProvider.java tasks.

The following figure shows the task folders:

Figure 1 Task Folders

Initializing Web.xml Before you use tasks you must have the task initialization files set-up and registered. Use the WAATaskRegistry.xml file to load the tasks into the task registry. Register the WAATaskRegistry.xml file in your web.xml as a context parameter: TaskRegistryXMLFile /WAATaskRegistry.xml File with information on the available tasks

202 Using and Scheduling Tasks You also need to register the WAADefaultTaskDefinitions.xml file with the WAAApplicationServicesServlet in the web.xml file. The WAADefaultTaskDefinitions.xml file provides the sample task definitions that you see on start up: WAAApplicationServicesServlet Application Services Servlet Servlet which handles starting ATF services com.hyperion.waa.web.core.WAAApplicationServicesServlet DefaultTaskDefinitionsXMLFileName /com/hyperion/waa/utility/core/task/WAADefaultTaskDefinitions.xml< /param-value> The default task definitions 1

Using a Task Definition Builder A task definition is a hierarchical structure of one or more tasks that perform a function. Tasks definitions are persisted in the repository with their full folder path and name. All task definitions use the Root task as their top task, which is automatically added when you create a task. The following figure shows a task definition that defines a mail server and sends an e- mail.

Figure 2 Mail Task Definition

A task has attributes that can specify a value or a property. For example, the Mail Server task has SMTP Host, user ID and password attributes. You can define the attribute at design time by setting it to a value. For example, you can set SMTP Host to a value, such as mail.grasp.com. You can alternatively set it to a property such as Host_Property. The property’s value is assigned at runtime by a user or inherited from an ancestor task. A task can be a nested task or a sibling task. A nested task can access its ancestor task’s properties. A sibling task cannot access a ancestor task’s properties. In Figure 3, Mail_A is nested, and Mail_B is a sibling of the Mail Server task. The Mail Server task exposes a connection to a mail server; only the Mail_A task can use it.

Initializing the Task Registry 203 Figure 3 Nested and Sibling Tasks

A task can be executed synchronously or asynchronously. A parent task is not completed until all its child tasks have been executed. If a synchronous parent’s child task fails during execution, the remaining child tasks are immediately terminated. In an asynchronous parent, the remaining child tasks are allowed to continue. However in both cases, the parent task is considered unsuccessful, and execution on the entire task chain up to the root task is terminated. You set a parent task to one of the following synchronizations:

● Synchronous - The nested child task does not run until the previous task is finished.

● Asynchronous - All child tasks run at the same time.

● Aynchronous with a maximum number of child tasks - Only the maximum number of children run at the same time.

Task dependencies are defined for tasks that are dependent on each other. When you create task, you must include dependent tasks as ancestors in the task definition. For example, a Mail task is dependent on a Mail Server task. In Figure 3, the Mail Server task is an ancestor task of the Mail_A task, so the dependency is fulfilled. However, Mail_B task does not work, because it also depends on a Mail Server task that is not defined. For task information including dependencies, exposed properties, and attributes, see “Using the Task Registry” on page 225.

➤ To create a task definition 1 From the Repository Objects tab in the Administration Tools, click the Create button, then select Task Definition. 2 Enter a name and description. 3 Select the Add Child member icon to add a child task. 4 Scroll through the task registry and select a task. A prompt is displayed for the selected task’s attributes. 5 For each attribute that is required, enter a value or click the Property check box and enter a property name. 6 Repeat steps 3-5 for each task that you want to add. 7 Click the Save button to save the task.

Note: You can move tasks using the cut and paste icons.

204 Using and Scheduling Tasks Using Attributes In Figure 4, the Mail Server task connects to a mail server and exposes the mail server connection to its child tasks. The following figure shows the Mail Server task attributes:

Figure 4 Mail Server Task Attributes

Note: The icon with the red check marks indicates that the attribute is required.

You set task attributes to one of the following:

● A specific value. For example, you can set the attribute SMTP Host = , where is the name of the mail server; for example the mail server for the Grasp company is mail.grasp.com. You must edit the task defintion to change the value.

● A property name. If you set the attribute to a property name, its value is resolved when the task is run. The user is always prompted at runtime to enter property values. The property may also be defined in a properties file using one of the following tasks: File Properties, Fixed Properties, Sql Properties, or User File Properties.

Note: User input overrides properties that are read from a properties file.

If the property is not found, an exception is thrown. For example, you can set the SMTP Host attribute to SMTP Property. At runtime, the user is prompted to enter a value for SMTP Property. If the user does not enter a value, the ancestor tasks are searched for SMTP Property. If SMTP Property is not found, an exception is thrown.

Manually Running Task Definitions After creating a task definition, you can run it; a user prompt is displayed for all properties. If you enter a value at the prompt, the value overrides the value defined by an ancestor task.

Initializing the Task Registry 205 Note: If you run a scheduled task definition, a prompt is not displayed for properties; therefore you must define all property values in ancestor tasks. For example, if SMTPHost is a property, use the User File Properties task or the File Properties task to assign a value to it.

In Figure 2, the task definition contains the Mail Server task and a nested Mail task. The attributes are set as follows:

Mail Server - Task Attribute: SMTP Host - value - mail.Grasp.com

Mail_A - Task Attributes:

● Mail Bcc

● Mail Body - value = Hello World

● Mail Cc

● Mail From - property = Mail From

● Mail Server Property Name

● Mail Subject

● Mail To - property = Mail To

● Property Name

The following prompt is displayed. You can enter a mail sender and mail recipient in the Mail From and Mail To properties respectively:

Figure 5 Prompt for Mail Properties

Figure 6 shows a task definition using the User File Properties task. This task uses a file named .properties, where user_id is the name of the authenticated user’s logon ID. For example, if the Administrator user is logged on, the file is Administrator.properties. You can define numerous properties in the Administrator.properties file: SMTP\ Host=mail.grasp.com Mail\ [email protected] Mail\ User\ Id= Mail\ Password=

206 Using and Scheduling Tasks Note: You must precede each blank character with the backslash character ( \ ).

When prompted for the Mail To property, you must enter the name of a mail recipient; when prompted for the Mail From property, you can leave it blank, so the property is taken from the properties file. If you enter a Mail From value, it overrides the Mail From property in the properties file.

Figure 6 Mail Task Definition Using a Properties File

➤ To run a task definition, take one of the following actions:

● From the Repository Object tab, select the task definition, then click the Run button.

● From the Repository Object tab, select a view, click the Run button, then from the Execute Task pull-down menu, select a task.

Tip: You can also click the Run button when you are editing a task definition.

Scheduling Task Definitions A scheduled task definition specifies when to execute a task definition. You can create one or more scheduled task definitions for each task definition. If you run a scheduled task definition, a prompt is not displayed for properties; therefore, you must define the property values in ancestor tasks. For example, if SMTPHost is a property, use the User File Properties task, File Properties task, or Fixed Properties task to assign a value to it.

➤ To create a scheduled task definition 1 From the Repository Objects tag, select the Create button, then select Scheduled Task Definition. 2 From the Select Task Definition pull-down menu, select a task definition. 3 From the Folder pull-down menu, select a folder. 4 Enter a name and description for the scheduled task definition. 5 Take one of the following actions:

❍ Click the +Frequency icon and specify a frequency.

❍ Click the +Expression icon and enter a valid Cron expression for the frequency. For more information, see the next section, Cron Expressions.

Initializing the Task Registry 207 6 Click the Save button.

A clock icon is displayed before each scheduled task definition. The following figure shows task definitions and the scheduled task defintion A Weekly E-mail Report:

Figure 7 Task Definitions and Scheduled Task Definition Icons

Cron Expressions Cron is the name of a utility that executes tasks at a specified time/date. The cron syntax is used to specify the frequency and time for scheduled task definitions. This section describes how to use cron commands. For more information, see http://www.redhat.com/support/resources/tips/cron/cron.html. An entry in cron is made up of a series of fields separated by a space. The * indicates that the entry is not defined or relevant. There are five fields for the event’s frequency:

● minute - This field controls what minute of the hour the event will run on, between '0' and '59.'

● hour - This field controls what hour the event will run on. It is specified in the 24 hour clock, with values between 0 and 23 where 0 is midnight.

● dom - This field is the day of month that you want the event run. For example, to run a command on the 19th of each month, the dom is 19.

● month - This field is the month a specified event will run. It can be specified numerically (0- 12).

● dow - This field is the day of the week that you want an event to be run on. It can be numeric (0-7).

Sample Task Definitions The sample task definitions are defined in the WAADefaultTaskDefinitions.xml file and are automatically loaded into the ATf repository. Following are the folders and default task definitions:

208 Using and Scheduling Tasks ● /hyperion/taskdefinitions/ConditionalEcmaScriptTest - Sends an e-mail based on a condition defined with ECMA script.

● /hyperion/taskdefinitions/GenericMailDefinition - Sends an e-mail with an attachment file.

● /hyperion/taskdefinitions/olap/GenericOlapReportMailDefinition - Creates and e-mails an OLAP report.

● /hyperion/taskdefinitions/relational/GenericRelationalReportMailDefinition - Creates and e-mails a relational report.

● /hyperion/taskdefinitions/olap/GenericOlapReportMailDefinitionWithCubeView - e- mails an OLAP Report if provided with a cubeView object.

● /hyperion/taskdefinitions/relational/GenericRelationalReportMailDefinitionWithQueryInfo - E-mails a Relational Report if provided with a queryInfo object.

● /hyperion/taskdefinitions/olap/ConditionalDemoBasicReportMailDefinition - E-mails an OLAP Report based on a script condition.

● /hyperion/taskdefinitions/olap/TwoDSOneConditionalDemoBasicAndSampleBasicReportM ailDefinition - E-mails an OLAP Report based on a script condition.

● /hyperion/taskdefinitions/olap/OneCubeViewTwoConditionalDemoBasicReportMailDefiniti on - E-mails an OLAP Report based on a script condition.

● /hyperion/taskdefinitions/relational/ConditionalDrillReportMailDefinition - e-mails a Relational Report based on a script condition.

● /hyperion/taskdefinitions/HyperionStockPrice-mailDefinition - E-mails the Hyperion stock price as an attachment.

● /hyperion/taskdefinitions/NotifyExecuted - Inserts a notification entry into a database table. This is a basic task definition that can be linked to from another task definition.

● /hyperion/taskdefinitions/NotifyRising - Appends a notification entry to a file. This is a basic task definition that can be linked to from another task definition.

● /hyperion/taskdefinitions/ConditionalEcmaScriptTest - Sends an e-mail based on a condition specified with an ECMA script. This demonstrates a conditional statement with If, Else If, and Else logic.

Examples The examples in this section utilize the components that are installed and configured with the Typical installation of Application Builder, which installs and deploys Apache Tomcat and MySql. It assumes that the following components are in place:

● Analytic Services and Hyperion System 9 BI+ Analytic High Availability Services™ are installed on localhost.

● The Analytic Services Demo application, Basic database is loaded with data.

● The default user/password, Administrator/password, is set-up in Analytic Services and Application Builder with Administrative rights.

● You are logged on to the Administration Tools as Administrator.

Initializing the Task Registry 209 These examples build on each other and must be done in order: “Create a Report Distribution” on page 210 - A Report Distribution is a task that runs a query, generates some form of static output (usually PDF), and distributes it by way of e-mail to a group of interested users. This example generates an OLAP view, exports it to PDF, attaches the PDF to an e-mail, then sends the e-mail. The task definition is named Report Distribution and is saved in the Administrator folder. “Scheduling a Report Distribution” on page 214 - A Scheduled Report Distribution runs at a scheduled time or at intervals. You can create different schedules task definitions that run the same report, which is a convenient way to run a report at different times. This example schedules the Report Distribution task definition to run weekly, on Fridays at noon. “Create an Alert” on page 215 - An alert sends an e-mail or writes to a log file to indicate that the values in a report have met a condition or threshold. This example appends a message into the c:\Alert.log file when the budget values in the Distributed Report task definition exceed the threshold of $200. “Adding Subscribers” on page 218 - You can add subscribers to receive report distributions. This is a convenient way to distribute reports at scheduled intervals. Subscribers are e-mail recipients. “Creating a Complex Alert” on page 218 - Complex alerts utilize Java objects and Java methods exposed in the task framework. This enables you to use complex logic to define a condition or threshold. This example uses the.findAncestorObject method which searches ancestor tasks for two OLAP views and then compares the values in the views.

Create a Report Distribution This section describes how to create and run a task definition that generates an OLAP view and attaches it to an e-mail message. The following figure shows the task definition:

Figure 8 Report Distribution Task Definition

210 Using and Scheduling Tasks Creating a Task Definition with a User Property File and Error Log This section shows you how to perform the following tasks:

● Create a Report Distribution task definition in the Users/Administrator/ folder.

● Add a User Properties File task to load property values from a user file. The user file name is equivalent to username.properties. This is a convenient way to run the same task using properties unique to each user. For example, you can create a user property file for each user and define the user’s e-mail address and alert log file.

● Create the Administrator.properties file.

Note: This example assumes you are logged in as Administrator.

Before you begin, create the property file Administrator.properties in the following directory: C:\install\ApplicationBuilder\7.0.0\WAA\deployed\Tomcat\4.1.24\webapps\- admin\WEB-INF\classes where install is the directory where you installed Application Builder. Add your e-mail server name, and if necessary a mail server user ID and password. For example, the contents of the Administrator.properties file may be as follows: SMTP\ Host=mail.myCompany.com Mail\ User\ Id=user1 Mail\ Password=PASSWORD1

Tip: The backslash character is needed to delimit each blank character.

➤ To create a new task definition and add the User Property File task: 1 Navigate to the Repository Objects tab in the Administration Tools. 2 Click the Create button, then select Task Definition. 3 From the Edit Task Definition page, click the Add Child Member icon. 4 Click the +General folder, then click the User File Properties task. 5 Click +Task Attributes icon at the bottom of the screen.

Tip: The + icon expands the attribute information.

6 For the Path attribute, click the Add icon. 7 Enter the following path: C:/install/ApplicationBuilder/7.0.0/WAA/deployed/Tomcat/4.1.24/webapps/ -admin/WEB-INF/classes where install is the directory where you installed Application Builder. 8 Optional: Enter a task name and description.

Initializing the Task Registry 211 9 Click OK. 10 To name and save the task definition: a. From the Folder: box, select Users/Administrator. b. In the Name text box, type Report Distribution. 11 Click Save.

The following procedure shows how to add a Error Log task that updates the c:\task_error.log file.

➤ To add a Error Log task: 1 Click the Add Child Member icon. 2 Click the +General folder, then click the Error Log task. 3 Click the +Task Attributes icon at the bottom of the screen. 4 Click the Message Log Format attribute, then click the Add icon. 5 Click the Log File Name attribute, then click the Add icon. 6 Type c:\task_error.log. 7 Click OK, then click Save

Creating an OLAP View and Exporting it to PDF

➤ To create an OLAP view, export it to PDF format, then make it into an attachment: 1 Click the Error Log task.

Tip: The next task you add will be a child of the Error Log task.

2 Click the Add Child Member icon. 3 Click the + OLAP folder, then click the Schema task. 4 Click the +Task Attributes icon at the bottom of the screen. 5 Enter the following values for each attribute listed:

❍ Server Name - localhost

❍ Schema Name - Demo

❍ URI - adm:thin:com.hyperion.ap.ees.EESHssDriver:localhost:Demo?user=Administrator;pa ssword=password;locale=en;domain=essbase;olapServer=localhost;orbType=TCPIP;p ort=5001;useConnPool=false;connPerOp=false;useCluster=false

Note: Do not enter values for the following attributes: Property Name, Remote Server Name, Driver Name, User Id, Password, Password Encrypted

212 Using and Scheduling Tasks 6 Use steps 2-5 to add the following child tasks and attributes: a. Task: Cube Attribute: Cube Name - Basic b. Task: Cube View

❍ Attribute: Expression Type - ALE

❍ Attribute: Expression Text - Select value From Basic PROJECT Year ON EDGE COLUMN WITH (SELECT * FROM Year WHERE Descendants("Year", "Year", false)) PROJECT Product, Measures ON EDGE ROW WITH (SELECT * FROM Product WHERE Children("Audio", "Product", false)), (SELECT * FROM Accounts WHERE Children("Profit", "Accounts", true)) PROJECT Scenario ON EDGE PAGE WITH (SELECT name FROM Scenario WHERE Member("Actual", "Scenario"), Member("Budget", "Scenario")) PROJECT Market ON EDGE SLICER WITH (SELECT name FROM Market WHERE Member("New_York", "Market"))

Tip: This expression text is in the sample script file installed with - adm\Samples\Scripts\ALE_CubeDataQuery1.txt file.

c. Task: Cube View Export Manager Attribute: Configuration Xml File Name - /WAAGridExport.xml d. Task: Cube View Export e. Task: Cube View Export Data Source Attribute: Export Name - PDF (Page size: 8.5x11) 7 Click OK, then click Save.

The following figure shows a snippet of the OLAP view results:

Figure 9 OLAP View

Sending E-mail with a Report Attachment The following procedure describes how to send an e-mail with an OLAP view attached.

Initializing the Task Registry 213 ➤ To create an e-mail: 1 Click the Cube View Export Data Source task.

Tip: The next task you add will be a child of the Cube View Export Data Source task.

2 Click the Add Child Member icon. 3 Click the +General folder, then click the Mail Server task 4 Click the +Task Attributes icon at the bottom of the screen. 5 For the SMTP Host attribute: a. Enter SMTP Host. b. Select the Property check box. 6 Click the Add Child Member icon. 7 Click the +General folder, then click the Mail task. 8 Click the +Task Attributes icon at the bottom of the screen. 9 Enter the following values for each Mail attribute listed:

❍ Mail From - e-mail_sender_address

❍ Mail To - e-mail_recipient_address

❍ Mail Subject - Attached is the monthly sales report

❍ Mail Body - Please review the attached sales report and send me your analysis.

Note: Enter valid e-mail addresses for e-mail_sender_address and e-mail_recipient_address

10 Click OK, then click Save. 11 Click Run.

Scheduling a Report Distribution You can schedule a task definition to run once or to run at repeated intervals. The following procedure schedules the Report Distribution task definition to run weekly, on Fridays at noon.

➤ To schedule the Report Distribution task definition: 1 Navigate to the Repository Objects tab in the Administration Tools. 2 Click the Create button, then select Scheduled Task Definition. 3 From the Edit Scheduled Task Definition page, specify the frequency as follows: Weekly, on Friday at 12:00:00 PM.

214 Using and Scheduling Tasks Tip: You can alternatively define the time by entering a cron expression in the +Expression panel. For more information, see “Cron Expressions” on page 208.

4 Select the Enabled check box 5 From the Folder pull-down menu, select Administrator. 6 Optional:

❍ Using the Name pull-down menu, change the default name.

Note: The default name is the the task definition name prepended with the word Scheduled. For example, the default name is Scheduled Report Distribution.

❍ Using the Description pull-down menu, enter a description. 7 Click Save.

Create an Alert An alert sends an e-mail or writes to a log file based on a condition. This example appends a message into the c:\Alert.log file, when the budget values in the Distributed Report task definition exceed the threshold of $200.

Creating an Alert Task Definition This section shows you how to perform the following tasks:

● Create an Expense Alert task definition and save it in the Users/Administrator folder.

● Specify an alert text file using the File Writer task.

● Specify an alert message using the File Notify Alert task.

Note: This example is similar to the sample task definition hyperion/taskdefinitions/NotifyRising.

➤ To create the alert task: 1 Navigate to the Repository Objects tab in the Administration Tools 2 Click the Create button, then select Task Definition. 3 From the Edit Task Definition page, click the Add Child Member icon. 4 Click the +General folder, then click the File Writer task 5 Click the +Task Attributes icon at the bottom of the screen 6 Enter the following text for the File Name attribute, then click OK: c:\Alert.log 7 Click the Add Child Member icon.

Initializing the Task Registry 215 8 Click the +General folder, then click the File Notify Alert task. 9 Click the +Task Attributes icon at the bottom of the screen. 10 Enter the following text for the Message attribute, then click OK: Your Expenses exceed $300.00. 11 To name the alert task definition: a. From the Folders: pull-down menu, select Users/Administrator. b. In the Name text box, type Expense Alert. 12 Click Save.

Adding a Conditional Script and Link to the Alert Task Definition This section shows you how to add the following functionality:

● Create the Report Distribution with Expense Alert task definition.

● Specify that you want to use ECMA script to define a condition using the Scripting Framework task.

● Define a condition using the If Scripting Framework task.

● Link to the Report Distribution with the Expense Alert task definition.

Note: The condition in this example is similar to the sample task definition hyperion/taskdefinitions/Olap/ConditionalDemoBasicReportMailDefinition.

➤ To add a conditional script and link to the Alert Task definition: 1 Navigate to the Repository Objects tab in the Administration Tools. 2 Click the Users/Administrator/Report Distribution task definition, then click the Edit button. 3 Save the task definition as Report Distribution with Expense Alert in the Users/Administrator/ folder. 4 Click the Mail task.

Tip: The next task you add will be a child of the Mail task.

5 Click the Add Child Member icon, click the + Core folder, then click the Scripting Framework task. 6 Click the +Task Attributes icon at the bottom of the screen. 7 Type the following text for the Language attribute, then click OK: ecmascript 8 Click the Add Child Member icon, click the + Core folder, then click the If Scripting Framework task. 9 Click the +Task Attributes icon at the bottom of the screen 10 Enter the following text for the Script attribute, then click OK:

216 Using and Scheduling Tasks var rCubeView = task.findAncestorObject(Packages.com.hyperion.ap.IAPQryCubeView);

if (rCubeView == null) { Packages.java.lang.System.out.println('CubeView is null'); } else { var rDataCell = Packages.com.hyperion.ap.utility.HsApUtility.getCubeViewCell(rCubeView, 0, 2, 2); return ( rDataCell != null && !rDataCell.isMissing() && rDataCell.getValue() > 200); }

Note: This script searches the ancestor tasks and uses the first cubeView object it finds, which is shown in Figure 10. If the data value in page 0, row 2, column 2, is greater than 200, True is returned; otherwise, False is returned.

11 Click the Add Child Member icon, click the +General folder, then click the Link task. 12 Click the +Task Attributes icon at the bottom of the screen.

13 Type the following text for the Linked Task Definition Name attribute, then click OK: Users/Administrator/Report Distribution with Expense Alert

The following figure shows a snippet of the OLAP view. The script returns true, because the data value in page 0, row 2, column 2, is 399.00 which is greater than 200.

Figure 10 OLAP View

Running or Scheduling the Alert

➤ To run or schedule the alert, take one of the following actions:

● Click the Report Distribution with Expense Alert task definition, then click the Run icon.

Initializing the Task Registry 217 ● Click the Report Distribution with Expense Alert task definition, click the Create icon, then click Schedule Task Definition. For more information, see “Scheduling a Report Distribution” on page 214.

Adding Subscribers You can add subscribers to receive report distributions. This is a convenient way to distribute reports at scheduled intervals. Subscribers refers to e-mail recipients. This example adds subscribers to the Report Distribution task definition. The term subscribers refers to e-mail recipients.

➤ To add subscribers: 1 Navigate to the Repository Objects tab in the Administration Tools 2 Click the Report Distribution task definition, then click the Edit icon at the bottom of the page 3 Click the Mail task, then click the Edit Member icon at the top of the page 4 Click the Mail To attribute, then enter a comma-delimited list of e-mail recipients, such as Jane Doe, Tom Smith, John Jones, and so on

Creating a Complex Alert Complex alerts utilize Java objects and Java methods exposed in the task framework. This enables you to use complex logic to define a condition or threshold. This example uses the .findAncestorObject method which searches ancestor tasks for two OLAP views and then compares the values in the views.

Note: The Java methods available in the task framework are listed in the ATFTask class in the Javadoc.

The following script checks the values in two OLAP views. Each OLAP view queries a different data source.

Note: This script is implemented in the sample task definition hyperion/taskdefintions/Olap/TwoDSOneConditionalDemoBasicAndSampleBasic ReportMailDefinition.

var rCubeView1 =task.findAncestorObject(Packages.com.hyperion.ap.IAPQryCubeView); var rCubeView2 = task.findAncestorProperty('CubeView2'); if (rCubeView1 == null) { Packages.java.lang.System.out.println('CubeView1 is null'); } else if (rCubeView2 == null) { Packages.java.lang.System.out.println('CubeView2 is null'); } else

218 Using and Scheduling Tasks { var rDataCell1 = Packages.com.hyperion.ap.utility.HsApUtility.getCubeViewCell(rCubeView1, 0, 0, 0); var rDataCell2 = Packages.com.hyperion.ap.utility.HsApUtility.getCubeViewCell(rCubeView2, 0, 0, 0); return ( rDataCell1 != null && rDataCell2 != null && !rDataCell1.isMissing() && !rDataCell2.isMissing() && rDataCell1.getValue() > 1000 && rDataCell2.getValue() > 1000); }

Initializing the Task Registry 219 220 Using and Scheduling Tasks APPENDIX Using Tasks A

This appendix describes the tasks that are loaded in the task registry and used to construct task definitions. Use this chapter as a reference to build task definitions. This appendix includes the following sections, which describe the tasks contained in the different task registries:

● “General Tasks” on page 221

● “Core Tasks” on page 223

● “OLAP Tasks” on page 224

● “Relational Tasks” on page 224

The following table lists and describes the tasks contained in the General task registry, with page references for more information: Table 1 General Tasks

General Task Name Description

“Conditionals” on page 227 This task groups an If Scripting Framework Script task and an Else task. If you are using the Else task, you must also use the Conditionals tasks.

“Database Meta Data” on page 227 This task exposes metadata from a relational database to child tasks.

“Database” on page 228 This task creates a connection to a relational database and exposes the connection to nested tasks.

“Data Source” on page 229 This task creates a data source and provides it to nested tasks. For example, you can specify a text file that appears as an attachment in the body of an e-mail. You use this as an attachment in an e- mail.

“Error Log” on page 230 This task creates a file that logs exceptions; messages are appended to an existing file. Place this task before all tasks from which you want to log errors.

“Else” on page 231 This task groups tasks and executes them if the preceding If Scripting Framework Script task condition is False. This task must have an ancestor Conditionals task, that encompasses the If Scripting Framework Script task and Else task.

“File Input Stream” on page 232 This task opens a file and exposes the input stream of the file. The file is created if it does not exist. This task can be used as input to a Data Source task for an attachment.

Using Tasks 221 Table 1 General Tasks (Continued)

General Task Name Description

“File Notify Alert” on page 232 This task creates and provides a standard alert message that is written to a file.

“File Writer” on page 233 This task opens a file and writes to it.

“File Properties” on page 234 This task loads properties with values from a specified file. The properties are available to nested tasks. The file that you specify contains property name value pairs.

“Fixed Properties” on page 235 This task defines property name and value pairs at design time. The properties are available to nested tasks. For example, if you have a scheduled task you must define all property values before the task is run. You can use this task, rather than defining the property values in a file.

“Grouping” on page 236 This task is used to group other tasks. It has no other functionality other than being the root task of a task definition.

“Link” on page 236 This task links a task definition, as a nested task, into an existing task definition. If a linked task definition is run manually, the user is not prompted for the linked task’s properties. Those properties must be resolved by an ancestor task using the User File Properties, File Properties, or Fixed Properties task.

“Mail Notify Alert” on page 237 This class creates a standard alert entry that can be incorporated into an e-mail message.

“Mail Server” on page 238 This task connects to a mail server and provides the mail server connection to nested tasks.

“Mail” on page 239 This task sends e-mail by implementing the javax.mail APIs. It searches the ancestor tasks for an attachment and automatically sends all the attachments that it finds. The attachments are added to the end of the e-mail body.

“Sql Notify Alert” on page 240 This task inserts a row containing alert notification information into a table in a relational database.

“Sql Properties” on page 241 This task defines a SQL query, executes it, and loads the property name and value pairs from the database providing them to ancestor tasks. The SQL query must use the SQL SELECT statement to select two columns, which represent a name and value.

“Sql Result Set Metadata” on page 241 This task provides metadata result set as an exposed object.

“Sql Statement” on page 242 This task executes a SQL statement.

“URL” on page 242 This task makes a connection to a URL.

“URL Datasource” on page 243 This task creates and provides a URL as a data source so it can be used as an attachment in an e-mail.

“User File Properties” on page 244 This task loads properties with values from a user file. The user file name is equivalent to username.properties. For example, if you log on as Administrator, this task loads the name value pairs defined in the Administrator.properties file.

222 Using Tasks The following table lists the tasks contained in the Core task registry: Table 2 Core Tasks

Core Task Name Description

“Evaluate Scripting Framework Script” on page 245 This task evaluates a script and returns the results.

“Execute Scripting Framework Script” on page 246 This task runs a script. If you want to return a value, you must do it explicitly in the script.

“Get Scripting Framework Member” on page 246 Creates a property in the task framework using a scripting framework member. This provides the ability to utilize the same object within a task and script.

“Grid Export Data Source” on page 247 This task creates a grid in PDF, HTML, or another specified format. You can use this as an attachment in an e-mail.

“Grid Export Manager” on page 247 This task reads in an XML file that defines export options for a grid. For example, it may define the page height, page width and MIME type for a PDF file. Using this information, you can export a grid into a PDF. The grid is defined by the Cube View Grid task or the Query Information Grid task.

“Grid Export” on page 248 This task creates an object and loads it with the XML file read in by the Grid Export Manager task. The Grid Export Data Source task uses this object to specify the export type. This task is always used as shown in the following Task Dependencies section.

“If Scripting Framework Script” on page 249 This task executes its nested tasks based on a condition. It must be set up with at least one child task. A condition consists of a script that returns a Boolean value.

“Repository Object” on page 249 This task retrieves and provides a ATF repository object, such as a folder, view, query, task definition, or scheduled task definition. You use this to retrieve an OLAP View or Relational View. You need to define the tasks to create a connection to the data source before you run the view.

“Scripting Framework” on page 250 Creates a scripting framework that enables you to use ECMA scripts in child tasks.

“Set Scripting Framework Member” on page 251 This task creates a member in the scripting framework using a task property or class. This provides the ability to utilize the same object within a script.

223 The following table lists the tasks contained in the OLAP task registry: Table 3 OLAP Tasks

OLAP Task Name Description

“Add Cube View Cell Value Format Cube Format” on This task specifies a format from the formatting XML file. page 252

“Cube” on page 253 This task accesses the cube object or OLAP database.

“Cube View Cell Value Format Manager” on page 254 This task defines a formatting XML file that specifies formatting for the data cell values in a cube.

“Cube View Cell Value Format” on page 254 This task specifies replacement text for data that is missing, inaccessible, or equivalent to zero.

“Cube View Export Data Source” on page 255 This task exports a cubeView grid to PDF, HTML, or other file type using a view created by the Cube View task. You use this as an attachment in an e-mail.

“Cube View Export Manager” on page 256 This task reads in an XML file that defines export options for an OLAP query. For example, it may define the page height, page width and MIME type for a PDF file. Using this information you can export a query, defined by the Cube View task, into a PDF.

“Cube View Export” on page 256 This task creates an object that contains export options loaded by the Cube View Export Manager task. The Cube View Export Data Source task enables you to specify one of the export options.

“Cube View Grid” on page 257 Use this task to place the cubeView information into a grid so it can be used with the Grid tasks in the Core registry. For example, you can use Grid Export and Grid Export Data Source tasks rather than Cube View Export and Cube View Export Data Source. The advantage to using the Grid tasks is that you can map both a relational or OLAP query to it and then use the same Grid tasks to display the results.

“Cube View” on page 257 This task creates a cube view which contains an OLAP query and access to the query results.

“Schema” on page 258 This task creates a connection to an OLAP schema or application.

The following table lists the tasks contained in the Relational task registry: Table 4 Relational Tasks

Relational Task Name Description

“Add Query Information Cell Value Format Database This task specifies a format from the formatting XML file. Format” on page 260

“JDBC Data Source” on page 261 This task creates a connection to a JDBC data source.

224 Using Tasks The following table lists the tasks contained in the Relational task registry: Table 4 Relational Tasks (Continued)

Relational Task Name Description

“Query Information Cell Value Format Manager” on This task defines a formatting XML file that specifies page 262 formatting options for the data rows in a relational database.

“Query Information Cell Value Format” on page 262 This task specifies replacement text for data that is equivalent to NULL.

“Query Info Export Data Source” on page 263 This task creates a grid in PDF, HTML, or other specified format using query results from a Query Information task. You use this as an attachment in an e-mail.

“Query Info Export Manager” on page 264 This task reads in an export XML file that defines export options for a relational query. For example, using this information you can export query results into a PDF file.

“Query Information Export” on page 264 This task creates an object that contains export options loaded by the Query Information Export Manager task. The Query Information Export Data Source task enables you to select one of the export options.

“Query Information Grid” on page 265 Use this task to place the queryInfo object into a grid so it can be used with the Grid tasks in the Core registry. For example, you can use Grid Export and Grid Export Data Source tasks rather than Query Information Export and Query Information View Export Data Source. The advantage to using the Grid tasks is that you can map both a relational or OLAP query to it and then use the same Grid tasks to display the results.

“Query Information” on page 265 This task creates an object that contains a SQL query and a pointer to the result set.

Using the Task Registry The following information is included for each task:

Task Name Task Name is the name of the task that is displayed on the user interface.

Task Dependencies This is a list of tasks on which TaskName is dependent. For example, the mail task is dependent on the Mail Server task, so any task definition that uses the Mail task must have a Mail Server task defined also: Mail Server Mail

Using the Task Registry 225 Attributes This is a list of attributes for TaskName. All tasks that expose an object have the following attribute:

● Property Name - This attribute defines the property name for the object created by this task. You define the Property Name so other tasks can use this object. This attribute is optional. For example, if the Mail Server task set the Property Name=pmail_server, then other tasks can use the pmail_server to access the information set up in the Mail Server task. Mail Server (Property Name=pmail_server) Mail (Mail Server Property Name = pmail_server)

Note: The Mail task is not nested, so the Mail Server Property Name must be explicitly defined.

Exposed Classes This is the class created by this task or the object type of the Property Name attribute. These objects can be used within a script. For example, if you are searching for a nested cubeView object, you need to know its type. The Cube View task creates the cubeView object. The cubeView object’s type is com.hyperion.ap.IAPQryCubeView. The following code finds an ancestor cubeView object: var rCubeView = task.findAncestorObject(Packages.com.hyperion.ap.IAPQryCubeView);

General Tasks The com.hyperion.atf.services.task class defines general purpose tasks that perform the following functionality:

● Send an e-mail - Use the following sequence of tasks: Mail and Mail Server

● Expose SQL information from a database - Use the following sequence of tasks: Database, Database Metadata, Sql Statement, and Sql Result Set Meta Data

● Send an alert - Each bullet shows a sequence of tasks that send an alert:

❍ Mail server, Mail, Mail Notify Alert

❍ Database, Sql Notify Alert

❍ File Writer, File Notify Alert

● Link or group tasks within a task definition - Use the Link task or the Grouping task respectively.

● Define property values - Use one of the following tasks: File Properties, Fixed Properties, Sql Properties, or User File Properties

● Create a data source that can be e-mailed as an attachment - Each bullet shows a sequence of tasks that create an attachment:

❍ File Input Sream and Data Source

❍ URL and URL Datasource

226 Using Tasks ● Generate an error log -Use the Error Log task.

● Perform Conditional Logic - Use the following tasks Conditionals and Else.

Conditionals This task groups an If Scripting Framework Script task and an Else task. If you are using the Else task, you must also use the Conditionals tasks.

Task Dependencies None

Attributes

None

Property Name Object Type None

Example The following example shows the sequence of tasks that send an e-mail if a condition is satisfied; otherwise, a message is written to a database: Conditionals If Scripting Framework Script Mail Server Mail Else Database Sql Notify Alert

Note: You need the Conditionals task only if you used the Else task.

Database Meta Data This task exposes metadata from a relational database to child tasks.

Task Dependencies Database

General Tasks 227 Attributes

● Database Property Name - The property name of a database object. If this attribute is not specified, the nested ancestor tasks are searched, and the first Database object found is used.

● Property Name - An optional property that exposes the java.sql.DatabaseMetaData object created by this task.

Exposed Classes java.sql.DatabaseMetaData

Example The following example gets the product name from the exposed database metadata and then uses a script to alert the user with the product name. DataBase Database Metadata Execute Scripting Framework Script

(where the script attribute is:var rDbmData=task.findAncestorObject (packages.java.sql.DatabaseMetaData); alert(rDbmData.getDatabaseProductName());

Database This task creates a connection to a relational database and exposes the connection to nested tasks.

Task Dependencies None

Attributes

● JNDI Name - The JNDI name of the relational database; for example, Drill, which is the sample MySql database that is installed with Application Builder.

Note: The JNDI name is mutually exclusive with the other attributes.

● User Id - The user ID to connect to the database

● Password - The password to connect to the database

● Connection URL - The connection string to access the relational database

● Driver Class Name - The name of the driver to connect to the database

● Property Name - An optional property that exposes the java.sql.Connection object created by this task

228 Using Tasks Exposed Classes java.sql.Connection

Example The following example opens a database and exposes the metadata for DB_1, using the Database Meta Data task. If you did not specify DB_1, the Database Meta Data task would have used DB_2, because it is the first property found in the ancestor tasks. DataBase (where property name = DB_1) DataBase (where property name = DB_2) Database Meta Data (where Database Property Name = DB_1)

Data Source This task creates a data source and provides it to nested tasks. For example, you can specify a text file that appears as an attachment in the body of an e-mail. This exposed object can be used by a nested mail task as an attachment.

Task Dependencies None

Attributes

● ContentType - The MIME type and subtype. This attribute is required. The following list shows common MIME types:

❍ application/pdf

❍ text/rtf

❍ text/htm"

❍ application/x-msexcel

❍ application/x-mspowerpoint

❍ text/xml

Note: MIME stands for Multipurpose Internet Mail Extensions for more information, see http://www.nacs.uci.edu/indiv/ehood/MIME/MIME.html

● File Input Stream Property Name - The property name of the object created by the Input Stream task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Input Stream object found is used.

● File Name - The file that you want to expose

● Text - A string of text that is written to the File Name or Input Stream Property Name

General Tasks 229 Note: The Input Stream Property Name attribute and File Name attribute are mutually exclusive.

● Name - The label for the data source. For example, if the data source an e-mail attachment, this name is used to label the attachment. Be sure to include the appropriate file extension name. If this attribute is not defined, the File Name is used. If the File Name is not specified, a system file name is used.

● Property Name - An optional property that exposes the javax.activation.DataSource object created by this task

Exposed Classes javax.activation.DataSource

Example The following tasks send an e-mail that says, “Hello Jane,” with the file mail_message.pdf attached and labeled New_Attachment. MailServer DataSource (where, Name = New_Attachment, ContentType = application/pdf, File Name = c:/temp/mail_message.pdf) Mail (Attributes: [email protected], body=Hello Jane)

Error Log This task creates a file that logs exceptions; messages are appended to an existing file. Place this task before all tasks from which you want to log errors.

Task Dependencies None

Attributes

● Log File Name - The fully qualified file name that you want to create or use. This attribute is required.

● Message Log Format - An extra line of text that you can add to log messages. The message log can be formatted using one or more of the following options:

❍ $(Message) - The error message

❍ $(Date) - The current system date

❍ $(Time) - The current system time

❍ $(DateTime) - The current system date and time

❍ $(ThreadInfo) - The current threads, name, priority, and thread group

230 Using Tasks ❍ $(CallStack) - The current stack values.

Exposed Classes None

Example The following example shows an error message written to the log file, where:

● Log File Name = foo.txt - The file is created or updated.

● Message Log Format = ATF (($DateTime) - ($Message)) - This is the message Log Format Text. ATF (Sep 3, 2003 10:11:33 AM - com.hyperion.ap.APException: [1033] Native: 1042006 [Wed Sep 03 10:11:33 2003]Local////Error(1042006) Network Error [10061]: Unable To Connect To [localhost]. The client timed out waiting to connect to the Essbase Agent using TCP/IP. Check your network connections.) This is the message Log Format Text.

Else This task groups tasks and executes them if the preceding If Scripting Framework Script task condition is False. This task must have an ancestor Conditionals task, that encompasses the If Scripting Framework Script task and Else task.

Task Dependencies Scripting Framework Conditionals If Scripting Framework Script

Attributes

None

Exposed Classes None

Example The following example shows the sequence of tasks that send an e-mail if a condition is satisfied; otherwise the Else tasks are executed that notify a database with a message:

General Tasks 231 Conditionals If Scripting Framework Script Mail Server Mail Else Database Sql Notify Alert

File Input Stream This task opens a file and exposes the input stream of the file. The file is created if it does not exist. This task can be used as input to a Data Source task for an attachment.

Task Dependencies None

Attribute

● File Name - The fully qualified file name that you want to open or create. This attribute is required

● Property Name - An optional property that exposes the java.io.inputStream object created by this task

Exposed Classes java.io.inputStream

Example The following tasks open a file, expose the input stream, and use the file as a datasource for a mail attachment: File Input Stream DataSource Mail Server Mail

File Notify Alert This task creates and provides a standard alert message that is written to a file.

Task Dependencies File Writer

232 Using Tasks Attribute

● File Writer Property Name - The property name of the object created by the File Writer task. If this attribute is not specified, the nested ancestor tasks are searched, and the first File Writer object found is used.

● Message - The message text

● Message Format - The message format, which can be formatted using any of the following options:

❍ $(Condition) - If this notification alert was invoked from a condition task, the condition task's description.

❍ $(Message) - Additional message to be included with this notification alert

❍ $(TaskDefinitionName) - The name of the task definition

❍ $(Timestamp) - The current system date and time

❍ $(UserName) - The name of the user running this task definition A default format is used if one is not specified. Following is the default format: time stamp, user, task definition name, condition, message

Following is an example of a default message: Sep 3, 2003 11:31:50 AM, Administrator, NotifyRising, cell (0,1,1) > 200, Your numbers are rising.

Exposed Classes None

Example The following tasks open a file and write the notification message to it. Root File Writer (where File Name = foo.txt) File Notify Alert (where Message = “Your sales are rising”)

Following is the message: Sep 3, 2003 11:31:50 AM, Administrator, NotifyRising, null, Your sales are rising.

Note: For a working example, see the Notify Rising task definition in the Hyperion Application Administration Tools.

File Writer This task opens a file and writes to it.

General Tasks 233 Task Dependencies None

Attributes

● Append - Set to True to append a message; set to False to start writing at the beginning of the file.

● File Name - The fully qualified file name that you want to open, create, or update. This attribute is required.

● Property Name - An optional property that provides the java.io.FileWriter object, created by this task, to nested tasks.

Exposed Classes java.io.FileWriter

Example The following tasks open a file and write the notification message to it. Root File Writer (where File Name = foo.txt) File Notify Alert (where Message = “Your sales are rising”)

Following is the message: Sep 3, 2003 11:31:50 AM, Administrator, NotifyRising, null, Your sales are rising.

Note: For a working example, see the Notify Rising task definition in the Hyperion Application Administration Tools.

File Properties This task loads properties with values from a specified file. The properties are available to nested tasks. The file that you specify contains property name value pairs.

Task Dependencies None

Attributes ConfigPropertyFileName - The fully qualified property file name that contains property name and value pairs. This attribute is required.

234 Using Tasks Exposed Classes None

Example The following example sends an e-mail using the property values from the WAAUserPropertyFile.properties file. In the Mail Server task, the SMTP Host attribute is set to the property SMTP Host. In the Mail task the Mail From attribute is set to the property Mail From. At runtime the values for these properties are taken from the WAAUserPropertyFile.properties file. File Properties (Attributes: ConfigPropertyFileName = WAAUserPropertyFile.properties) Mail Server (where SMTP Host = SMTP Host) Mail (where Mail From = Mail From)

Following is the WAAUserPropertyFile.properties file that is created during installation, with values entered by the installer: SMTP\ Host=mail.grasp.com Mail\ [email protected] Mail\ User\ Id= Mail\ Password=

Note: You must precede each blank character with the backslash character ( \ ) in a properties file.

Fixed Properties This task defines property name and value pairs at design time. The properties are available to nested tasks. For example, if you have a scheduled task you must define all property values before the task is run. You can use this task, rather than defining the property values in a file.

Task Dependencies None

Attributes

● Property Name - The name of the property

● Property Value - The value for the property

Note: The user should define both the property name and property value attributes. There is no error checking for blank or missing definitions.

Exposed Classes None

General Tasks 235 Example The following example sends an e-mail using the property values defined by the Fixed Properties task: Fixed Properties (where the property name = mail_to, property [email protected]) Mail Server ( Mail (where Mail To = mail_to)

Grouping This task is used to group other tasks. It has no other functionality other than being the root task of a task definition.

Task Dependencies None

Attributes None

Exposed Classes None

Link This task links a task definition, as a nested task, into an existing task definition. If a linked task definition is run manually, the user is not prompted for the linked task’s properties. Those properties must be resolved by an ancestor task using the User File Properties, File Properties, or Fixed Properties task.

Task Dependencies None

Attributes Linked Task Definition Name - The name of the task definition to which you are linking. You must include the full ATF repository path name and task name. This attribute is required. For an example see the hyperion/taskdefiintions/olap/ConditionalDemoBasicReportmailDefintion sample task definition.

236 Using Tasks Exposed Classes None

Example The following example defines TaskCommon and TaskA, which uses the Link task. All linked tasks, such as TaskCommon, must end with a single nested task, because a child cannot have multiple parents. TaskCommon’s properties are resolved by TaskCommon, TaskD or TaskE. They cannot be resolved from TaskA or TaskB. TaskA TaskB Link TaskCommon TaskC TaskCommon TaskD TaskE

The parent and nested tasks are reassigned for the linked task. In the following example, TaskCommon assigns TaskD as a parent task and TaskC as a nested task. The final task definition is as follows: TaskA TaskB TaskD TaskE TaskC

Mail Notify Alert This class creates a standard alert entry that can be incorporated into an e-mail message.

Task Dependencies None

Attributes

● Message - The text to display in the body of the e-mail

● Message Format - The message format can be formatted using any of the following options:

❍ $(Condition) - If this notification alert was invoked from a condition task, the condition task's description

❍ $(Message) - Additional message to be included with this notification alert

❍ $(TaskDefinitionName) - The name of the task definition

❍ $(Timestamp) - The current system date and time

❍ $(UserName) - The name of the user running this task definition

General Tasks 237 A default format is used if one is not specified. Following is the default format: timeStamp, user, task definition name, condition, message

Following is an example of a default message: Sep 3, 2003 11:31:50 AM, Administrator, NotifyRising, null, Your numbers are rising.

● Property Name - An optional property that exposes the java.lang.String object created by this task.

Exposed Classes

java.lang.String

Example For an example see the OneCubeViewTwoConditionalDemoBasicReportMailDefinition sample task. The following task sequence is needed to add the Mail Notify Alert task’s message to the body of the e-mail. Mail Notify Alert MailServer Mail

Mail Server This task connects to a mail server and provides the mail server connection to nested tasks.

Task Dependencies None

Usage Mail Server Mail

Attributes

● SMTP Host - The mail server. This attribute is required.

● SMTP Host Password - The password for the mail server. If the mail server is secured you need this attribute; otherwise it is optional.

● SMTP Host UserId - The user Id for the mail server. If the mail server is secured, this attribute is required; otherwise, it is optional.

238 Using Tasks ● Property Name - An optional property that exposes the javax.mail.Session object created by this task

Exposed Classes javax.mail.Session

Example This example creates a connection to a mail server and sends an e-mail: Mail Server Mail

Mail This task sends e-mail by implementing the javax.mail APIs. It searches the ancestor tasks for an attachment and automatically sends all the attachments that it finds. The attachments are added to the end of the e-mail body. Attachments must be one of the following tasks or classes:

● Data Source

● URL Data Source

● Grid Export Data Source

● Cube View Export Data Source

● Query Info Export Data Source

● a com.hyperion.atf.services.task.AtfDataSourceTask based class.

Task Dependencies Mail Server

Attributes

● Mail Bcc - One or more e-mail addressees for the blind carbon copy (Bcc) recipient

● Mail Cc - One or more e-mail addressees for the carbon copy (Cc) recipient

● Mail From - One e-mail address for the sender. This attribute is required.

● Mail Server Property Name - The property name of the object created by the Mail Server task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Mail Server object found is used.

● Mail Subject - The text that appears on the e-mail subject

● Mail To - One or more e-mail addresses for the recipients. This attribute is required.

● Mail Body - The e-mail content. This can be text, and it can include an attachment.

General Tasks 239 ● Property Name - An optional property that exposes the javax.mail.internet.MimeMessage object created by this task

Exposed Classes javax.mail.internet.MimeMessage

Example This example sends an e-mail to notify an analyst that a specific condition was met: If Scripting Framework Script Mail Server Mail Task

Sql Notify Alert This task inserts a row containing alert notification information into a table in a relational database.

Task Dependencies Database

Attributes

● Database Property Name - The property name of the object created by the Database task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Database object found is used.

● Table Name -The database table name where the row is inserted. If the table does not exist, it is created.

● Message - The message text

Exposed Classes None

Example In the following example, a generic alert notification row is inserted with the message “Check your e-mail” in the ALERT_Log table in the relational database: Database (where JNDI Name = ) SQL Notify Alert (where Table Name = ALERT_LOG, Message = Check your e- mail)

240 Using Tasks Sql Properties This task defines a SQL query, executes it, and loads the property name and value pairs from the database providing them to ancestor tasks. The SQL query must use the SQL SELECT statement to select two columns, which represent a name and value.

Task Dependencies Database

Attributes

● Sql Query - A SQL query statement. This attribute is required.

● Database Property Name - The property name of the object created by the Database task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Database object found is used.

Exposed Classes

None

Example The following example defines the SQL statement SELECT (state id, state name) from city where the Database Property Name is State. When this task is executed, the state id and state name are stored in a list of property names and values; for example, property name = CT and property value = Connecticut. A nested task could specify the property name CT, and the value Connecticut is substituted. Database (where JNDI Name = Drill) Sql Properties (where Query = “Select distinct city_id, city_name from city”)

Sql Result Set Metadata This task provides metadata result set as an exposed object.

Task Dependencies Database SQL Statement

General Tasks 241 Attributes

● Sql Property Name - The property name of an object created by the Sql Statement task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Sql statement object found is used.

● Property Name - An optional property that exposes the java.sql.ResultSetMetaData object created by this task

Exposed Classes java.sql.ResultSetMetaData

Sql Statement This task executes a SQL statement.

Task Dependencies Database

Attributes

● Sql Query - Use the Select, Insert, or Update SQL statement. This attribute is required.

● Database Property Name - The property name of the object created by the Database task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Database object found is used.

● Property Name - An optional property that exposes the java.Sql.ResultSet object created by this task

Exposed Classes

java.Sql.ResultSet

URL This task makes a connection to a URL.

Task Dependencies None

Attributes

● URL - The URL with which to connect. This attribute is required.

242 Using Tasks ● Parameter Name - One or more parameter names appended to the URL

● Parameter Value - One or more parameter values appended to the URL

Note: Parameter Name and Parameter Value must be matching name and value pairs.

● Property Name - An optional property that exposes the java.net.URLConnection object created by this task.

Exposed Classes

java.net.URLConnection

Example See the sample task definition /hyperion/taskdefinitions/HyperionStockPrice-mailDefinition. URL URL Datasource

URL Datasource This task creates and provides a URL as a data source so it can be used as an attachment in an e-mail.

Task Dependencies URL

Attributes

● Name - The label for the data source. For example, if the data source is an e-mail attachment, this name is used to label the attachment. Be sure to include the appropriate file extension.

● URL Property Name - The property name of the object created by the URL task. If this attribute is not specified, the nested ancestor tasks are searched, and the first URL object found is used.

● Property Name - An optional property that exposes the javax.activation.DataSource object created by this task

General Tasks 243 Exposed Classes

javax.activation.DataSource

Example See the sample task definition /hyperion/taskdefinitions/HyperionStockPrice-mailDefinition

User File Properties This task loads properties with values from a user file. The user file name is equivalent to username.properties. For example, if you log on as Administrator, this task loads the name value pairs defined in the Administrator.properties file.

Task Dependencies None

Attributes path - the fully qualified path of the user properties file. If this attribute is omitted, the default Web application root directory is used.

Exposed Classes None

Example The following example sends an e-mail using the property values from the Administrator.properties file. The user Administrator is logged into the application. In the Mail Server task, the SMTP Host attribute is set to the property SMTP Host. In the Mail task, the Mail From attribute is set to the property Mail From. At runtime, the values for these properties are taken from the Administrator.properties file. User File Properties (Attributes: path = /classes) Mail Server (where SMTP Host = SMTP Host) Mail (where Mail From = Mail From)

Following is the Administrator.properties file contents, which contains property name and value pairs: SMTP\ Host=mail.grasp.com Mail\ [email protected]

244 Using Tasks Note: You must precede each blank character with the backslash character ( \ ).

Core Tasks The com.hyperion.waa.utility.core.task class defines general purpose tasks that perform the following functions:

● Define a scripting framework - Use the task Scripting Framework to enable ECMA script to use with conditional statements.

● Use Conditional Logic - Use the following tasks: If Scripting Framework Script and Else If Scripting Framework.

● Pass members between a scripting framework and a task framework - Use the following tasks: Get Scripting Framework Member, Set Scripting Framework Member.

● Run a script - Use the following tasks, Evaluate Scripting Framework, Execute Scripting Framework.

● Create a view that can be e-mailed as an attachment - Use the following tasks: Repository Object, Grid Export Manager, Grid Export, Grid Export Data Source.

Note: The Repository Object task can access an OLAP view or relational view stored in the ATF repository.

Evaluate Scripting Framework Script This task evaluates a script and returns the results.

Task Dependencies Scripting Framework

Attributes

● Script - The ECMA script. This attribute is required.

● Script As Function - Set to True if the script returns a value. If you use the return statement in your script, you must set this to True. If the script does not return a value, set to False. The default is False.

● ScriptingFrameworkPropertyName - The scripting framework’s property name, which is defined by the Scripting Framework task

● Property Name - An optional property that exposes the java.lang.Object object created by this task

Exposed Classes java.lang.Object, which contains the value returned from executing the script

Core Tasks 245 Execute Scripting Framework Script This task runs a script. If you want to return a value, you must do it explicitly in the script.

Task Dependencies Scripting Framework

Attributes

● Script - The ECMA script. This attribute is required.

● Script As Function - Set to True if the script returns a value. If you use the return statement in your script you must set this to True. If the script does not return a value, set to False. The default is False.

● ScriptingFrameworkPropertyName - The scripting framework’s property name, which is defined by Scripting Framework task

Exposed Classes None

Get Scripting Framework Member Creates a property in the task framework using a scripting framework member. This provides the ability to utilize the same object within a task and script.

Task Dependencies Scripting Framework

Attributes

● MemberName - The member name in the scripting framework. This attribute is required.

● PropertyName - The property name that you are creating in the task

● ScriptingFrameworkPropertyName - The scripting framework’s property name, which is defined by Scripting Framework task

● Property Name - An optional property that exposes the java.lang.Object object created by this task

Exposed Classes java.lang.Object

246 Using Tasks Grid Export Data Source This task creates a grid in PDF, HTML, or another specified format. You can use this as an attachment in an e-mail.

Task Dependencies Cube View Grid or Query Information Grid (defines the grid) Grid Export Manager Grid Export

Attributes

● Export Name - The type of export that you want to perform, this name is defined in the Grid Export Manager XML file. For example, if you use the WAAGridExport.xml file, you can specify PDF (Page size: 8.5x11) , RTF (Page size: 8.5x11), or HTML, Excel, or Powerpoint.

Note: Be sure to enter the exact export name defined in the XML file, including spaces.

● Grid Export Property Name - The property name of the object created by the Grid Export task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Grid Export object found is used.

● Grid Property Name - The property name of the object created by the Cube View Grid task or Query Information Grid task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Grid object or Query Information Grid object found is used.

● Property Name - An optional property that exposes the javax.activation.DataSource object created by this task

Exposed Classes javax.activation.DataSource

Grid Export Manager This task reads in an XML file that defines export options for a grid. For example, it may define the page height, page width and MIME type for a PDF file. Using this information, you can export a grid into a PDF. The grid is defined by the Cube View Grid task or the Query Information Grid task.

Task Dependencies None

Core Tasks 247 Attributes

● Config Xml File Name - An XML file that defines export types, for more information, see the Hyperion Application Builder Administrator’s Guide or see the WAAGridExport.xml file which is installed with the -samples application.

Tip: Use a forward slash ( / ) to denote a directory.

● Allow Validation - Set to True to validate the XML file using its .dtd file.

● Property Name - An optional property that exposes the com.hyperion.waa.utility.core.WAAGridExportManager object created by this task

Exposed Classes com.hyperion.waa.utility.core.WAAGridExportManager

Grid Export This task creates an object and loads it with the XML file read in by the Grid Export Manager task. The Grid Export Data Source task uses this object to specify the export type. This task is always used as shown in the following Task Dependencies section.

Task Dependencies Cube View Grid or Query Information Grid (defines the grid) Grid Export Manager Grid Export Grid Export Datasource

Attributes

● Grid Export Manager Property Name - The property name of the object created by the Grid Export Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Grid Export Manager object found is used.

● Grid Export Manager Property Name - The property name of the object created by a parent Grid Export task. This enables you to link Grid Export objects together.

● Property Name - An optional property that exposes the com.hyperion.waa.utility.core.WAAGridExport object created by this task

Exposed Classes com.hyperion.waa.utility.core.WAAGridExport

248 Using Tasks If Scripting Framework Script This task executes its nested tasks based on a condition. It must be set up with at least one child task. A condition consists of a script that returns a Boolean value.

Task Dependencies None

Attributes:

● Else - Set to True if you want to use an Else clause with this task.

● Script - A string that contains the script expression

● Script As Function - Set to True if your script returns a value; otherwise, set to False.

● Scripting Framework Property Name - The property name of the object created by the Scripting Framework task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Scripting Framework object found is used.

Exposed Classes None

Repository Object This task retrieves and provides a ATF repository object, such as a folder, view, query, task definition, or scheduled task definition. You use this to retrieve an OLAP View or Relational View. You need to define the tasks to create a connection to the data source before you run the view.

Task Dependencies None

Attributes

● Full Path - The full path of the repository object, such as /hyperion/olap/TestOlapView

● Property Name -An optional property that exposes the objects created by this task. See the following Exposed Classes, for a list of the possible object types.

Exposed Classes com.hyperion.waa.utility.olap.WAAOlapView com.hyperion.waa.utility.olap.WAARelationalView

Core Tasks 249 com.hyperion.waa.utility.olap.WAAScheduledTaskDefinition com.hyperion.waa.utility.olap.WAATaskDefinition com.hyperion.waa.utility.olap.WAAOlapDataSource com.hyperion.waa.utility.olap.WAARelationalDataSource com.hyperion.waa.utility.olap.WAAWAAFolder

Example The following tasks create a connection to an OLAP data source and use an OLAP View stored in the repository: Schema Cube Repository Object (using the view: /hyperion/olap/Sales Report)

Scripting Framework Creates a scripting framework that enables you to use ECMA scripts in child tasks.

Task Dependencies None

Attributes

● Language - A string that defines the scripting language. Only ECMA script is supported.

Tip: Specify ECMA script without a blank character.

● Scripting Framework Property Name - The property name of the object created by the Scripting Framework task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Scripting Framework object found is used.

● Property Name - An optional property that exposes the com.hyperion.waa.utility.core.WAAScriptingFramework object created by this task

Exposed Classes com.hyperion.waa.utility.core.WAAScriptingFramework

Example The following example uses a scripting framework with ECMA script.

250 Using Tasks Scripting Framework (where Language=ecmascript, Property Name = script_in_ECMA) If Scripting Framework Script (script=”if (true) return true; else return false;“, ScriptingFrameworkPropertyName = script_in_ECMA)

Set Scripting Framework Member This task creates a member in the scripting framework using a task property or class. This provides the ability to utilize the same object within a script.

Task Dependencies Scripting Framework

Attributes

● Class Name - The task class that you are making available to the scripting framework

● Property Name - The property, defined in the task framework, that you are making available to the scripting framework

Note: ClassName and PropertyName are mutually exclusive.

● Member Name - The member name of the member created in the scripting framework

● Scripting Framework Property Name - The property name of the object created by the Scripting Framework task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Scripting Framework object found is used.

Exposed Classes None

OLAP Tasks The com.hyperion.waa.utility.olap class defines OLAP tasks that perform the following functions:

● Create an OLAP view - Use the following tasks: Schema, Cube, Cube View, Cube View Grid.

● Format an OLAP view - Use the following tasks: Cube View Cell Value Format Manager, Cube View Cell Value Format, Add Cube View Cell Value Format Cube Format.

● Convert the OLAP view into a datasource that can be e-mailed as an attachment - Use the following tasks: Cube View Export Manager, Cube View Export, and Cube View Export Data Source.

OLAP Tasks 251 Example The following example create an OLAP view, formats it, exports it to another format, places it in a data source, then e-mails it as an attachment. Schema Cube Cube View Cell Value Format Manager Cube View Cell Value Format Add Cube View Cell Value Format Cube Format Cube View

Cube View Export Manager Cube View Export Cube View Export Data Source Mail Server Mail The following example creates an OLAP View, then maps it to a grid so that the Grid tasks, from the General tasks, can utilize it. The advantage to using the Grid tasks is that you can map a relational view or OLAP view to it and then use the same Grid tasks to display the results. Schema Cube Cube View Cell Value Format Manager Cube View Cell Value Format Add Cube View Cell Value Format Cube Format Cube View

Cube View Grid Grid Export Manager Grid Export Grid Export Data Source

Add Cube View Cell Value Format Cube Format This task specifies a format from the formatting XML file.

Task Dependencies Cube View Cell Value Format Manager Cube View Cell Value Format

Attributes

● Cube View Cell Value Format Manager Property Name - The property name of the object created by the Cube View Cell Value Format Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Cell Value Format Manager object found is used.

● Cube View Cell Value Format Property Name - The property name of the object created by the Cube View Cell Value Format task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Cell Value Format object found is used.

252 Using Tasks ● Schema Property Name - The property name of the object created by the Schema task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Schema object found is used.

● Cube Property Name - The property name of the object created by the Cube task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube object found is used.

The following attributes define the server, product, and schema for the format you are using. They must match the server, product, and schema used in the format XML file.

● Server Name - The name of the server, where the cube and schema reside; or example, localhost if the OLAP server is located on your computer.

● Product Name - The name of the product. This should match the product in the Schema task that you are using; for example, Analytic Services.

● Schema Name - The name of a schema used in the Schema task. For example, Demo is an Essbase schema.

● Cube Name - The name of a cube. For example, Basic is an Essbase sample cube.

● Format Name - The name of the format specified in the XML file. This attribute is required. For example, Default is defined for Demo Basic in the WAAGridExport.xml file.

Exposed Classes None

Example Schema Cube Cube View Cell Value Format Manager Cube View Cell Value Format Add Cube View Cell Value Format

Cube This task accesses the cube object or OLAP database.

Task Dependencies Schema

Attributes

● Schema Property Name - The property name of the object created by the Schema task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Schema object found is used.

● Cube Name - The name of the cube; for example, Basic

OLAP Tasks 253 ● Property Name - An optional property that exposes the com.hyperion.ap.IAPMdCube.class object created by this task

Exposed Classes com.hyperion.ap.IAPMdCube.class

Example Schema Cube

Cube View Cell Value Format Manager This task defines a formatting XML file that specifies formatting for the data cell values in a cube.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.olap.WAACubeViewCellValueFormatManager object created by this task

● ConfigXmlFileName - An XML file that defines OLAP formatting options. For more information, see the Hyperion System 9 BI+ Application Builder J2EE Administrator’s Guide or see the WAACubeViewCellValueFormats.xml file, which is installed with the - samples application.

● AllowValidation - Set to True to validate the XML file using its .dtd file.

Exposed Classes com.hyperion.waa.utility.olap.WAACubeViewCellValueFormatManager

Cube View Cell Value Format This task specifies replacement text for data that is missing, inaccessible, or equivalent to zero.

Task Dependencies Cube View Cell Value Format Manager

254 Using Tasks Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.olap.WAACubeViewCellValueFormat object created by this task

● Cube View Cell Value Format Manager Property Name - The property name of the object created by the Cube View Cell Value Format Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Cell Value Format Manager object found is used.

● Missing Text - The text used to represent missing text

● No Access Text - The text used to represent No Access text

● Zero Text - The text used to represent zero text

Exposed Classes com.hyperion.waa.utility.olap.WAACubeViewCellValueFormat

Cube View Export Data Source This task exports a cubeView grid to PDF, HTML, or other file type using a view created by the Cube View task. You use this as an attachment in an e-mail.

Task Dependencies Cube View Cube View Export

Attributes

● Property Name - An optional property that exposes the javax.activation.DataSource object created by this task

● Cube View Export Property Name - The property name of the object created by the Cube View Export task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Export object found is used.

● Cube View Property Name - The property name of the object created by the Cube View task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View object found is used.

● Cube View Cell Value Format Property Name - The property name of the object created by the Cube View Cell Value Format task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Cell Value Format object found is used.

● Export Name - The type of export that you want to perform. This name is defined in the Cube View Export Manager XML file. For example, if you use the WAAGridExport.xml file, you can specify PDF (Page size: 8.5x11), RTF (Page size: 8.5x11), or HTML, Excel, or Powerpoint.

OLAP Tasks 255 Note: Be sure to enter the exact export name defined in the xml file including spaces.

Exposed Classes javax.activation.DataSource

Cube View Export Manager This task reads in an XML file that defines export options for an OLAP query. For example, it may define the page height, page width and MIME type for a PDF file. Using this information you can export a query, defined by the Cube View task, into a PDF.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.core.WAACubeViewExportManager object created by this task.

● ConfigXmlFileName - An XML file that defines export types, for more information, see the Hyperion System 9 BI+ Application Builder J2EE Administrator’s Guide or see the WAAGridExport.xml file which is installed with the sample application.

● AllowValidation - Set to True to validate the XML file using its .dtd file.

Exposed Classes com.hyperion.waa.utility.core.WAACubeViewExportManager

Cube View Export This task creates an object that contains export options loaded by the Cube View Export Manager task. The Cube View Export Data Source task enables you to specify one of the export options.

Task Dependencies Cube View Export Manager

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.olap.WAACubeViewExport object created by this task

256 Using Tasks ● Cube View Export Manager Property Name - The property name of the object created by a parent Cube View Export task. This enables you to link Cube View export objects together.

● Cube View Export Manager Property Name - The property name of the object created by the Cube View Export Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Export Manager object found is used.

Exposed Classes com.hyperion.waa.utility.olap.WAACubeViewExport

Cube View Grid Use this task to place the cubeView information into a grid so it can be used with the Grid tasks in the Core registry. For example, you can use Grid Export and Grid Export Data Source tasks rather than Cube View Export and Cube View Export Data Source. The advantage to using the Grid tasks is that you can map both a relational or OLAP query to it and then use the same Grid tasks to display the results.

Task Dependencies Schema Cube Cube View

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.olap.WAACubeViewGrid object created by this task.

● Cube View Property Name - The property name of the object created by the Cube View task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View object found is used.

● Cube View Cell Value Format Property Name - The property name of the object created by the Cube View Cell Value Format task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube View Cell Value Format object found is used.

Exposed Classes com.hyperion.waa.utility.olap.WAACubeViewGrid

Cube View This task creates a cube view which contains an OLAP query and access to the query results.

OLAP Tasks 257 Task Dependencies Schema Cube

Attributes

● The OLAP query is defined by one of the following attributes:

❍ Expression Text - The OLAP query expression text. For example: SELECT "*" FROM "Basic" PROJECT "Market" ON EDGE ROW WITH (SELECT "Name" FROM "Market" WHERE Member("New_York", "Market"), Member("Boston", "Market"), Member("Chicago", "Market") ) PROJECT "Year" ON EDGE COLUMN WITH (SELECT "Name" FROM "Year" WHERE Member("Jan", "Year"), Member("Feb", "Year"), Member("Mar", "Year") ) PROJECT "Product", "Accounts", "Scenario" ON EDGE SLICER WITH (SELECT "Name" FROM "Product" WHERE Member("Stereo", "Product") ),(SELECT "Name" FROM "Accounts" WHERE Member("Sales", "Accounts") ),(SELECT "Name" FROM "Scenario" WHERE Member("Actual", "Scenario") )

❍ Expression File - The fully qualified file name, of the file containing the expression text for the OLAP query.

❍ Input Stream Property Name - The property name of the object created by the Input Stream task which contains OLAP query expression text.

❍ Repository Property Name - The property name of the object created by the Repository Object task. This must be a OLAP View object that contains OLAP ALE query expression text.

Note: If the OLAP query is not defined by the attributes above, the ancestor tasks are searched for a Input Stream object and a Repository Object object.

● Expression Type - Use to specify the expression type of the query. Valid values are ALE, MDX and XML.

● Cube Property Name - The property name of the object created by the Cube task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Cube object found is used.

● Property Name - An optional property that exposes the com.hyperion.ap.IAPQryCubeView object created by this task

Exposed Classes com.hyperion.ap.IAPQryCubeView

Schema This task creates a connection to an OLAP schema or application.

258 Using Tasks Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.ap.IAPDomain object created by this task

● Name - The schema name, for example Demo. If you are using WAADataSources.xml you need to enter the Schema id, such as LocalHost Essbase Demo.

● URI - The URI to connect to the OLAP schema

Note: The URI is mutually exclusive with the attributes Remote Server Name, Server Name, and Driver Name.

● Remote Server Name - The remote server name

● Server Name - The name of the server where the schema is located. For example, use localhost if the OLAP server is located on your computer.

● Driver Name - The driver to connect to the OLAP schema; for example, HssEssDriver

● User Id- The user ID needed to access the OLAP schema

● Password - The password needed to access the OLAP schema

● Password Encrypted - Set to True to encrypt passwords.

Exposed Classes com.hyperion.ap.IAPDomain

Relational Tasks The com.hyperion.waa.utility.relational class defines relational tasks that perform the following functionality:

● Create a relational view - Use the following tasks: JDBC Data Source, Query Information, Query Information Grid.

● Format a relational view - Use the following tasks: Query Information Cell Value Format Manager, Query Information Cell Value Format, Add Query Info Cell Value Format Database Format.

● Convert the relational view into a datasource that can be e-mailed as an attachment - Use the following tasks: Query Information Export Manager, Query Information Export, Query Information Export Data Source

Relational Tasks 259 Examples This example creates a relational view, formats it, exports it to another format, places it in a data source, then e-mails it as an attachment. JDBC Datasource Query Information Cell Value Format Manager Query Information Cell Value Format Add Query Info Cell Value Format Cube Format Query Information

Query Information Export Manager Query Information Export Query Information Export Data Source Mail Server Mail The following example creates a relational view, formats it, and maps it to a grid, so that the Grid tasks, from the General tasks, can utilize it. The advantage to using the Grid tasks is that you can map a relational view or OLAP view to it and then use the same Grid tasks to display the results. JDBC Datasource Query Information Cell Value Format Manager Query Information Cell Value Format Add Query Info Cell Value Format Cube Format Query Information Query Information Grid

Grid Export Manager Grid Export Grid Export Data Source Mail Server Mail

Add Query Information Cell Value Format Database Format This task specifies a format from the formatting XML file.

Task Dependencies Query Information Cell Value Manager Query Information Cell Value Format

Attributes

● Query Information Cell Value Format Manager Property Name - The property name of the object created by the Query Information Cell Value Format Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information Cell Value Format Manager object found is used.

260 Using Tasks ● Query Information Cell Value Format Property Name - The property name of the object created by the Query Information Cell Value Format task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information Cell Value Format object found is used.

● Format Name - The format name defined in the XML file loaded by the Query Information Cell Value Format Manager. The server name and database name must match those in the formatting XML file.

● Server Name - The name of the server where the database resides

● Database Name - The name of the database

Note: The Server Name and Database Name are mutually exclusive with the JDBC Data Source Property Name.

● JDBC Data Source Property Name - The property name of the object created by the JBDC Data Source task

Note: If you do not define the Server Name, and Database Name attributes, the ancestor tasks are searched for the JDBC Data Source task.

Exposed Classes None

JDBC Data Source This task creates a connection to a JDBC data source.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.relational.WAAJdbcDataSource object created by this task.

● Connection URL - The URL to connect to the JDBC database.

Tip: Specify the Connection URL or the JNDI Name and Driver Class Name.

● JNDI Name - The JNDI name of the relational database

● Driver Class Name - The driver class name to connect to the JDBC database

● User Id - The user ID to access the JDBC database

Relational Tasks 261 ● Password - The password to access the JDBC database

● Password Encrypted - Set to True to indicate that the password is encrypted.

Exposed Classes com.hyperion.waa.utility.relational.WAAJdbcDataSource

Query Information Cell Value Format Manager This task defines a formatting XML file that specifies formatting options for the data rows in a relational database.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.relational.WAAQueryInfoCellValueFormatManager object created by this task

● ConfigXmlFileName - The name of an XML file that defines relational formatting options. For more information, see the Hyperion System 9 BI+ Application Builder J2EE Administrator’s Guide or see the WAAQueryInfoCellValueFormats.xml file which is installed with the -samples application.

● AllowValidation - Set to True to validate the XML file using its .dtd file.

Exposed Classes com.hyperion.waa.utility.relational.WAAQueryInfoCellValueFormatManager

Query Information Cell Value Format This task specifies replacement text for data that is equivalent to NULL.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.relational.WAAQueryInfoCellValueFormat object created by this task.

262 Using Tasks ● Query Information Cell Value Format Manager Property Name - The property name of the object created by the Query Information Cell Value Format Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first object found is used.

● Null Text - The string to use for a data cell that contains NULL data.

Exposed Classes com.hyperion.waa.utility.relational.WAAQueryInfoCellValueFormat

Query Info Export Data Source This task creates a grid in PDF, HTML, or other specified format using query results from a Query Information task. You use this as an attachment in an e-mail.

Task Dependencies Query Info Query Info Export Manager (optionally) Query Info Export

Attributes

● Property Name - An optional property that exposes the javax.activation.DataSource object created by this task

● Query Information Export Property Name - The property name of an object created by the Query Information Export task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information Export object found is used.

● Query Information Property name - The property name of an object created by the Query Information task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information object found is used.

● Query Information Cell Value Format Property Name - The property name of an object created by the Query Information Cell Value Format Property task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information Cell Value Format Property object found is used.

● Export Name - The type of export you want to perform, this name is defined in the Query Info Export Manager XML file. For example, if you use the WAAGridExport.xml file you can specify PDF (Page size: 8.5x11) , RTF (Page size: 8.5x11), or HTML, Excel, or Powerpoint.

Tip: Be sure to enter the exact export name defined in the XML file including spaces.

Relational Tasks 263 Exposed Classes javax.activation.DataSource

Query Info Export Manager This task reads in an export XML file that defines export options for a relational query. For example, using this information you can export query results into a PDF file.

Task Dependencies None

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.core.WAAQueryInfoExportManager object created by this task.

● ConfigXmlFileName - An XML file that defines export types, for more information, see the see the Hyperion System 9 BI+ Application Builder J2EE Administrator’s Guide or see the WAAGridExport.xml file which is installed with the Sample Application.

● AllowValidation - Set to True to validate the XML file using its .dtd file.

Exposed Classes com.hyperion.waa.utility.core.WAAQueryInfoExportManager

Query Information Export This task creates an object that contains export options loaded by the Query Information Export Manager task. The Query Information Export Data Source task enables you to select one of the export options.

Task Dependencies Query Information Export Manager

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.olap.WAAQueryInfoExport object created by this task.

● Query Info Export Manager Property Name - The property name of the object created by the Query Info Export Manager task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Info Export Manager object found is used.

264 Using Tasks ● Query Info Export Property Name - The property name of the object created by a parent Query Information Export task. This enables you to link Query Information Export objects together.

Exposed Classes com.hyperion.waa.utility.olap.WAAQueryInfoExport

Query Information Grid Use this task to place the queryInfo object into a grid so it can be used with the Grid tasks in the Core registry. For example, you can use Grid Export and Grid Export Data Source tasks rather than Query Information Export and Query Information View Export Data Source. The advantage to using the Grid tasks is that you can map both a relational or OLAP query to it and then use the same Grid tasks to display the results.

Task Dependencies JDBC Data Source Query Information

Attributes

● Property Name - An optional property that exposes the com.hyperion.waa.utility.relational.WAAQueryInfoGridTask object created by this task.

● Query Information Property Name - The property name of the object created by the Query Information task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information object found is used.

● Query Information Cell Value Format Property Name - The property name of the object created by the Query Information Cell Value Format task. If this attribute is not specified, the nested ancestor tasks are searched, and the first Query Information Cell Value Format object found is used.

Exposed Classes com.hyperion.waa.utility.relational.WAAQueryInfoGridTask

Query Information This task creates an object that contains a SQL query and a pointer to the result set.

Task Dependencies JDBC Data Source

Relational Tasks 265 Attributes

● The SQL query is defined by one of the following attributes:

❍ Repository Object Property Name - The property name referring to the Relational View object created by the Repository Object task

❍ Input Stream Property Name - The property name of the object created by the Input Stream task which contains the expression text

❍ Expression File - The fully qualified name of the file containing the expression text for the SQL query

❍ Expression Text - The SQL query expression text

Note: If one of the attributes above is not specified, the nested ancestor tasks are searched, and the first Input Stream object or Repository Object object found is used.

● Property Name - An optional property that exposes the com.hyperion.waa.utility.relational.WAAQueryInfo object created by this task

● JDBC Data Source Property name - The name of a specific JDBC Data Source object

Exposed Classes com.hyperion.waa.utility.relational.WAAQueryInfo

Example The following example defines a Query Information task. The JDBC datasource connection from the JDBC Datasource parent task is used. Root JDBC Datasource Query Information (where Expression Text = value:“Select distinct city_id, city_name from city”)

266 Using Tasks APPENDIX Setting up OLAP Data Sources B and ADM Pooling

This appendix describes how to set up the data source XML file to define ADM pooling. You use the data source XML file with the following WAA tags:

● The useDataSourceTreeBean tag, generates an HTML control to display the data sources.

● The useDataSourcePoolManager tag, implements the ADM pooling.

The data source XML file is read when the Application Builder application starts.

Note: The WAADataSources.xml file is the default data source XML file installed with Application Builder.

The following sections describe how to specify the ADM pooling information in a data source XML file:

● “Specifying the Data Source XML File Name” on page 268

● “Defining the OLAP Data Source and Cube” on page 268

● “Defining the ADM pool” on page 270

● “Defining the ADM Pool Configuration” on page 271

● “Encrypting Passwords” on page 272

● “Data Source XML File Examples” on page 273

You must always have one tag defined. The first tag defined is used internally and is not displayed in your Data Source Tree. The following guidelines apply to a data source configuration:

● You can, optionally, define the server and driver.

● You must define a OLAP data source and cube.

● Each OLAP data source can have multiple cubes.

● Each cube can have multiple ADM pools. You must have at least one ADM pool for each cube. The ADM pools are defined within the tag.

● You must define a ADM pool configuration for each ADM pool.

Setting up OLAP Data Sources and ADM Pooling 267 Specifying the Data Source XML File Name You must specify the name of your data source XML file in the Web.xml file. The web.xml file specifies initialization parameters. The following web.xml snippet specifies the WAADataSources.xml file: DataSourcesXMLFile /WAADataSources.xml File with data source information for application servers which don't provide a JNDI hook

The following table defines and describes the tags that are used in the web.xml file Table 5 Web.xml XML Tag Descriptions

XML Tag Value Description

None Defines initialization parameters

DataSourcesXMLFile Defines the type of XML file

XML file name Defines the XML file name. For example, the default WAADataSources.xml file is installed with the Sample Application.

Defining the OLAP Data Source and Cube After you define the server and driver, you must define the OLAP data source. Using the tags and their descriptions from Table 6 on page 269, define the OLAP data source according to your own OLAP data source and cube. The following code defines the Hyperion Analytic Services Demo application, Basic database/cube, on the local computer using the adm:native:ProductName Product. True root This root node is not displayed localhost Local machine Essbase/Name> OLAP data stored in Essbase

268 Setting up OLAP Data Sources and ADM Pooling localhost Essbase Demo Demo Sample Application adm:thin:com.hyperion.ap.ees.EESHssDriver:localhost:Demo?user=sys tem;password=password;locale=en;domain=essbase;olapServer=localhost;orbT ype=TCPIP;port=5001;useConnPool=false;connPerOp=false;useCluster=false Basic Basic Standard database

The following table defines the tags used in defining an OLAP data source: Table 6 OLAP Data Source XML Tags

Tag Description

Defines password encryption. Set this to True if you encrypt your OLAP data source user’s passwords; otherwise, set it to False. If you use encryption, you must encrypt all the passwords in the data source XML file file. For more information, see “Encrypting Passwords” on page 272.

Defines a OLAP data source or a cube. This must be a unique name.

Defines a level displayed in the tree structure of the useDataSourceTreeBean tag. You must always have one tag defined. The first tag defined is used internally and does not appear in your useDataSourceTreeBean tag. Additional tags are optional and used for display purposes only.

Defines the OLAP data source, and encompasses the OLAP data source, cube, and ADM pool definitions.

Defines the text displayed in the name column of the useDataSourceTreeBean tag. You use Name to define the following components:

● server

● driver

● OLAP data source

● cube

Defines the text displayed in the description column of the useDataSourceTreeBean tag. For each tag, you define a tag.

Defining the OLAP Data Source and Cube 269 Table 6 OLAP Data Source XML Tags (Continued)

Tag Description

Defines the ADM connection string for the OLAP data source. This is case- sensitive. adm:driver type:driver:server:data source where driver type is thin or native, driver defines the specific driver, and server defines the server. If you are using a Star Schema data source, this defines the DataSourceid. data source defines the OLAP data source or application. Examples of : StarSchema, Demo application adm:thin:com.hyperion.ap.starschema.SSHssDriver:localhost:SSDemo Analytic Services, Demo application- adm:native:ProductName:localhost:Demo Financial Management, Sample Application adm:native:HsvADMDriver:localhost:Simple For more information, see the IAPMDdomain OpenConnection() interface in the Hyperion System 9 BI+ Application Builder J2EE Analytic Data Model Devleoper’s Guide.

Defines the database.

Defining the ADM pool Each cube uses one or more ADM pools. You must define the name of the ADM pool to be identical to the J2EE application user’s role or the SSO users group. Use the XML tags described in Table 7 on page 271 to define the ADM pools. The application user’s J2EE role or SSO group is used to map to an ADM pool. For example, if a J2EE role or SSO group is _Analyst, then you must have an ADM pool with the name _Analyst. All Application Builder users with the J2EE role or SSO group _Analyst will use the ADM pool named _Analyst.

Note: _Admin is a predefined J2EE role or SSO group. You grant the _Admin J2EE role or SSO group to a Application Builder user in order to access the Administration tools to perform administrative tasks, such as user administration, xml file editing and so on.

If a Application Builder user has more than one J2EE role or SSO group, the first matching ADM pool defined in the data source XML file is used.

Note: You must define at least one ADM pool for each J2EE role or SSO group.

270 Setting up OLAP Data Sources and ADM Pooling Example of ADM pool Definition The following sample code provides an example of a ADM pool definition: _Analyst PP1 hyperion solutions

The following table defines the tags used in ADM pooling: Table 7 ADM Pool XML Tags

Tag Description

Defines the name of the ADM pool to service the cube. You can define multiple ADM pools for a cube.

Identifies the ADM pool configuration to use. You define the ADM pool configuration using the tag.

Defines the name of the ADM pool. The name should match one of the J2EE roles or SSO groups defined for your application users. which were set up using your application server. Application Builder matches the J2EE role or SSO group of a Application Builder user to the ADM pool name and retrieves an ADM connection from that ADM pool. You can define multiple ADM pools for a cube.

Defines the OLAP data source user id that is used to connect to the cube. This tag is case-sensitive.

Defines the OLAP data source user id’s password that is used to connect to the cube. If you are using encryption, all your OLAP data source user passwords must be encrypted. This tag is case-sensitive. For more information, see “Encrypting Passwords” on page 272.

Defining the ADM Pool Configuration After you define the OLAP data source, cube, and ADM pool, you must define the ADM pool configuration. This information is used to identify the ADM pool as well as the number of ADM connections allowed simultaneously. The following sample code provides an example of a ADM pool configuration. For a definition of the tags used in ADM pooling, refer to Table 8 on the following page. PP1 1000 3 1800 0.4 30 3 2 false

Defining the ADM Pool Configuration 271 The following table defines the tags used in ADM pool configuration. Table 8 ADM pool Configuration

XML Tag Description

Defines the ADM pool configuration which can be used by ADM pools.

Defines the ADM pool's identification which must be unique.

Defines the maximum number of open ADM connections at one time.

Defines the minimum number of open ADM connections at one time.

Defines the period of inactivity before an ADM connection is automatically returned to the ADM pool. The Min number of ADM connections always stays open.

Defines the ratio between the number of ADM instances and the number of connection instances. For example, a ratio of 1/2 or 0.5 creates one connection for every two ADM users.

Defines the frequency in seconds with which inactive connections are checked.

Defines the time in seconds to wait before retrying to acquire a connection after the previous attempt.

Defines the number of times to retry acquiring a connection before throwing an exception.

If this tag is set to True, a background thread checks for frozen connections. If it is set to False, no action is taken.

Note: The times are defined in seconds.

Encrypting Passwords You use the XML tag to encrypt the OLAP user’s passwords specified in the data source XML file. If you set the encryption XML tag to true, you must encrypt all the OLAP user’s passwords manually using the Java setPassword class. You use the Java setPassword class to encrypt passwords. The encrypted password is automatically written into the data source XML file.

➤ To encrypt an OLAP data source user’s password: 1 Navigate to the directory where the data source XML file is located. 2 Set the encryption XML tag to true, in the data source XML file.

Note: Ensure that your classpath includes the adm.jar file.

3 Use the following Java class:

272 Setting up OLAP Data Sources and ADM Pooling java com.hyperion.ap.adm.cache.SetPassword

Note: You must encrypt all the OLAP user passwords in the data source XML file.

The following table defines SetPassword parameters: Table 9 SetPassword Parameters

Variable Definition

The name of the data source XML file containing data source and ADM pooling information

The OLAP data source id defined in the data source XML file with the and tags

OLAP data source user name

The OLAP data source user name’s password

The following example encrypts the password for the Hyperion Analytic Services user User_ReadOnly, which is defined in the WAADataSources.xml file: java com.hyperion.ap.adm.cache.SetPassword WAADataSources.xml "localhost Essbase6 Demo" User_ReadOnly password

Data Source XML File Examples The following examples describe the contents of the WAADataSources.xml file, which is the data source XML file installed with the Sample Application. The data source XML file is used by the following Quick Builder components:

● The useDataSourceTreeBean tag, which shows the data sources.

● The useDataSourcePoolManager tag, which implements ADM pooling.

Defining OLAP Data Sources in Tree Format The following XML code defines OLAP data sources in tree format: root This root node is not displayed

localhost Local machine

Data Source XML File Examples 273 Essbase Driver for Essbase Version/Description> LocalHost Essbase Demo Demo Sample application adm:thin:com.hyperion.ap.ees.EESHssDriver:localhost:Demo?us er=system;password=password;locale=en;domain=essbase;olapServer=localhos t;orbType=TCPIP;port=5001;useConnPool=false;connPerOp=false;useCluster=f alse Basic Basic Standard database _Analyst PP1 analyst password

The following figure shows three levels in the tree, which are server, driver, and OLAP data source:

Figure 1 Data Sources Displayed in Tree Format

Note: You use the useDataSourceTreeBean tag to display the data sources specified in the WAADataSources.xml file.

274 Setting up OLAP Data Sources and ADM Pooling Defining OLAP Data Sources in a Flat List The following XML code defines OLAP data sources in a flat list: root This root node is not displayed LocalHost Essbase Demo Demo Sample Application adm:thin:com.hyperion.ap.ees.EESHssDriver:localhost:Demo?user=sys tem;password=password;locale=en;domain=essbase;olapServer=localhost;orbT ype=TCPIP;port=5001;useConnPool=false;connPerOp=false;useCluster=false Basic Basic Standard database _Analyst PP1 analyst password localhost:starschema:Demo SSDemo Standard application adm:thin:com.hyperion.ap.starschema.SSHssDriver:localhost:SSDemo< /URL> Basic Basic Standard database _Analyst PP1 analyst password

The following figure shows the WAADataSources.xmlfile in list format:

Data Source XML File Examples 275 Figure 2 Data Sources Displayed in List Format

Note: You use the useDataSourceTreeBean tag to display the data sources specified in the WAADataSources.xml file.

WAADataSources.xml File This example shows how to define Analytic Services and Star Schema data sources and ADM pools. It also illustrates how J2EE users are mapped to ADM pools. The following table shows the J2EE users, ADM pools, and Analytic Services user ids used in this example: Table 10 Application Users and ADM Pooling Example

Application User J2EE role or Application User id SSO group and ADM Pool Analytic Services User id/Password

analyst _analyst analyst/password

viewer _Viewer viewer/password

The J2EE users utilize the ADM pools in the WAADataSources.xml file that match their J2EE roles. For example, the application user analyst implements the HAB_Analyst ADM pool and logs on to Analytic Services as analyst/password. true false root This root node is not displayed

276 Setting up OLAP Data Sources and ADM Pooling localhost Local machine Essbase 6 Driver for Essbase Version 6.x LocalHost Essbase6 Demo Demo Sample Application adm:thin:com.hyperion.ap.ees.EESHssDriver:localhost:Demo?us er=system;password=password;locale=en;domain=essbase;olapServer=localhos t;orbType=TCPIP;port=5001;useConnPool=false;connPerOp=false;useCluster=f alse Basic Basic Standard database _Analyst PP1 analyst password _Viewer PP1 viewer password

Data Source XML File Examples 277 278 Setting up OLAP Data Sources and ADM Pooling APPENDIX Setting Up Relational Data C Sources

This appendix describes how to set up XML files for your relational data sources. You use a relational data source for the following purposes:

● To query relational data directly

● To drill-through from summarized and calculated data stored in your OLAP data source into detailed data stored in a relational data source

● As a ATF repository that stores and secures internal objects., such as views and queries

● As an annotation repository that stores WAA annotations

Note: The blank character is not supported for relational database column names. For example, the column name “City State” is invalid and the column name “City_State” is valid.

Setting Up Relational Data Sources This section describes how to specify relational data sources in the web.xml file and in the data source XML file. You specify the name of your data source XML file in the web.xml file. The web.xml file specifies initialization parameters. The following web.xml snippet specifies the WAADataSources.xml file: DataSourcesXMLFile /WAADataSources.xml The following table defines and describes the tags that are used in the web.xml file: Table 11 Web.xml Tag Descriptions

XML Tag Value Description

None Defines initialization parameters.

DataSourcesXMLFile Defines the type of XML file.

XML file name Defines the XML file name. For example, the default WAADataSources.xml file is installed with the Sample Application.

Setting Up Relational Data Sources 279 You also specify the name of your relational data sources in the web.xml file. The following web.xml snippet specifies the and Drill MySQL relational data sources which are installed with the Typical installation, and used by the Sample Application: JDBC data source for views and formats jdbc/ javax.sql.DataSource Container JDBC data source for drill through jdbc/Drill javax.sql.DataSource Container

The data source XML file specifies how to display the relational data sources and is used with the useDataSourceTreeBean tag. The following WAADataSources.xml snippet specifies the and Drill MySQL data sources used by the Sample Application. root This root node is not displayed Relational Relational data 's query data true Drill Drill 's sample drill-through data Drill true

280 Setting Up Relational Data Sources The following table describes the tags used to define a relational data source. Table 12 Data Source XML file Tags

Tag Description

Defines a level displayed in the tree structure of the useDataSourceTreeBean tag. You must always have one tag defined. The first tag defined is used internally and does not appear in your data source tree. Additional tags are optional and used for display purposes only.

Defines the text displayed in the description column of the WAADataSourceTree.jsp table. For each tag, you define a tag.

Encompasses the id, Name, Description, URL, and UserProperty tags.

Specifies the data source name.

Defines the text displayed in the name column of the useDataSourceTreeBean tag.

Name of the JDBC relational data source that you created in your application server. The user id and password are specified in your application server.

Using a WAA Drill-Through You use WAA drill-through to navigate from the summarized and calculated data stored in your OLAP data source into detailed data stored in a relational data source. drill-through queries are written in SQL. OLAP databases are optimized for analysis of summary data, but this is insufficient information for many applications. Therefore, applications implement drill-through from OLAP data back to supporting or detailed transactional data in a relational database. For example, you might use an OLAP data source to analyze retail sales for the first quarter in the Eastern region. Detailed data, such as a list of customers who purchased a particular product in a particular size, is not used during the normal course of analyzing business performance. However, as you analyze sales results, you may want to view this detailed information using the drill-through function. You use the following tags to perform a WAA drill-through:

● useDrillThroughManager - This tag specifies the XML configuration file that defines the mapping between the OLAP data source and the SQL data source

● useDrillThroughQueryInfo - This tag executes the drill-through functionality and optionally defines the object that will accept a response to a prompt.

● useDrillThroughResultListBean - This tag generates HTML to display the results of a drill- though from an OLAP cell to a relational query.

Before you can use drill-through, you must perform the following tasks:

Using a WAA Drill-Through 281 ● “Enabling Drill-Through in the Web.xml File” on page 282

● “Defining the WAADrillThrough.xml Tags” on page 282

Before You Begin In order to use the drill-through function, you need to understand the following concepts:

● The basic concepts, features, and tables of your selected data source. For example, if you are using Oracle, you need an understanding of Oracle schema and administrative tasks.

● Setting up JDBC pooling for your relational data source. For more information, refer to the section on creating and configuring a JDBC data source in the relevant application server chapter of the Hyperion System 9 BI+ Application Builder J2EE Administrator’s Guide.

● SQL query concepts and syntax. For a list of the SQL statements that Application Builder supports, see the Hyperion System 9 BI+ Application Builder J2EE System Administrator’s Guide.

Enabling Drill-Through in the Web.xml File The web.xml file specifies initialization parameters to enable drill-through. The following web.xml snippet enables drill-through and specifies a drill-through XML file, which is named WAADrillThrough.xml. DrillThroughXMLFile /WAADrillThrough.xml File with information to allow drill-through from OLAP to relational data sources

JDBC data source for drill-through jdbc/Drill javax.sql.DataSource Container

Defining the WAADrillThrough.xml Tags This section describes the WAADrillThrough.xml tags.

282 Setting Up Relational Data Sources The following tables list the drill-through XML tags, values, and description:

Table 13 Drill-Through XML Tags

Tag Attribute(s) Description

none Used to define the relational drill- through. This tag encompasses all the information in the XML file.

Name Specifies the text name of your OLAP server. This tag encompasses all mapping and queries for this server, allowing for different drills for the same application and cube but a different server. For example, you could have the Demo application and Basic cube set up in both Analytic Services and Financial Management data sources and specify a driver for each.

Name Specifies the OLAP driver. This tag Valid Values are: encompasses all mapping and queries for this driver, allowing for ● "Hyperion Essbase" different drills for the same ● "Hyperion Financial application and cube but a different Management" driver.

● "Star Schema"

● "Hyperion Planning"

● "Hyperion Enterprise"

Name Specifies the OLAP application. This tag encompasses all mapping and queries for this application.

Name Specifies the OLAP cube. This tag encompasses all mapping and queries for this cube.

Using a WAA Drill-Through 283 The following table describes the XML tags that map OLAP members to relational members: Table 14 Drill-Through XML File Tags to Map OLAP and Relational Members

Tag Contents/Attribute(s) Description

Name Specifies the OLAP dimension.

● Contents ( ALE member query that specifies ) the members that are drillable or non-drillable.

● True - Enables drill-through for ● Drillable all cells that match the member selection.

● False - Disables drill-through for all cells that match the member selection. Enables or disables drill-through for members using the results of an ALE member query.

Name Specify the text name of your OLAP member.

Name Specify the text name of the relational value from the relational table and column.

Data Source Name The JNDI name to a pooled data source.

Id, Name and Description The Id, Name and Description that you assign to the relational database.

284 Setting Up Relational Data Sources The following table describes the XML tags and keywords in the SQL query: Table 15 Drill-Through XML tags to Specify an SQL Query

Tag or Keyword Value Description

< Query> Name description The text describing the drill-through query.

Contents Specifies the SQL Query executed to get the drill-through results.

Setting Up the Drill-Through File This section describes how to set up drill-through XML file and uses code snippets from the WAADrillThrough.xml file which is used by the Sample Application.

Specifying the OLAPServer, OLAPProduct, OLAPSchema and OLAPCube tags You can have one or more instances of the OLAPServer, OLAPProduct, OLAPSchema, and OLAPCube tags. The Name attributes must match the OLAP ADM connection names. For example, if the user is connected to the adm:native:HssEssDriver:sunyserver1:Demo application, Basic cube, the corresponding tag is as follows: …...

Specifying the OLAPQuery Tag Globally You use an OLAPQuery tag to set the members retrieved from the query to drillable or non- drillable. If the OLAPQuery tag is not nested in a JDBC tag, the drillable or non-drillable ability is applied globally to all members retrieved from the query.

Note: If the OLAPQuery tag is nested inside a JDBC tag, the drillable or non-drillable ability is applied locally to all members retrieved from this query, overriding the global settings. For more information, see “Specifying the OLAPQuery Tag Locally” on page 287.

You can have one instance of an OLAPQuery tag nested in an OLAP Dimension tag. Setting the value of the Drillable attribute to False specifies an exclusion list. A value of True specifies an inclusion list. The OLAPQuery is an ADM ALE query. All dimension inclusion/exclusion lists specified within a cube are used to determine whether a cell is drillable or non-drillable. By default, a dimension and all it's members are drillable unless otherwise specified.

Using a WAA Drill-Through 285 The following example would disable drill-through for the Year, Qtr1, Qtr2, Qtr3 and Qtr4 members: ... ... SELECT "Name" FROM "Year" WHERE Member("Year", "Year"), Member("Qtr1", "Year") , Member("Qtr2", "Year") , Member("Qtr3", "Year") , Member("Qtr4", "Year") ...

Mapping OLAPMember tags to RelationalMember Tags Globally You specify OLAP member to relational member mappings using the OLAPMember and RelationalMember tags respectively. These mappings are applied globally to all dimensions in the cube, if they are not nested in a JDBC tag.

Note: If the OLAPDimension tag is nested inside a JDBC tag, the mappings are local and override the global mappings. For more information, see “Mapping OLAPMember Tags to RelationalMember Tags Locally” on page 288.

You can have zero or more instances of the OLAPDimension tag. The possible dimensions available are determined by the cube specified in the parent OLAPCube tag. The Name attribute identifies the dimension. If the OLAPDimension tag is nested inside an OLAPCube tag it is applied globally to all dimensions. For example, the following code snippet uses the Year dimension: ...

You can have one or more instances of RelationalMember tags nested in OLAPMember tags and one or more instance of OLAPMember tags nested in an OLAPDimension tag. Specifying an OLAPMember to RelationalMember mapping indicates that before executing the drill- through query, the OLAPMember, needs to be replaced with the specified RelationalMember value(s). There can be one OLAPMember mapped to several RelationalMembers. The Name attribute in the OLAPMember tag specifies the OLAP member and the Name attribute in the RelationalMember tag specifies the relational member. For example, in OLAP, the member Qtr1 does not exist in the RDBMS. Instead, the column contains values January, February, March, and so on. Therefore, with the following member mapping, any time a drill-through is queried on OLAPMember Qtr1: January, February and March would replace it. For example: ...

286 Setting Up Relational Data Sources ... ...

Specifying the RelationalDatabase Tag The RelationalDatabase tag indicates the drill-through target. There can be one or more RelationalDatabase tags nested in an OLAPCube tag. Each RelationalDatabase tag has id, Name, and Description attributes. The id attribute must be unique. For example: ... ... ... ...

Specifying the JDBC Tag The JDBC tag indicates the JDBC data source used to execute the drill-through query. This tag must be nested inside a RelationalDatabase tag. The DataSourceName specifies the JNDI name to a pooled data source. For example: ...

Specifying the OLAPQuery Tag Locally You use an OLAPQuery tag to set the members retrieved from the query to drillable or non- drillable. If the OLAPQuery tag is nested in a JDBC tag, the drillable or non-drillable ability is applied locally to all members retrieved from the query, overriding the global settings set previously.

Note: If the OLAPQuery tag is not nested inside a JDBC tag, the drillable or non-drillable ability is applied globally to all members retrieved from this query. For more information, see “Specifying the OLAPQuery Tag Globally” on page 285.

Using a WAA Drill-Through 287 You can have one instance of an OLAPQuery tag nested in an OLAP Dimension tag. Setting the value of the Drillable attribute to False specifies an exclusion list. A value of True specifies an inclusion list. The OLAPQuery is an ADM ALE query. All dimension inclusion/exclusion lists specified within a cube are used to determine whether a cell is drillable or non-drillable. By default, a dimension and all it's members are drillable unless otherwise specified. For example: ... ... ... SELECT "Name" FROM "Year" WHERE Member("Year", "Year"), Member("Qtr1", "Year") , Member("Qtr2", "Year") , Member("Qtr3", "Year") , Member("Qtr4", "Year") ...

...

Mapping OLAPMember Tags to RelationalMember Tags Locally You specify local OLAP member to relational member mappings within the JDBC tag, using the OLAPMember and RelationalMember tags respectively. These local mappings override the mappings specified previously in the XML file.

Note: If the OLAPDimension tag is not nested inside a JDBC tag, the mappings are global mappings. For more information, see “Mapping OLAPMember tags to RelationalMember Tags Globally” on page 286.

Within the RelationalMember tag you specify mappings between OLAP members and relational members. This overrides the OLAP member to relational member mappings within the OLAPCube tag. For example: ... ...

288 Setting Up Relational Data Sources ...

Specifying the Query Tag There can be one or more Query tags, therefore there can be many drill-through queries associated with a target. This tag is nested inside of a RelationalDatabase tag. The Query tag has a Name attribute that contains the name of the drill-through query and must be unique. The Description attribute describes the query. For example: ... ... ...

Specifying the SQLQuery Tag There can only be one SQLQuery tag nested inside a Query tag. The SQLQuery tag contains the SQL query and PromptEdit functions that are executed when drilled on. The point of view, which consists of OLAP members from each dimension when drill-through was invoked, is used in response to the following PromptEdit functions. Notice that only the Market, Scenario and Year dimensions were used in the drill-through query. For example: Select a.GM$, a.PRICE, a.QTY, a.GEOGRAPHY, a.SCENARIO, a.QUARTER, a.TIME From Financial_adhoc a, Financial_office b Where a.GEOGRAPHY=b.OFFICE and a.GEOGRAPHY in (PromptEdit("Market", "", "", "string", "false")) and a.SCENARIO in (PromptEdit("Scenario", "", "", "string", "false")) and a.QUARTER in (PromptEdit("Year", "", "", "string", "false")) Order By a.GM$ asc ...

Using a WAA Drill-Through 289 The following table describes the XML tags and keywords in the SQL query: Table 16 Drill-Through XML tags to Specify a SQL Query

Tag or Keyword Value Description

Name description Specifies the name of one drill-through query.

Select value, value Text name of the relational column. Specifies the relational column. May be qualified by a table name or an alias (eg. Financial_office.OFFICE_MGR or b. OFFICE_MGR)

From value, value Text name of the relational table. Specifies the relational table and, Optionally, you can specify an alias optionally, an alias name for the table. name for the table.

Where value, value Text name of the relational TableName.ColName specifies the table.column. relational table and column. You can also use an alias name for the table.

PromptEdit(“OLAPDimensionNam A variable that inserts a member PromptEdit specifies a point of view e”,””,””,”sting”,”false”) from the point of view. For dimension and inserts the corresponding example, $(PromptEdit:Market) member. substitutes the point of view Market members into the where clause.

OrderBy value, Value is the column you want to Used to sort your query results. sort by. asc and desc represent the sort direction ascending or descending. asc is the default. Application Builder supports up to three levels of sorting.

290 Setting Up Relational Data Sources APPENDIX Setting Up Formatting XML Files D

You use a formatting XML file to define formatting for a relational or OLAP data. The formatting you define is for the cell data and it specifies a numeric or date/time format as defined by the “Formatting Objects” on page 299. This appendix includes the following topics:

● “Using a Relational Formatting XML File” on page 291

● “Using an OLAP Formatting XML File” on page 294

Using a Relational Formatting XML File This section describes the relational formatting .xml file tags and attributes. You define an XML file to specify formatting for a queryInfo database. You can specify a formatting object to be used on specific table columns using a regular expression, or to be used on columns, rows, and cells based on their index. You can group column, row, and cell formats into a group and assign a format name. You can then reuse the format name to apply to similar tables, using the addQueryInfoCellValueFormatDatabaseFormat tag.

Note: Use the WAAQueryInfoCellValueFormatManager_7_0.dtd file to validate the XML file.

The following rules apply to the tags:

● All row, column, and cell indices are zero-based integers.

● The following tags defined within the tags must be defined in this order: , , , , <(NumericFormat | DateTimeFormat)?>.

Note: A + permits one or more instances, * permits zero or more instances, and ? permits zero or one instance.

The following table describes the XML tags. The instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected the tag must be defined at least once; if zero or one instance is expected the tag may or may not be defined.

Setting Up Formatting XML Files 291 Tags Table 17 Relational Formatting XML Tags

Required Tag Instances Attributes Description

One or more Name Defines the server name. instances

One or more Name Defines the database instances name.

One or more Name - name of the group of Use to define a group of instances formatting specifications. formatting specifications Nulltext=” string” specifies the that contains one or string to substitute for NULL more formatting objects data. associated with a specific cell, column, row, or JDBC and ColumnsFormat.

Zero or more rowIndex Use to define formatting instances columnIndex for a specific cell.

Zero or more rowIndex Use to define formatting instances for a specific row.

Zero or more colIndex Use to define formatting instances for a specific column.

Zero or one DataSourceName = JDBC Use to define the pooled instances datasource pool JDBC data source which is the JNDI name.

Zero or more TableNameExpression = regular Use to define a specific instances expression list of columns within a ColumnNameExpression = table. You can use the regular expression wildcard * to specify one or more characters.

292 Setting Up Formatting XML Files Table 17 Relational Formatting XML Tags (Continued)

Required Tag Instances Attributes Description

Zero or one For a list of attributes, see Use to define a instances “Numeric Formatting” on formatting object. You page 299. These attributes are must define one < identical to the attributes for NumericFormat> or the useNumericFormat tag. tag within the , , , tag.

Zero or one For a list of attributes, see Use to define a instance “Date/Time Formatting” on formatting object. You page 302. These attributes are must define one < identical to the attributes for Numeric Format> the useDateTime or tag within the , , , tag.

Example

Using a Relational Formatting XML File 293

Processing This section shows the JSP tags used to read in the formatting XML file. JSP: useQueryInfoCellValueFormatManager useQueryInfoCellValueFormat...... addQueryInfoCellValueFormatDatabaseFormat Name = “Format_by_Column” ......

4 The useQueryInfoCellValueFormatManager tag reads in the XML file. 5 The useQueryInfoCellValueFormat creates an object that contains a hash table that holds one or more specifications to a data area, such as cell, column, row, table and column name expressions and an associated format object. 6 The addQueryInfoCellValueFormatDatabaseFormat tag adds the format specified by the attribute Name = “Format_by_Column” to the useQueryInfoCellValueFormat’s hash table.

Note: The Format_by_Column format is defined by the tag in the XML file.

7 The formatting is applied to matching cells, columns, rows, and column names in context to the JSP tags on the page.

Using an OLAP Formatting XML File This section describes the OLAP formatting XML file tags and attributes. You define the XML file to specify formatting for an OLAP database. You can specify a formatting object to be used on specific members resulting from a member query or specific pages, columns, rows, or cells based on their index. You group this formatting information together and assign it a format name. You can then reuse the formatting information by applying it to similar cubes or schemas.

Note: Use the WAACubeViewCellValueFormatManager_7_0.dtd file to validate the XML file.

The following rules apply to the tags:

● All page, row, column, and cell indices are zero-based integers.

● The attributes tags within the tags must be in the following order: , , , , , <(NumericFormat | DateTimeFormat)?>.

294 Setting Up Formatting XML Files Note: A + permits one or more instances, * permits zero or more instances, ? permits zero or one instance.

● The attributes and tags defined within the tag must be in the following order: (ALE Query, (NumericFormat | DateTimeFormat)).

The following table describes the XML tags. The Instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected the tag must be defined at least once; if zero or one instance is expected, the tag may or may not be defined.

Using an OLAP Formatting XML File 295 Tags Table 18 OLAP Formatting XML Tags

Tag Instance Attributes Description

One or more Name Use to define the instances datasource server or computer name.

One or more Name Use to defines the product. instances Valid Values are:

● "Hyperion Essbase"

● "Hyperion Financial Management"

● "Star Schema"

● "Hyperion Planning"

● "Hyperion Enterprise"

One or more Name Use to define the schema instances or application name.

One or more Name Use to define the cube or instances database name.

One or more Name - Name of the group of Use to define a group of instances formatting specifications. formatting specifications These attributes specify a string to that contains one or more replace missing data, data that formatting objects cannot be accessed, and data associated with a specific equal to zero: page, cell, column, row, or member selection results. ● MissingText

● NoAccessText

● ZeroText

Zero or more PageIndex - If undefined, defaults Use to define a specific instances to all pages. cell. rowIndex columnIndex

Zero or more PageIndex - If undefined, defaults Use to define a specific instances to all pages. row. rowIndex

Zero or more PageIndex - if undefined, defaults Use to define a specific instances* to all pages. column. columnIndex

Zero or more PageIndex - If undefined, it defaults Use to define a specific instances* to all pages. page.

296 Setting Up Formatting XML Files Table 18 OLAP Formatting XML Tags (Continued)

Tag Instance Attributes Description

Zero or one UserId Use to define the userid instance Password and password for the datasource or cube. Encrypted - Can be set to True for password encryption or False for no password encryption. The default is False.

One instance Name Use to define the dimension name to which the query applies.

One or more ALE Query Use to define the ALE query instances that specifies members and member properties. For example SELECT "*" FROM "Accounts" WHERE Descendants("Accounts", "Accounts", "true") specifies all members and member properties of the Accounts dimension.

Note: Select “*” is always executed.

instances “Numeric Formatting” on object. You can define one page 299. These attributes are or useNumericFormat tag. tag within the , , , , or tag.

Zero or more For a list of attributes, see Use to define a formatting instances “Date/Time Formatting” on object. You can define one page 302. These attributes are < Numeric identical to the attributes for the Format> or useDateTimeFormat tag. tag within the , , , , or tag.

Using an OLAP Formatting XML File 297 Example

SELECT "*" FROM "Year" WHERE Member("Qtr1","Year") SELECT "*" FROM "Year" WHERE Descendants("Qtr1", "Year", "false") SELECT "*" FROM "Year" WHERE Descendants("Qtr2", "Year", "false"),Descendants("Qtr3", "Year", "false")

298 Setting Up Formatting XML Files

Processing This section shows the JSP tags used to read in the formatting XML file. JSP: useCubeViewCellValueFormatManager ...... useCubeViewCellValueFormat...... addCubeViewCellValueFormatDatabaseFormat Name = “Format_by_Column” ......

8 The useCubeViewCellValueFormatManager reads in the entire .xml file.

9 The useCubeViewCellValueFormat creates an object that contains a hash table that holds one or more specifications to a data area, such as cell, column, row, table and column name expressions and an associated format object. 10 The addQueryInfoCellValueFormatDatabaseFormat tag adds the format specified by the attribute Name = “Format_by_Column” to the useCubeViewCellValueFormat’s hash table. 11 The addCubeViewCellValueFormatDatabaseFormat tag adds in the format specified by the attribute Name = “Format_by_Column”.

Note: The Format_by_Column format is defined by the tag in the XML file.

12 The formatting is applied to cells, columns, rows, pages, and members in context to the JSP tags on the page.

Formatting Objects This section describes the formatting objects and their attributes.

Numeric Formatting Use to define a formatting object that provides scaling and formatting of integers and floating point numbers. The pattern and all symbols, separators, and digits are specified by the DecimalFormat Java class.

Formatting Objects 299 type The type of formatting, which can be any of the following:

❍ None for the Number.toString() result, which is the default

❍ Number for a locale-based number

❍ Percent for a locale-based percent

❍ Currency for a locale-based currency

❍ Pattern for a pattern specification

scalingFactor Indicates the number to scale by. For example, if you are calculating a percentage, set this to 100. A positive value will scale up, while a negative value scales down. Examples:

❍ 200,000 with scaling factor -100 = 2000

❍ 200,000 with scaling factor +100 = 20,000,000

❍ .54 with scaling factor +100 = 54

locale Identifies the locale to use for the formatting. The locale that can be accepted is the toString() value of a java.util.Locale object, which can be Language[_country[_variant]] (specified by the Locale Java class). If this is not specified, the user's preferred locale is used. If that cannot be found, then the system default is used. For example, en_US, fr_FR, de_DE, or ja_JP.

pattern Indicates the pattern to use for integers and floating point numbers. Table 19 Pattern Examples

Value Pattern Output Explanation

123456.789 ###,###.### 123,456.789 ● The pound sign (#) denotes a digit.

● The comma is a placeholder for the grouping separator.

● The period is a placeholder for the decimal separator.

123456.789 ###.## 123456.79 The value has three digits to the right of the decimal point, but the pattern has only two. The format method handles this by rounding up.

123.78 000000.000 000123.780 The pattern specifies leading and trailing zeros, because the 0 character is used instead of the pound sign (#).

300 Setting Up Formatting XML Files Table 19 Pattern Examples (Continued)

Value Pattern Output Explanation

12345.67 $###,###.### $12,345.67 $12,345.67 $12,345.67

12345.67 \u00A5###,###.### ¥12,345.67 The pattern specifies the currency sign for Japanese yen (¥) with the Unicode value 00A5. groupingSize Indicates the size of the group for the comma placement. For example, the number 3000 with groupingSize=3 = 3,000. If you set the grouping size to 0, a comma is not placed in the number. decimalSeparatorAlwaysShown Indicates to always show the decimal separator. minimumIntegerDigits Specifies the minimum number of digits to display before the decimal separator. Leading zeros are added if necessary. For example, the number 5 with minimumIntegerDigits set to 3 = 005. maximumIntegerDigits Specifies the maximum number of digits to display before the decimal separator. Significant digits are not truncated. For example, 005000 with maximumIntegerDigits set to 4 = 5000, and 5000 with maximumIntegerDigits set to 1 = 5000. minimumFractionDigits Specifies the minimum number of digits to display after the decimal separator. Trailing zeros are added if necessary. For example, the number 1.25 with minimumFractionDigits set to 4 = 1.2500. maximumFractionDigits Specifies the maximum number of digits to display after the decimal separator. Digits are truncated or rounded after the decimal separator, if necessary. For example, .12299 with the maximumFractionDigits set to 3 = .123. negativePrefix Specifies the prefix to use with a negative number; for example, an open sign parenthesis “(“.

Formatting Objects 301 negativeSuffix Specifies the suffix to use with a negative number; for example, a closed sign parenthesis “)“.

positivePrefix Specifies the prefix to use with a positive number; for example, an open sign parenthesis “(“.

positiveSuffix Specifies the suffix to use with a positive number; for example, a closed sign parenthesis “)“.

Date/Time Formatting Use this to specify a date, time, or date/time format object which are defined by date and time pattern strings. The pattern, symbols, separators, and digits are specified by the SimpleDateFormat Java class.

type The type of formatting, which can be any of the following:

❍ None for the Date.toString() result, which is the default

❍ Date for a locale-based date

❍ Time for a locale-based time

❍ DateTime for a locale-based date and time

❍ Pattern for a pattern specification

style Specifies the general style to use when displaying the date, time, and date/time format. Valid styles and examples for April, 10, 1998 and 3:58:45 PM are:

❍ Default - 10-Apr-98 and 3:58:45 PM

❍ Short - 4/10/98 and 3:58 PM

❍ Medium - 10-Apr-98 and 3:58:45 PM

❍ Long - April 10 and 1998 and 3:58:45 PM PDT

❍ Full - Friday, April 10, 1998 and 3:58:45 oclock PM PDT

302 Setting Up Formatting XML Files locale Identifies the locale to use for the formatting. The locale that can be accepted is the toString() value of a java.util.Locale object which can be Language[_country[_variant]] (specified by the Locale Java class). If this is not specified, the user's preferred locale is used. If that cannot be found, then the system default is used. For example, en_US, fr_FR, de_DE, ja_JP. pattern Date, time, and date/time formats are specified by date and time pattern strings. The following table shows examples for date/time formats. Table 20 Pattern Examples

Date and Time Pattern Result

"yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT

"EEE, MMM d, ''yy" Wed, Jul 4, '01

"h:mm a" 12:08 PM

"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time

"K:mm a, z" 0:08 PM, PDT

"yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM

"EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700

"yyMMddHHmmssZ" 010704120856-0700

Formatting Objects 303 304 Setting Up Formatting XML Files APPENDIX Setting Up Annotation XML E Files

This appendix describes how to set up an XML file to define a relational and OLAP data cell. It includes the following topics:

● “Using a Relational Annotation XML File” on page 305

● “Using an OLAP Annotation XML File” on page 310

An annotation is text data that is stored at the cell or row level. There are two kinds of annotations:

● A data source annotation is assigned to a OLAP data cell and it can be one of the following:

❍ An Analytic Services linked reporting object(LRO) set up by the Analytic Services system administrator

❍ A Financial Management cell text set up by the Financial Management system administrator

● A WAA annotation is set up using tags, and it can be assigned to an OLAP data cell or relational row. A WAA annotation can be text, a URL, or a file.

Using a Relational Annotation XML File This section describes the relational annotation XML file tags and their attributes. You define an XML file to specify the WAA annotations to attach to rows in a relational database.

Note: Use the WAADatabaseAnnotationManager_7_0.dtd file to validate the XML file.

The following rules apply to the order of the tags:

● The tags defined within the tag must be specified in the following order: , .

● The tags defined within the tag must be specified in the following order: , .

Tip: A + permits one or more instances, * permits zero or more instances, and ? permits zero or one instance.

Setting Up Annotation XML Files 305 The following table describes the XML tags. The instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected, the tag must be o defined at least once; if zero or one instance is expected the tag may or may not be defined.

306 Setting Up Annotation XML Files Tags Table 21 Relational XML tags

Tag Instance Attributes Description

One or more Version="7.0" Use to define the version of instances the .dtd and .xml files.

One or more Name Defines the data source instances server name or computer.

One or more Name Defines the data source. instances

One or more Name Defines a column name instances that maps to one or more specific tables and columns, and optionally a query. This allows you to assign annotations once using the name. The annotation is actually assigned to all of the mapped tables and columns.

One or more Name Defines the table within the instances tag.

One or more Name Defines the column within instances the

tag.

Zero or more Attacle= This element specifies the instances True - Makes it possible to SQL query that selects one assign an annotation to a or more members to assign member the annotation to. False - Makes it impossible ● A global to assign an annotation to tag is not specified a member within the tag. If the tag is global, all annotations, specified within the tags are attached to the query results.

Using a Relational Annotation XML File 307 Table 21 Relational XML tags (Continued)

Tag Instance Attributes Description

(continued) Zero or more ● A local tag instances is specified within the tag. If the tag is local, all annotations specified by its ancestor tag are attached to the query results.

Tip: See “Relational Annotation Processing” on page 309.

One or more Name - the annotation Use to define the name of instances name an annotation. Description - the annotation description

Example /* Define “RegionId” to map to 3 columns within 3 different tables. /

/* This is a global ( not specified within the tag). Therefore all annotations, specified for this database are attached to the Regionid query results*/ SELECT region_id from region, country WHERE region.country_id=country.country_id AND continent_id='02' /* Define “Salesmanid” to map to 4 columns within 4 different tables. A global is not defined.*/

308 Setting Up Annotation XML Files

/* Assign the “Regions” annotation to all columns that are mapped to “RegionId”. A global is not defined.* */ /* Assign the "USA Regions" annotation to all columns that are mapped to “RegionId” and match the query specified in the tag*/ SELECT region_id from region WHERE country_id='001' /* Assign the "North American Regions" annotation to all columns that are mapped to “RegionId” and match the query specified in the tag*/ SELECT region_id from region, country WHERE region.country_id=country.country_id AND continent_id='01' /* Assign the "Regions By Salesman" annotation to all columns that are mapped to "Salesmanid" and “RegionId” using the global query defined above with the tag */

Relational Annotation Processing This section shows the JSP tags used to read in the annotation XML file. useDatabaseAnnotationManager ...... useQueryInfoRowAnnotationsBean Name = “Format_by_Column” ......

13 The annotation XML file is read into memory by the useDatabaseAnnotationManager tag. This maps query result rows to specific annotations.

Using a Relational Annotation XML File 309 14 The useQueryInfoRowAnnotationsBean tag inserts an HTML control that displays a list of all annotations. If you select an annotation, the annotation editor is displayed. The annotation editor edits, creates, modifies, and previews annotations.

Guidelines All rows in a relational data source can have one or more WAA annotations. You use the tag in the .xml file to assign annotations to a row: 15 The queries for dimensions can be global or local.

❍ A global tag is not specified within the tag. If the query is global, all annotations or tags specified within the tags are attached to the query’s resulting members.

❍ A local tag is specified within the tag. If the query is local, the annotation, specified by its ancestor tag, is attached to the query’s resulting members. 16 Within the tag, for each tag specified, the system looks for a query in the following order: a. It looks for the local query, which is in the nested tag, and uses it to assign the annotation. b. If there is not a local query, the system looks for the column’s global query and uses that to assign the annotation. c. If there is not a global query, the system assigns the annotation to all the tag members.

Using an OLAP Annotation XML File This section describes the WAA annotation tags and their attributes. You define the XML file to specify WAA annotations to attach to cells in an OLAP data source.

Note: Use the WAACubeAnnotationManager_7_0.dtd file to validate the XML file.

The tags defined within the tag must be specified in the following order: , .

Tip: A + permits one or more instances, * permits zero or more instances , and ? permits zero or one instance.

The following table describes the XML tags. The instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected the tag must be defined at least once; if zero or one instance is expected the tag may or may not be defined.

310 Setting Up Annotation XML Files Tags Table 22 OLAP Annotation XML Tags

Tag Instance Attributes Description

One or more Version="7.0" Use to define the version of the instances .dtd and xml file.

One or more Name Use to define the server name. instances

One or more Name Use to define the OLAP driver or instances product. Valid Values are:

● "Hyperion Essbase"

● "Hyperion Financial Management"

● "Star Schema"

● "Hyperion Planning"

● "Hyperion Enterprise"

One or more Name Use to define the OLAP schema or instances application.

Zero or more Name Use to define the OLAP cube. instances

Zero or more Name Use to define the dimension. instances

Zero or one Attacle=”True” or “False” Use to define the ALE query that instance selects one or more members to attach the annotation to.

● A global query is not specified within tag. If the query is global, all annotations or tags specified within the tags are attached to the query’s resulting members.

● A local query is specified within the tag. If the query is local, the annotation, specified by its ancestor tag, is attached to the query’s resulting members.

One or more Name Use to define the name of an instances Description annotation. This name appears on the HTML control when the annotation is used.

Example

Using a Relational Annotation XML File 311 Corporation//DTD Cube Annotation Manager 7.0//EN" "contextroot:/WEB- INF/dtds/waa/utility/olap/WAACubeAnnotationManager_7_0.dtd"> /* This is a global query for Scenario. If scenario is used in succeeding XML tags for this cube and it does not have a local query defined, this global query is used. */ /* This statement assigns all annotations (“East Region By Time”, “Actual Feedback”, and “Feedback”) defined within the tags to the Scenario:Actual */

SELECT "Name" FROM "Scenario" WHERE Member("Actual", "Scenario") /* This statement assigns the “East Region By Time” annotation to the intersection of all Year members and Market members equal to East */

SELECT "Name" FROM "Market" WHERE Children("East", "Market", "false") /* This statement assigns the “Actual Feedback” annotation to the intersection of all Year, Market, Products, Accounts, and Scenario members = Actual members */

SELECT "Name" FROM "Scenario" WHERE Member("Actual") /* This statement assigns the “Feedback” annotation to the intersection of all Year, Market, Products, Accounts, and Scenario members. So all member are assigned to this annotation */

312 Setting Up Annotation XML Files

SELECT "Name" FROM "Scenario" WHERE Descendants("Scenario", "Scenario", "true")

Processing This section shows the JSP tags used to read in the annotation XML file. useCubeAnnotationManager ...... useCubeViewCellAnnotationsBean ......

17 The annotation XML file is read into memory by the useCubeAnnotationManager tag. This maps cubeview cells to specific annotations. 18 The useCubeViewCellAnnotationsBean tag inserts an HTML control that displays a list of all annotations. If you select an annotation, the annotation editor is displayed. The annotation editor edits, creates, modifies, and previews annotations. The useCubeViewCellAnnotationsBean tag displays all annotations including Data source annotations. For example, if you are using Analytic Services, the Analytic Services LROs are displayed. Similarly, if you are using Financial Management, the Financial Management cell text is displayed.

Guidelines All cells in an OLAP data source can have one or more WAA annotations. You use the tag in the .xml file to assign annotations to a cell: 19 The queries for dimensions can be global or local.

❍ A global query is not specified within the tag. If the query is global, all annotations or tags specified within the tags are attached to the query’s resulting members.

❍ A local query is specified within the tag. If the query is local, the annotation, specified by its ancestor tag, is attached to the query’s resulting members. 20 Within the tag, for each dimension specified the system looks for a query in the following order:

Using a Relational Annotation XML File 313 a. It looks for the local query, which is in the dimension’s nested tag, and uses it to assign the annotation. b. If there is not a local query, the system searches for the dimension’s global query and uses that to assign the annotation. c. If there is not a global query, the system assigns the annotation to all the dimension’s members.

314 Setting Up Annotation XML Files APPENDIX Setting Up Export XML Files F

The Export function exports a grid, join, or transformation grid to the following formats: PDF, RTF, HTML, Excel, or Power Point. The formatting applied to the cubeView and QueryInfo is retained in the output. The chart is not included in the output file. The WAAGridExport.xml file defines the export options and parameters for a CubeView, QueryInfo or Grid object. It generates an HTML control that lists the export options. You use one of the following tags to generate an HTML control that displays the export options set up by the WAAExport.xml file:

❍ useCubeViewExportBean - This tag is an adapter tag for exporting a CubeView into an IWAAGrid object. You use this tag to define export options for OLAP data.

❍ useQueryInfoExportBean - This tag is an adapter tag for exporting a QueryInfo into an IWAAGrid object. You use this tag to define export options for relational data.

❍ useGridExportBean - This tag exports the universal result set grid or IWAAGrid object. You use this tag to define export options for a grid, join, or transformation grid.

Setting up the Export XML File This section describes the export XML file tags and their attributes.

Note: Use the WAAGridExport_7_0.dtd file to validate the XML file.

The following figure describes the XML tags. The instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected the tag must be defined at least once. The following rule applies to the order of the tags:

● The tags defined within the tag, must be specified in the following order , .

Tip: Where + permits one or more instances, * permits zero or more instances , ? permits zero or one instance.

Setting Up Export XML Files 315 Tags Tableo 23 Relational XML tags

Tag Instance Attributes Description

You must have Version="7.0" Use to define the version of only one the .dtd and xml file. instance of this.

Zero or more Name Use to define a default instances Value XSLT parameter that will be applied to every The names and values are tag defined in this file. listed in the Cascading Style Sheets, level 2 Note: If this parameter is document. For more also specified within the information, see tag then it http://www.w3.org/TR/RE overrides this default C-CSS2/. setting.

One or more Name This parameter is passed to instances Value the XSLT parser at runtime, serving as a parameter in The names and values are the XSLT template script. It described in “Setting XSLT override the default setting Parameter Values” on in the XSLT file. page 319.

One or more Name = “name” There are four supported instances Type = types: “ XSLT” ● XSLT - The Grid XML “FOP_PDF” document is run “JFOR” through XSLT via Xalan, “Debug” and a text file is returned

● FOP_PDF - The Grid XML document is run through XSLT via Xalan, the FOP renderer, and a PDF file is returned

● JFOR - The Grid XML document is run through XSLT, the JFor renderer, and a RTF file is returned

● Debug - The Grid XML document is not run through XSLT, and the raw Grid XML document from IWAAGrid is returned.

316 Setting Up Export XML Files Table 23 Relational XML tags (Continued)

Tag Instance Attributes Description

Export (continued) One or more ● MimeType = Specifies the Mime type of instances "application/pdf" the file. There are six supported mime types. ● "text/rtf"

● "text/html" Tip: MIME stands for Multipurpose Internet Mail ● "application/x- Extensions for more msexcel" information, see ● "application/x- http://www.nacs.uci.edu/in mspowerpoint" div/ehood/MIME/MIME.html

● "text/xml"

Export (continued) One or more XSLTFile = “file_name” Specify the XSLT file. There instances are two XSLT files provided:

● WAAGridToHtml.xslt - This is a sample stylesheet that converts a Grid XML document into HTML output.

● WAAGridToXslfo.xslt - This is a sample stylesheet that converts a Grid XML document into XSL:FO output.

Tip: You can create your own XSLT file. Do not modify the provided XSLT files.

Example Following is an example export file.

Note: The WAAGridExport.xml file is installed with the Sample Application.

Setting up the Export XML File 317

Processing This section shows the JSP tags used to read in the export XML file. useQueryInfoExportBean Name = ...... specifies a WAAExport.xml file

21 The export XML file is read into memory. 22 The Type, MimeType, and XSLT parameters define the export output type and XSLT formatting file.

23 The DefaultXSLTParameters and XSLTParameter values are substituted into the XSLT file. The DefaultXSLTParameters is substituted unless the XSLTParameter defines the same Name. The XSLTParameter values override the DefaultXSLTParameters values. In the following example, PageHeight = 8.5 is used, because it overrides the DefaultXSLTParameters setting for Name = “PageHeight” DefaultXSLTParameters = XSLTParameter Name="PageHeight" Value="scale" ...... XSLTParameter Name="PageHeight" Value="8.5"

24 The Name attribute within each tag is listed on the generated HTML control. 25 When a user clicks on an Export type, the following processing occurs dependent on the type of file you are exporting:

● The Grid XML document is created

● The Grid XML document and the XSLT file are processed by Xalan to produce HTML or XSL:FO output.

318 Setting Up Export XML Files ● The HTML output is used to produce Power Point and Excel output.

● The XSL:FO output is processed by FOP or JFor and produces PDF or RTF output respectively.

Setting XSLT Parameter Values The following two sample XSLT style sheets are provided to add basic formatting to a XML document containing a grid generated by the HAB class method com.hyperion.waa.utility.core.WAAGridExport.convertGridToXML().

● WAAGridToXslfo.xslt- This is a sample stylesheet that converts a grid XML document into XSL:FO output. There are a number of parameters that are set, and may be overridden by parameter settings in the XML file. For example, you can vary the output (such as page sizing, etc.)

● WAAGridToHtml.xslt - This is a sample stylesheet that converts a Grid XML document into HTML output.

You can add new formatting parameters by also adding methods to implement them in the XSLT file. The methods use the X_Path syntax. If you want to override the parameters in the .XSLT file, use the parameter settings in the WAAExportGrid.xml file rather than changing the XSLT file. You can also use one of the XSLT files as a base to create a new one. Do not modify the sample XSLT files. The XSLT file defines the parameter names in accordance with the CSS2 specification. For more information, http://www.w3.org/TR/REC-CSS2/. The following parameters can be specified in the XML file. The value you set in the XML file overrides the value defined in the XSLT file.

● Global grid rendering features define parameters for the entire grid.

❍ MergeCornerHeaders - set to true to merge corner or page headers, set to false to leave headers separate.

❍ MergeRowHeaders - set to true to merge page headers, set to false to leave headers separate.

❍ MergeColumnHeaders - set to true to merge column headers, set to false to leave headers separate.

❍ GridColumnsBeforeWrap - set to the number of columns to display on one physical page. Set to "infinite" if you want to display all columns.

❍ PageBreakAfterGridPage - set to true to place a page break after each grid. Set to false to place two grids on the same page.

❍ UseDataFormatting - set to true to use the formatting set in the cubeView or queryInfo by the formatting tags. Set to false to ignore the formatting, set by the formatting tags.

❍ UseCellIndenting - set to true to use the standard tree structure for indentation. Set to false to left align all the data cells.

Setting XSLT Parameter Values 319 ❍ UseCellAlignments - set to true to if you want the data aligned to the right and the metadata aligned to the left. Set to false to ignore data and metadata alignment.

● Global page formatting features:

❍ PageHeight - set to mm units or “scale” which will reduce the size of the grid to fit on the physical page.

❍ PageWidth - set to mm units or “scale” which will reduce the size of the grid to fit on the physical page.

❍ PageMarginTop - set to mm units if you are using scaling.

❍ PageMarginBottom - set to mm units if you are using scaling.

❍ PageMarginLeft - set to mm units if you are using scaling.

❍ PageMarginRight - set to mm units if you are using scaling.

❍ TableColumnWidth- set to mm units if you are using scaling.

● Cell rendering Parameters for each cell type. This is described in the following section.

Cell Rendering Parameters This section describes the XSLT parameters that define the borders and padding for cells. The XSLT parameters are defined using the following syntax: areaCellSidePropertyValue, for example CornerHeaderCellBorderTopColor and DataCellBorderTopColor define the color for the top of a corner header and a data cell respectively. area = CornerHeadercell, RowHeadercell, ColumnHeaderCell, or DataCell cell = Border, Padding side = Top, Right, Bottom, or Left Property = style, width, color, padding Value is defined in the CSS standards The properties and values are described in the following bullets:

● Style - The border style properties specify the line style of a box's border . For example, solid, double, dashed, etc. See the CSS style sheet for a list of styles. Valid values are:

❍ None - No border. This value forces the computed value of 'border-width' to be '0'.

❍ Hidden - Same as 'none', except in terms of border conflict resolution for table elements.

❍ Solid - The border is a single line segment.

Tip: The 'dotted', 'dashed', 'double', 'groove', 'ridge', 'inset', and 'outset' styles are interpreted to be the same as ‘solid’.

● Color - A Color is either a keyword or a numerical RGB specification. For example, red, or RGB(@%%,0,0) or #FF0000. See the CSS style sheet for a list of colors. Valid keyword color names are: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow.

320 Setting Up Export XML Files ● Padding - The padding property specifies the width of the padding area of a box. Each padding side is set individually. For example, 1pt, 1px or 1mm. See the CSS style sheet for a list of valid padding widths.

● Width - The borderwidth specifies the width of the border area, which may take one of the following values:

❍ thin - A thin border.

❍ medium - A medium border.

❍ thick - A thick border.

❍ - The border's thickness has an explicit value. Explicit border widths cannot be negative. For example, 1pt, 1px or 1mm. See the CSS style sheet for a list of valid lengths.

Setting XSLT Parameter Values 321 322 Setting Up Export XML Files APPENDIX Setting Up Universal Chart XML G Files

The charting function generates a chart from universal result set data which is stored in an IWAAGrid instance. The WAAGridChart.xml file defines the charting types and options. You use one of the following tags to generate an HTML control that displays a universal chart specified by the WAAChart.xml file:

❍ useGridChartBean - This tag generates a universal chart using universal result set data which is stored in an IWAAGrid instance.

❍ useCubeViewChartBean - This tag is an adapter class for generating a universal chart using CubeView data. The cubeview data is mapped to an IWAAGrid instance and the useGridChartBean tag is then executed..

❍ useQueryInfoChartBean - This tag is an adapter class for generating a universal chart using QueryInfo data. The QueryInfo data is mapped to an IWAAGrid instance and the useGridChartBean tag is then executed.

Setting up the Universal Chart XML File This section describes the universal chart XML file tags and their attributes. You define an XML file to specify the chart type and options to apply to an IWAAGrid instance.

Note: The WAAGridChart.xml file defines a 3D bar chart, a 2D bar chart and a line chart.

Figure 24 describes the XML tags. The instance column specifies how many instances of the tag are expected. For example, if one or more instances are expected the tag must be defined at least once. The following rules applies to the order of the tags:

● The tags defined within the tag, must be specified in the following order and match the pattern , where + permits one or more instances and ? permits zero or one instance.

Setting Up Universal Chart XML Files 323 Tags Tableo 24 Relational XML tags

Tag Instance Attributes Description

You must have Version="7.0" Use to define the version of only one the .dtd and xml file. instance of this.

Zero or one none Use to define default instances ChartOptions that are applied to every tag defined in this file. If this is not applicable to a chart it is ignored.

Note: If this parameter is also specified within the tag then it overrides this default setting.

One or more Name This parameter is passed to instances Value the IWAAGrid instance at runtime, serving as a name The names and values are value that overrides the listed in the NetCharts 4.0 default setting in the chart documentation. xml file. For more information, see http://www.netcharts.com/ documentation/CDLRefere nce/index.html.

One or more Name ● Name is the text name instances Type you assign to the chart and use to refer to it as

● Type is the chart type defined in the NetCharts 4.0 documentation.

(continued) One or more OutputMIMETypes Specifies the Mime type of instances the file. Valid values are: image/bmp, image/jpeg, image/pict, image/png, image/psd, image/tga, image/tiff, image/cur, image/xpm, image/xbm, image/x-cmu-raster, image/ico, image/pcx.

Tip: MIME stands for Multipurpose Internet Mail Extensions.

(continued) One or more Height ● Height in pixels instances Width ● Width in pixels

324 Setting Up Universal Chart XML Files Setting Universal Chart Name and Values This section shows the steps used to set Chart names and values.

Note: For more information, see the com.hyperion.waa.utility.core.WAAGridChartGenerator class or Javadoc.

26 The chart option names and values are defined in the NetCharts CDL (Chart Definition Language) documentation. Some options are valid for all chart types, others are specific to a particular chart type. 27 Substitution variables can be used. These are resolved when the chart is generated, allowing you to insert things like the current page for the CubeView into the title. Substitution parameters are delimited by ${VARIABLE}, the following parameters are recognized: ${CELL_P_R_C} ${ROW_NAME_P_R} ${ROW_HEADER_P_R_H} ${COLUMN_NAME_P_C} ${COLUMN_HEADER_P_C_H} ${PAGE_NAME_P} ${PAGE_LABEL_P_L} where P=Page Index, R=Row Index, C=ColumnIndex, L=Label Index, H=Header Index. For example, "${PAGE_NAME_3} with cell ${CELL_7_4_5}"

28 There are also variables that can be used to construct Netcharts tuples: ${LOOPCOLUMNS} ${LOOPCOLUMNS_STARTINDEX_ENDINDEX} ${LOOPROWS} ${LOOPROWS_STARTINDEX_ENDINDEX} The LOOP_* variable will repeat the following tuple value(s) for each row or column. When using the variables above with the LOOP* variables, you can use "C" to represent the current index. For example, "(${LOOPROWS}, (${ROW_NAME_C}, BLUE), (${ROW_NAME_C}, RED))" ; displays the rows in the colors blue and red in succession.

Example The following example is the CustomChart.xml file that creates a new chart type.

Setting Universal Chart Name and Values 325

The following JSP example below loads this file, adds a new chart type, and then makes all chart backgrounds green if the user's name is foobar. This example makes heavy use of nesting, but none of the tags have to be nested -- they'll just have many more attributes!

The user foobar would see a dropdown with the chart names "3D Bar Chart" and "Horizontal Bar" followed by the rendering of the selected chart using data from the CubeView, with green backgrounds. Any other user would see the same two chart types with the background color white as specified in the XML file.

<%-- Provide the query and the current page index. The Chart Bean could also take the CubeView id/scope and Page Index as attributes. --%> <%-- Manager loads and parses the XML file for the application --%> <%-- CubeViewChart reads initial configuration from the Manager -- %> <%-- Add a new chart "Horizontal Bar" to CubeViewChart. It can have a different size and image type than other charts. --%> <%-- User foobar likes green backgrounds --%> <% if ("foobar".equals(request.getRemoteUser())) { %> <%-- No chartName attribute => global option --%>

326 Setting Up Universal Chart XML Files <% } %> <%-- Selector bean provides a dropdown menu of chart types --%> <%-- Render the currently selected chart in SelectorBean (could also specify by name) --%>

Setting Universal Chart Name and Values 327 328 Setting Up Universal Chart XML Files A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Glossary

ad hoc report An online analytical query created on-the- annotation Text data that is stored for OLAP data or fly by an end user. relational data. There are two kinds of annotations: data source and WAA. A data source annotation is assigned to ADM Client Interfaces Exposes public client interfaces, an OLAP data cell and can be either a Essbase Analytic which are available for use by the developer to access a data Services linked reporting object (LRO) or a Financial source. Management cell text. A WAA annotation is set up using ADM Pooling Enables users to share a connection to a an XML file, and it can be assigned to an OLAP cell, Olap data source. ADM pooling also controls the security to view, relational row, or relational view. A WAA annotation your data source. is text, a URL, or a file.

Administration Tools A set of tools to assist with the annotation repository Stores annotation information for administration of applications created with Application views and cell data. It also stores WAA drill-through Builder. mapping information for a WAA drill-through.

ALE Analytic Language for Expression. A language-based ANT A Java-based build tool, part of the Jakarta project representation used to specify queries within the Analytic from Apache. ANT users create XML-based build files that Data Model (ADM). describe their project build processes.

ALE query Retrieves member information and data cells API See also Application Programming Interface (API). from a data source using the Analytic Data Model. For applet In Java, a program that can run in a Web browser. example, you can specify both member and data cell Small programs written in languages other than Java are queries using one of the following query representations: sometimes referred to as applets. Analytic Language for Expression (ALE);Extensible Mark- up language (XML), which is an ADMML.dtd compliant application A related set of dimensions and dimension XML text; or an Expression Tree. members that are used to meet a specific set of analytical or reporting requirements. Analysis Tools Framework (ATF) repository Stores secured object information for users, groups, folders, Application Programming Interface (API) A library of views, task definitions, scheduled task definitions, and functions that you can use in a custom program. Provides permissions. It also includes a cron scheduling utility that programmatic access to an application’s data or services. schedules and runs tasks. Application Builder provides a Java API that you can use to develop client programs. Analytic Data Model (ADM) A generic, object-oriented interface that accesses different OLAP data sources. The application project A project for the exclusive use of an ADM developed by Hyperion is used in several Hyperion application to store and manage its models. An application products, such as Reports, Application Builder, and project is created for an application during the registration Financial Management. process.

application server A middle-tier server that is used to deploy and run Web-based application processes.

Glossary 329 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z authentication Verification of identity as a security Configuration The security platform relies on an XML measure. Authentication is typically based on a user ID document to be configured by the product administrator and password. Passwords and digital signatures are forms or installer of the software. The XML document must be of authentication. modified to indicate meaningful values for properties, specifying locations and attributes pertaining to the bean A reusable component, or building block, that can corporate authentication scenario. For configuration be combined with other components in the same or other instructions, see the documentation for the applicable computers in a distributed network to form an Hyperion product. application. cube A block of data that contains three or more calc script A set of commands that define how a database dimensions. Multidimensional cubes are better suited for is consolidated or aggregated. A calculation script may also complex data analyses than for relational databases contain commands that specify allocation and other because relational databases are limited to two dimensions. calculation rules separate from the consolidation process. A Essbase Analytic Services database consists of miniature cell A unit of data representing the intersection of cubes that make up a larger cube, or hypercube. dimensions in a multidimensional database; the cube view An object that contains the XML intersection of a row and a column in a worksheet. representation of an OLAP data query and partial results chart Charts are graphical representations of the data of the query. retrieved from a specified grid. Examples of chart types data The values (monetary or non-monetary) associated are bar, line, and pie. with the query intersection. child A member that has a parent above it in the database data cell query The extraction of one or more values from outline. a multi-dimensional data source. For example, the class A template definition of the methods and variables CubeView query navigates from the metadata to the data in a particular kind of object. The class defines all of the cells. common properties of the different objects that belong to data load The process of populating an Essbase Analytic it. See also object. Services database with data. Loading data establishes column A vertical display of information in a grid or actual values for the cells defined by the structural outline table. A column can contain data from a single field, of the database. derived data from a calculation, or textual information. data query The extraction of one or more values from a The terms column and field are sometimes used multi-dimensional data source. A data query utilizes the interchangeably. Contrast with row. cube view object to return data cell values and data cell component A module of program functionality that has attributes. It also enables access to member names and defined inputs, processes, and outputs, and that, when usage of a data cell object for data persistence. incorporated into a larger program or system, provides data source A storage area containing data that is available application functionality. The basic building block of both to the user. A data source may be a multidimensional Analytic Application Framework and the Analytic database, a relational database, or a file. Applications. Analytic Application Framework Components include: Application-Server Components, data source annotation An annotation assigned to a Common Application Components, Custom Application OLAP data cell. It can be either a Essbase Analytic Services Components, Snap-in Components, Client Sub- linked reporting object (LRO) or a Financial Management Components. Analytic Application components include: cell text. Application Component Classes and Application data source drill-through A Essbase Analytic Services or Components (AC Instances). Essbase Integration Server (EIS) drill-through or a composite objects A pattern in the ADM design which Financial Management drill-through line item detail describes the relationship between child objects and the (DTLID). parent objects that contain them.

330 Glossary A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

data source XML file The XML file that specifies OLAP Dynamic Time Series A process that is used to perform data sources, Analytic Data Model pools, and relational dynamic period-to-date reporting for all values associated data sources. For example, the waadatasources.xml with a query. file is the data source XML file used in the Sample dynamic time series functions Hidden outline members Application. that provide period-to-date reporting at up to eight levels, database A collection of related information. Each unit such as year-to-date and month-to-date totals. An (record) of the database is typically organized in a fixed administrator assigns Dynamic Time Series members to format to make it easy to retrieve selected portions of the members of the time-based dimension in your database data on demand. Each record is made up of one or more outline. data fields, and each data field can hold one piece of data EAR file An enterprise archive file used to distribute J2EE (known as a value). Web applications. Contains WAR files, JAR files, and database administrator (DBA) An individual who deployment information. administers database servers, such as Essbase Analytic edge A component of an OLAP cube. Valid edges include Services, and who may also design, maintain, and create Row, Column, Page, and Slicer. For example, if a report databases. has Product and Sales on the columns and Region on the DB2 Database 2. A IBM-proprietary relational database rows, then the Row edge contains Product and Sales and product, providing an open database environment that the column edge contains Region. runs on a wide variety of computing platforms. Enterprise Beans Server-side components that DBA See also database administrator (DBA). encapsulate the business logic of an application.

dimension A data category that is used to organize execute A command that runs a specified Calc script business data for retrieval and preservation of values. Each object against a OLAP result set. In most cases, a Calc dimension usually contains a hierarchy of related members script object represents a file containing Calc script grouped within it. For example, a Year dimension often commands. includes members for each time period, such as quarters export A means by which a user can direct the output of and months. Other common business dimensions may be data or the results of a query. measures, natural accounts, products, and markets. export The process of moving a model, including its dimensional hierarchy A type of model that typically contents, from the application to Hyperion Hub. includes a hierarchy of related group members, such as entities or accounts. expression tree query An object-based representation and manipulation of Analytic Language for Expression queries. drill-through The navigation from a data value in one This is ideal for interactive query building. cube to corresponding data in another data source. For example, you can access context-sensitive transactional Extensible Markup Language (XML) A language data. Drill-through occurs usually from the lowest point of comprised of a set of tags used to assign attributes to data atomicity in a database (detail) to a next level of detail in that can be interpreted between applications based on the an external data source. schema used.

drill-through XML file Contains information required to external authentication The practice of storing user logon map from an OLAP cube’s data cell to a SQL query to credentials in a corporate authentication repository (such retrieve detailed consolidation information. For example, as Lightweight Directory Access Protocol, or LDAP, the WAADrillThrough.xml file is the drill-through XML directory) as an alternative to maintaining users and file used in the Sample Application. groups for each Hyperion product.

DTD file A document type definition file. Defines the type of elements, attributes, and entities in an associated XML document.

Glossary 331 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z fact table A container for one or more relational tables Hypertext Markup Language (HTML) The programming that define the data values for each dimension intersection language used to generate Web pages on the World Wide in the OLAP model. For example, if the OLAP model Web. contains Products, Region, and Year dimensions, the fact icon A graphical representation of an object or concept table might include data values for the number of units of that invokes an application or program. desktop shortcut. Product A sold in New York in January. Identity A unique identification of one valid user or filter In Hyperion Hub, a method that enables users to group existing on an external authentication repository. filter "out" selected members from the model when the model is imported. import The process of moving a model, including its contents, from Hyperion Hub to the application. filter functions Filter functions filter the set of objects returned by execution of the query. The following member instantiate To create a single occurrence of an object filter functions are implemented by all Analytic Data based upon its class. Model drivers: AllMembers, Children, Descendents, invisible tags A tag which may or may not produce Member, SystemMemberList, and TopOfHierarchy. invisible HTML elements on a Web page, as well as folder An object in the ATF repository used as a storage processing server-side requests. container for other objects such as views, queries, or other J2EE A framework for developing and deploying folders. enterprise applications. The J2EE platform consists of a set generation A layer in a hierarchical tree structure that of services, application programming interfaces (APIs), defines member relationships in a database. For example, and protocols that provide the functionality for developing Essbase Analytic Services orders generations incrementally multitiered Web-based applications. from the dimension (generation 1) down to the child J2EE roles Used to implement ADM pooling. A J2EE role members. assigned to J2EE users in your application server. grid A report object that can contain data from external J2EE users J2EE application users that are assigned to data sources. A grid contains a row, column, and roles in your application server to access your Application (optionally) a page axis. Builder application.

guided analysis. Functionality that JAR file A Java archive file. A platform-independent file links and launches reports and views format that permits many files to be aggregated into one from one Hyperion product to file. another. Users can easily navigate from any Application Builder report Java Database Connectivity (JDBC) A Java API in the to related financial reports (rendered J2EE framework that enables Java programs to execute in Reports), unstructured content SQL statements. This allows Java programs to interact with (using Central) and interactive out- any SQL-compliant database supporting JDBC. JDBC of-the-box analysis (rendered in makes it possible to write a single database application that Analyzer). can run on different platforms and interact with different RDBMSs. hab-blank.ear file An enterprise archive file that contains the WAA framework and minimal deployment Java developer A person who is competent in Java information to create a new web application. programming, specifically the Java 2.0 Standard Edition as well as the Java 2.0 Enterprise Edition. hab-samples.ear file An enterprise archive file that contains the WAA framework, deployment information, Java Development Kit (JDK) A software development kit and customized code for the Sample Application. from JavaSoft used to produce Java programs, containing the software and tools that developers need to compile, hierarchy A set of multidimensional relationships in an debug, and run applets and applications. outline, often created in a tree formation. For example, parents, children, and generations represent a hierarchy.

332 Glossary A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Java Naming and Directory Interface (JNDI) A standard log A system-maintained record of transactional data extension to the Java platform, providing Java technology- resulting from actions and commands. enabled applications with a unified interface to multiple log file A system-maintained file that records naming and directory services in the enterprise. It enables transactional data resulting from actions and commands. seamless connectivity to heterogeneous enterprise naming For example, an application log file records user actions and directory services. It also enables developers to build that are performed on that application; a client log file powerful and portable directory-enabled applications records client messages, actions, and errors. using this industry standard. member query Enables you to navigate from the metadata Java Server Pages (JSP) Technolog y for controlling the to the data. A member query utilizes the MemberSelection content and appearance of web pages through the use of object to return member objects and hierarchy servlets. relationship objects. It also enables access to member Java Virtual Machine (JVM) Technology that enables the properties. For example, the logical relationships between Java 2 platform to host applications on any computer or dimension/member and hierarchy/hierarchy relation are operating system without rewriting or recompiling. The described in the MemberSelection query. So the JVM is also responsible for the compactness of MemberSelection query can access a member. You can also applications targeting the Java 2 platform, and is the specify the level of the members that you want in the foundation of its security capabilities. MemberSelection query.

JavaBeans Reusable software components written in the member selection An object that contains the XML Java programming language. You write JavaBeans just as representation of an OLAP member query and the results you write any other Java class. You can also take existing of the query. components, applets, or Java classes and turn them into metadata A set of data that defines and describes the JavaBeans. properties and attributes of the data stored in a database or JDBC Pooling Database connectivity where a JDBC data used by an application. Examples of metadata are source is created and configured for connection pooling dimension names, member names, properties, time with a relational database. The JDBC data source periods, and security. efficiently creates and manages connections to a relational Microsoft Virtual Machine (VM) A self-contained database. operating environment that facilitates the execution of Java JDBC-ODBC Bridge Driver A bridge is a device that programs on a Microsoft operating system. governs the flow of traffic between networks or network model A file or string of content containing an segments and forwards packets between them. A driver is a application-specific representation of data. Models are the program that extends the operating system to support a basic data managed by Hyperion Hub. Models are of two device such as a disk or tape drive; or a program that major types: dimensional, and non-dimensional, enables an application to use a device such as a printer. application objects. join Creates a relationship between two tables based on matching key column values in relational databases and as an SQL command. Model-View-Controller Model (MVC) Consists of a controller servlet that dispatches requests to appropriate JSP developer A person that is competent in Java server Action classes provided by the application developer, JSP page technology and has user knowledge of an OLAP or custom tag libraries, and associated support in the relational data source. controller servlet. For example, this model assists key column In relational databases, a column or columns developers in creating interactive form-based applications, that form a unique identifier for each row. For example, and utility classes to support XML parsing, automatic EMPLOYEE_ID might be a key column. population of JavaBeans properties (based on the Java reflection APIs), and internationalization of prompts and leaf member A member that has no children. messages.

Glossary 333 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z multidimensional database (MDDB) A method of Open Database Connectivity (ODBC) Standardized organizing, storing, and referencing data through three or application programming interface (API) technology that more dimensions. An individual value is the intersection allows applications to access multiple third-party of a point for a set of dimensions. databases. multithreading Within a single program, concurrent order of precedence A set of rules that determines the handling of multiple, separately executable sequences of order in which arithmetic operations take place in a program instructions. formula. Multiplication (*) and division (/) are performed first (first tier operations), followed by addition (+) and named group An object that describes levels and subtraction (-) (second tier operations). When there are generations for dimensions. A level is a branch within a multiple operations involving the same tier, the operations dimension. The levels are numbered incrementally from are performed from left to right. Use of parentheses alters the leaf member (level 0) towards the root. For example, the normal order, with the operations contained within the in a Essbase Analytic Services Accounts dimension that innermost parenthesis performed first. consists of general ledger accounts, all of the detail accounts are Level 0 members. The accounts one level outline The database structure of a multidimensional higher are Level 1, their parents are Level 2, and so on. It database, including all dimensions, members, tags, types, can happen that a parent has two or more children that are consolidations, and mathematical relationships. Data is different levels. stored in the database according to the structure defined in the outline. non-dimensional model A type of model that includes application objects such as security files, member lists, page axis Enables you to set up views (pages) of selected calculation scripts, and web forms. members, to organize the data in a data entry form into smaller, logical groups. Each page on the page axis can object A program component that is related to an have members selected from one dimension or from application or database. Objects can be outlines, rules files, multiple dimensions. For example, you could set up one calculation scripts, report scripts, or data sources. They are page to enter data for Radio promotions and another page stored within the application or database subdirectory on to enter data for Web promotions. the server or client machine. parent A member that has an aggregated branch of object factory Enables developers to derive objects from children below it. Web Application Architecture classes and have the architecture instantiate them transparently. This makes permission A level of access users and groups can have for application customization much easier. managing data or other users and groups. Permissions can be granted to users and groups explicitly or by means of Object Management Group (OMG) A consortium that filters. Administrators can also set global minimum created the Common Warehouse Metadata Initiative, permissions as settings for Essbase Analytic Services which defines a standard model for OLAP metadata to be applications and databases, so that all users can have at browsed and interchanged. least access to data specified by the minimum permission ODBC See Open Database Connectivity (ODBC). setting for a particular scope. The scope of a permission OLAP See online analytical processing (OLAP). refers to the area of data it encompasses. The scope of a permission can be the system, an application, or a online analytical processing (OLAP) A database. multidimensional, multi-user, client-server computing environment for users who need to analyze consolidated point of view (POV) A unique set of dimension members enterprise data. OLAP systems feature functionality such that defines specific intersections of data. as drilling down, data pivoting, complex calculations, project Used by Hyperion Hub to store, manage and share trend analyses, and modeling. models. Projects are of two types, application project and shared project.

POV See point of view (POV).

334 Glossary A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

query To request information from a data provider. For repository group A parent object to repository users, or a example, queries are used to access a relational data source. container for storing ATF repository users with the same permissions. query functions A method to filter retrieved information in a query language. Enables you to filter the set of objects repository user An individual who is registered in the ATF returned by execution of an OLAP query. For example, the repository. following member query functions are implemented by all role Used to define group privileges, and are granted to Analytic Data Model (ADM) drivers: AllMembers, users or groups of users in order to determine who can Children, Descendents, Member, SystemMemberList, and perform the activities associated with the privileges. A user TopOfHier archy. may perform the activities only if he has been granted the queryInfo An object that contains a SQL query and required role or if he is a member of a group that has been partial results of the query. granted the required role.

Quick Builder Enables you to build applications within root member The highest member in a dimension Macromedia > Dreamweaver > . Tags from the branch. See also leaf member. Application Builder tag library are represented by icons, row A horizontal display of information in a grid or table. menus, and wizards. For example, a Web designer can A row can contain data from a single field, derived data build an application graphically by dragging and dropping from a calculation, or textual information. The words row Dreamweaver icons onto a Java server page. and record are sometimes used interchangeably. Contrast Quick Builder component Reference tags, from the with column. Application Builder tag library, that are displayed as icons schema In relational databases, a logical model that within Dreamweaver. represents the data and the relationships between the data. RDBMS See relational database management system schema definition Used to create objects and set their (RDBMS). properties. The objects you create correspond to your registration The process by which applications provide metadata. For example, you create a dimension object for information for connecting and creating initial projects in each dimension in your data source. Hyperion Hub. Registration information includes the URL security agent. A Web Access Management Solutions path to the server and the server port number, as well as provider employed by companies to manage and enforce information about the application. authentication, authorization, and single sign-on. related content. Information that is Examples: Netegrity SiteMinder, IBM Tivoli Access associated with OLAP or relational Manager. The Hyperion security platform enables single data such as a drill-through, sign-on for a user into a web-based Hyperion application annotation, or guided analysis link. without challenging the user for credentials, as long as the Security Agent has already authenticated the user. relational data access component A component that can be accessed within an application that enables you to view servlet Small Java programs, or modules of Java code that the relational data that is associated with specific OLAP run in a server application. For example, an applet that members at the given cell. runs on a server, usually meaning a Java applet that runs on a Web server. relational database management system (RDBMS) A database management system for accessing data in a shared project A project that enables two or more relational database and storing data in the form of related applications to share their models. tables. A RDBMS takes SQL statements entered by a user sibling A child member at the same generation as another or contained in an application program and creates, child member and having the same immediate parent. For updates, or provides access to the relational database. example, the members Florida and New York are both children of the member, East, and siblings of each other.

Glossary 335 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z single sign-on The ability of an externally-authenticated tag library A collection of custom tags which can be user to access multiple, linked Hyperion applications after imported for use in a JSP page. Individual tags are grouped logging on to the first application. The user can launch into several tag libraries according to their functionality. A other applications from the first application (and from tag library is similar to an XML document that contains other linked Hyperion applications) without logging on information about individual tags. For example, in again. The user’s ID and password are already Application Builder, there is a relational tag library that authenticated. contains relational tags and an OLAP tag library that contains OLAP tags. slicer The slicer edge can contain one or more dimensions, but only one member can be specified for thin driver A Java based driver that is inherently cross- each dimension. For example, if the member Actuals from platform, because it is written exclusively in Java. the Scenario dimension is on the slicer then the data in the Token An encrypted string returned from the security result set is all data that intersects the row, col, and page platform that holds information for a user. Tokens are members, and also has the scenario dimension set to opaque to the application, and are generated upon Actuals. The data omitted from this slice is any data authentication. associated with the non-selected members of the Scenario dimension, for example Budget, Variance, Forecast, etc. tool tip A tiny pop-up window that presents a short description of a toolbar or picture button’s action. Tool special permission A group of predefined permissions tips are dialogs that briefly describe or define a button’s granted to users, groups, folders, views , or queries within functionality. the repository. A special permission is a single bit, whereas a permission is a combination of one or more special top-level member A dimension member at the top of the permissions. tree in a dimension outline hierarchy, or the first member of the dimension in sort order if there is no hierarchical SQL See also Structured Query Language (SQL). relationship among dimension members. The top-level star schema A logical model that represents your member name is generally the same name as the relational data in a form that mirrors that of OLAP data. A dimension name if a hierarchical relationship exists. star schema contains a fact table and one or more UDA A user-defined attribute. A UDA is a term associated dimension tables. with members of an outline to describe a particular Structured Query Language (SQL) A computer language characteristic of the members. Users can specify UDAs used to access data in relational databases. within calculation scripts and reports so that they return lists of members that have the specified UDA associated substitution variable A variable that acts as a global with them. UDAs can be applied to dense as well as sparse placeholder for information that changes regularly. You set dimensions. the variable and a corresponding string value; the value can then be changed at any time. Substitution variables unary operator A group of mathematical indicators (+, -, can be used in calculation scripts, report scripts, Essbase *, /, %) that define how roll-ups take place on the database Spreadsheet Services, and Essbase API. outline. synchronized The condition that exists when the latest Uniform Resource Locator (URL) An address for a version of a model resides in both the application and in resource located on the World Wide Web, such as a Hyperion Hub. document, image, downloadable file, service, or electronic mailbox. URLs use a variety of naming schemes and access table In relational databases, a form of data storage in methods, such as HTTP, FTP, and Internet mail. An which data is stored in records comprised of fields. Each example of a URL is http://www.hyperion.com. A URL can record is defined by a unique, or primary, key. also point to a file located on a local or network drive, such tag A Java class that implements a specialized interface as file:///D:/essbase/docs/essdocs.htm. enabling it to be used in a Java server page for processing.

336 Glossary A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

union An SQL command that is a type of join that WAA Utility Components Low level building blocks used combines the results of two SELECT statements. A union to perform processing for events, a repository, the is often used to merge lists of values contained in two hashtable, and exceptions. tables. WAA Web Components Handle functions specific to Web universal result set An object implementing the applications. For example, Web components handle user IWAAGrid interface, enabling clients to access OLAP or flow between the various JSPs. analysis tasks, such as relational data in the same way. The advantage is that you building and saving queries, displaying members and data, only need to create the JSP once to display both relational drilldown, and so on. and OLAP data. The Universal Result Set is also used to WAR file A Web archive file. A WAR file contains the generate output to various formats, for example PDF or complete directory structure and all files that define the HTML. You can create a single JSP that can display either Web application. For example, Web applications are relational and OLAP data in a grid. typically distributed as WAR files. URL See Uniform Resource Locator (URL). Web Application Architecture (WAA) A set of Java beans, User ID The key word that defines the user to the Java server pages, servlets, applets, and miscellaneous authentication server, and the user to the external supporting elements that can be combined in a variety of authentication method. In some cases the User ID may be ways to quickly create Web-based analytic applications. a short “cryptic” id. In other situations the User ID may be Web Application Architecture (WAA) provides tag the users complete name. libraries and reusable components that implement from 50% - 80% of the functionality required for a typical view In relational databases, a logical table created by custom analytic application. The architecture is designed combining columns from one or more tables. A view can with reuse and rapid development in mind. contain metadata and formatting information used to query an OLAP data source. web designer A person with HTML skills and user knowledge of data sources. visible tags A tag which produces visible HTML elements on a Web page, as well as processing server-side requests. web server A computer that delivers, or serves up, Web pages. WAA annotation Text, a URL, or a file. A WAA annotation is set up using tags and it can be assigned to an XML query An ADM query formatted as an XML string. OLAP data cell or cubeView, and a relational row or For example, the tags defined in Application Builder are queryInfo. used to define a member and data XML query.

WAA Core Domain Contains the basic framework for the architecture, as well as general purpose, reusable components. The relational and OLAP Domain extend the core objects.

WAA drill-through Navigates from an OLAP data cell to corresponding data in a relational data source.

WAA OLAP Domain Contains components designed to facilitate typical analysis tasks, such as building and saving queries, displaying members and data, drilldown, and so on.

WAA Relational Domain Contains components designed to facilitate SQL drill-through from an OLAP cube to the relational database that was used to build the cube. Functionality to edit and run an SQL query is also provided.

Glossary 337 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

338 Glossary A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index

A Advanced Options navigation button, 22 accessing Administration Tools, 20 alerts, defined, 81 Cell Format Tool, 104 Analysis Tools Framework (ATF) repository, 149 Conversion Tool, 150 Annotation XML file Edit Member Tool, 73 creating, 97 Managing Groups, 156 annotation XML files, 305 Security Tool, 153 Annotation XML Setup XML Setup Tool, 92, 167 Annotation Setup page, 100 accessing XML Files Creating a Relational Annotation, 99 introduction, 92, 167 Creating an OLAP Annotation, 93 add API, 270 child member, 74 application sibling above, 74 passwords, 23 sibling below, 74 roles, 23 add cube view cell value format cube format task, 252 users, 23 add query information cell value format database format task, 260 application projects. See Hyperion Hub ADM pooling, 24 arranging setting up, 29 member order, 74 ADM pooling, setting up, 267 asynchonously, tasks, 204 audience for this guide, 9 Administration Tools authentication accessing, 20 J2EE, 153 Conversion Tool, 149 single sign-on, 153 Edit Member Tool, 73 Available Columns list, 83 home page, 21 home page url, 20 languages, 21 C login and logout, 22 Cell Format XML Setup navigating, 22 accessing, 104 Security Tool, 153 Cell Format Setup page, 104 View Tool, 77 Creating a Relational Cell Format XML File, 111 XML Setup Tool, 91, 163 Creating OLAP Cell Format XML File, 105 advanced column settings child member selecting columns, 84 add, 74

Index A 339 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z completing creating SQL queries SQL queries, 86 applying a group by, 85 SQL query, 80 applying filters to queries, 84 conditionals task, 227 deleting a filter, 85 configuration, 47 completing, 80 consulting services, 13 completing the query, 86 conversion exporting the query to text, 87 of a repository, 150 navigating, 81 Conversion Tool selecting columns, 83 accessing, 150 advanced columns, 84 Conversion page, 150 selecting queries, 82 introduction, 149 selecting tables, 82 core tasks, 245 sorting columns, 86 creating cube an OLAP annotation, 93 defining, 268 Annotation XML files, 97 cube task, 253 groups, 156 cube view cell value format manager task, 254 users, 154 cube view cell value format task, 254 views, 78 cube view export data source, 255 Creating a Relational Annotation cube view export manager task, 256 Columns cube view export task, 256 Edit Properties page, 102 cube view grid task, 257 Database cube view task, 257 Properties page, 101 Defining Groups, 101 D Group data source task, 229 Edit Properties page, 102 data source XML file, 267 relational tree data sources Annotation Setup page, 100 relational, 279 Save page, 103 database meta data task, 227 Selecting a Relational Database, 101 database task, 228 Selecting A Server, 100 Date/Time format value Selecting Columns in the Database, 102 Index, 110 Selecting Table, Column Objects, 103 Locale, 110 Server Pattern, 110 Edit Properties page, 101 Style, 110 Table, Column Type, 110 Edit Properties page, 103 Debug/Locale/Encryption Creating an OLAP annotation, 96 Edit Properties page, 123 Cell Format Setup page, 94 default dimensions Choosing a Data Source, 95 selecting, 79 Creating a Group, 96 deleting Edit Member page, 98 filters from queries, 85 Edit Properties page, 98 member, 75 Save page, 99 users, 154

340 Index D A B C D E F G H I J K L M N O P Q R S T U V W X Y Z dimension data Edit View page filtering and sorting, 80 Data Filtering and Sorting section, 80 dimension members Default section, 79 managing, 73 editing dimensional hierarchies. See Hyperion Hub views, 78 documents editing groups See conventions used, 12 Managing Groups feedback, 13 creating, 156 ordering print documents, 12 education services, 13 structure of, 9 else task, 231 documents, accessing error log task, 230 Hyperion Download Center, 10 to 11 evaluate scripting framework task, 245 Hyperion Solutions Web site, 10 to 11 execute scripting framework task, 246 Information Map, 10 export XML files, 315 online help, 10 exporting models. See Hyperion Hub exporting to text Drill Through Setup Drill Through Setup page, 134 queries, 87 drill-through views, 80 enable functionality of, 281 external authentication enabling in web.xml, 282 about, 42, 142 uses, 281 prerequisites, 44, 143 drill-through tags setting up for Hyperion Application Builder, 68 OLAP driver, 285 single sign-on, 153 OLAP server, 285 with NT LAN, 44, 143 drill-through XML file, 279 drivers F specifying location on server, 283 to 284, 290 file input stream task, 232 file notify alert task, 232 E file properties task, 234, 244 file writer task, 233 edit members tree, 74 files StarSchemaDriver.jar, 281 Edit Member Tool WAADataSources.xml, 273, 276 accessing, 73 examples, 273 edit properties member, 74 tags, 281 Edit SQL Query page filtering and sorting confirm delete dialog, 88 dimension data, 80 Filter section, 84 fixed properties task, 235 format value Group section, 85 Always Show Decimal Separator, 108 Select Columns section, 83 Group Size, 108 Select Tables section, 82 Index, 108, 110 Edit View Locale, 108, 110 Edit Folder page, 88 Maximum Fraction Digits, 108 Edit Permissions page, 89 Maximum Integer Digits, 108 Export to text file page, 80

Index E 341 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Minimum Fraction Digits, 108 Hyperion Hub Minimum Integer Digits, 108 application projects Negative Prefix, 108 creating, 170 Negative Suffix, 108 deleting, 171 Pattern, 108, 110 described, 168 Positive Prefix, 109 permissions, 171 Positive Suffix, 109 renaming, 170 Scaling Factor, 108 configuring for external authentication, 163 Style, 110 dimensional hierarchies, 163 Type, 110 metadata formatting XML files, 291 managing, 167 From, 207 sharing, 168 models G comparing, 176 described, 163 general tasks, 226 editing content, 178 get scripting framework member task, 246 filtering content, 181 grid export data source, 247 grid export manager task, 247 permissions, 183 Grid Export Setup assigning, 185 Create deleting, 187 Edit Properties page, 141, 144 editing, 186 properties, viewing and setting, 187 Grid Export Setup page, 139 to 140, 142 renaming, 179 grid export task, 248 group sharing, 180 setting permissions for, 157 synchronizing, 175 Group By tracking version history, 182 applying to query tables, 85 viewing, 173 grouping task, 236 non-dimensional hierarchies, 163 Groups private models, 169 Edit Properties page, 96 projects, 168 guided analysis creating, 170 setting up, 166 deleting, 171 permissions H assigning, 171 deleting, 173 home page editing, 172 Administration Tools, 21 renaming, 170 home page url shared models, 169 Administration Tools, 20 shared projects, 168 to 169 Hyperion Application Builder creating, 170 Launch page, 20 deleting, 171 Hyperion Consulting Services, 13 permissions, 172 Hyperion Download Center accessing documents, 11 process, 169 Hyperion Education Services, 13 renaming, 170 selecting, 171

342 Index G A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

stopping sharing, 171 creating, 156 user authentication, 183 Group profile page, 157 Hyperion product information, 13 setting permissions, 157 Hyperion Solutions Web Site setting permissions accessing documents, 11 Permissions page, 157 Hyperion support, 13 special permissions page, 158 Hyperion Technical Support, 13 Managing OLAP Data Sources OLAP Data Source Edit Properties page, 129 I managing permissions of object types, 159 if scripting framework task, 249 importing models. See Hyperion Hub Managing Relational Data Sources introduction Relational Data Source Edit Properties page, 130 Conversion Tool, 149 Managing SQL Queries creating SQL queries, 81 editing SQL queries See J creating SQL queries, 81 J2EE Managing Users authentication, 153 creating, 154 Java Naming and Directory Interface (JNDI), 150 User Profile page, 154 JDBC data source task, 261 deleting, 154 JNDI settings, 24 delete confirmation dialog, 155 setting permissions, 155 L user permissions page, 155 languages managing users Administration Tools, 21 Security Tool, 154 link task, 236 managing views locating View Tool, 78 WAAGridExport.xml file, 92 mapping roles XML files, 92 ADM pools, 276 login and logout member Administration Tools, 22 deleting, 75 logon information, specifying, 284, 290 edit properties, 74 member order arranging, 74 M members tree mail notify alert task, 237 edit, 74 mail server task, 238 metadata management. See Hyperion Hub mail task, 239 model management. See Hyperion Hub managing move dimension to dimension members, 73 column, 79 users, 154 page, 79 Managing Cubes row, 79 Cube Edit Properties, 132 Managing Groups accessing, 156 N Groups page, 156 navigating

Index I 343 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Administration Tools, 22 Format SQL queries, 81 Edit Properties page, 107 navigation Page Advanced Options, 22 Edit Properties page, 108 buttons, 22 Save page, 109 Rows Per Page, 22 Select Source page, 106 nested tasks, 203 Selecting an OLAP Data Source, 105 non-dimensional hierarchies. See Hyperion Hub Setting the Formatting, 107 Numeric format value Numeric Cell Format Values, 107 Always Show Decimal Separator, 108 setting the formatting Group Size, 108 Date/Time Cell Format Values, 109 Index, 108 OLAP data and ADM pooling Locale, 108 accessing, 267 Maximum Fraction Digits, 108 OLAP data source, 281 Maximum Integer Digits, 108 defining, 268 Minimum Fraction Digits, 108 flat list, 275 Minimum Integer Digits, 108 tree format, 273 Negative Prefix, 108 OLAP databases, 281 Negative Suffix, 108 OLAP tasks, 251 Pattern, 108 Positive Prefix, 109 P Positive Suffix, 109 passwords Scaling Factor, 108 encrypting, 272 passwords, encrypting, 272 O path to Object Types WAAGridExport.xml, 139 managing permissions, 159 permissions Object Types page, 159 setting user, 155 permissions pool Edit Permission page, 161 defining, 270 special permissions pool definition Edit Permission page, 160 example, 271 object types pooling, setting up ADM, 267 prerequisites setting permissions, 161 data source concepts, 282 setting special permissions, 159 JDBC pooling, 282 OLAP Annotation Annotation Setup page, 94 SQL, 282 OLAP annotation prerequisites for using this guide, 9 properties creating, 93 for LDAP, 50 OLAP Cell Format for NTLM, 56 Date/Time Format properties files Edit Properties page, 110 modifying, 47 Save page, 111 Defining a Format Definition, 106

344 Index O A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Q default dimensions, 79 query information cell value format manager task, 262 queries, 82 query information cell value format task, 262 selecting columns query information export data source task, 263 advanced column settings, 84 query information export manager task, 264 for SQL queries, 83 query information export task, 264 selecting tables query information task, 265 for SQL queries, 82 Query Management server, specifying on which schema driver is located, navigating SQL queries, 81 283 to 284, 290 set scripting framework task, 251 setting permissions R for a group, 157 relational data for views, 89 accessing, 279 to 288 of object types, 161 relational data sources setting special permissions setting up, 279 of object types, 159 relational data, accessing, 29 shared models. See Hyperion Hub relational tasks, 259 shared projects. See Hyperion Hub repository sharing metadata. See Hyperion Hub Analysis Tools Framework, 149 sibling above conversion, 150 add, 74 description, 29 sibling below editing .xml and .properties files for, 29 add, 74 repository object, 249 sibling tasks, 203 Rows Per Page single sign-on navigation list box, 22 about, 42, 142 running sorting columns views, 88 in SQL queries, 86 sql notify alert task, 240 S sql properties task, 241 SQL Query Management sample export XML creating a folder, 88 path, 139 deleting a query, 88 scheduled task definitions navigating SQL queries, 81 defined, 207 sql statement task, 242 schema task, 258 StarSchemaDriver,jar file, 281 scripting framework, 250 synchonously, tasks, 204 Security Tool accessing, 153 Managing Groups, 155 T Managing Users, 154 tags Object Types, 159 JDBC, 287 Select Columns Advanced page query, 289 Enter Expression section, 84 SQL query, 289 Select Function section, 84 WAADrillThrough.xml, 283 selecting task categories, 147, 202

Index Q 345 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z task definition X creating, 204 XML files task definition builder, 203 locating, 92 task definitions XML Setup Tool running, 205 accessing, 92 task registry, 202 accessing XML files, 92, 167 tasks Annotation XML Setup, 93 attributes, 205 Cell Format XML Setup, 104 core, 245 Data Source XML Setup, 119 general, 226 Drill Through Tool, 133 OLAP, 251 Grid Export XML Setup, 139 relational, 259 invalid XML dialog, 92 running, 204 locating XML files, 92 technical support, 13 XML Setup page, 92 XML Tags U OLAP data source, 269 Unified Model Language (UML) standards, 281 universal charting XML files, 323 url datasource task, 243 url task, 242 user setting permissions, 155 users deleting, 154 managing, 154

V versioning. See Hyperion Hub View Management creating views, 78 editing views, 78 exporting views to text, 80 running views, 88 setting permissions, 89 View Tool managing SQL Queries, 81 managing views, 78

W WAAGridExport.xml location, 92 path to, 139 web.xml intializing for tasks, 202

346 Index U