Top Banner
Hyperion Solutions Corporation Hyperion ® Performance Suite Release 8.3 Foundation Developer’s Guide P/N: D833383000
188
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: Hyperion 8.3 Developers Guide

Hyperion Solutions Corporation

Hyperion® Performance Suite™

Release 8.3

Foundation Developer’s Guide

P/N: D833383000

Page 2: Hyperion 8.3 Developers Guide

Copyright © 1999–2004 Hyperion Solutions Corporation.

All rights reserved.

“Hyperion” 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 of this manual 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 purchaser's personal use, without the express written permission of Hyperion.

The information contained in this manual 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 of this material.

This software described in this manual is licensed exclusively subject to the conditions

set forth in the Hyperion license agreement. Please read and agree to all terms before

using this software.

GOVERNMENT RIGHTS LEGEND: 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 Corporation1344 Crossman AvenueSunnyvale, California 94089

Printed in the U.S.A.

Page 3: Hyperion 8.3 Developers Guide

Contents

Preface

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Document Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiGeneral Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiHyperion Foundation Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . xivHyperion Intelligence Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . xivHyperion SQR Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Where to Find Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Additional Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiEducation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiConsulting Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiTechnical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

PART I API Documentation

CHAPTER 1 Getting Started with Java APIs

Basic Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Importing the SDK Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Obtaining a Session Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Invoking Hyperion Performance Suite Services . . . . . . . . . . . . . . . . . . . . 1-3

Java Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Java-Accessed Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Page 4: Hyperion 8.3 Developers Guide

iv Contents

CHAPTER 2 Hyperion Performance Suite Objects

Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2AbsoluteTimeEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2BaseObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2BQYDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3BQYJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4CustomCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4DataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4ExternallyTriggered Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5InstancePermission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6JobOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6ObjectID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6OCEDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7ParameterList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7PhysicalResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8QueryVector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8RecurringTimeEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8ReportMartEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Respository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9ScheduledTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10SPFSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10SQRJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10SQRJobOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11JobParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11ObjectType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12ReportMartException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13SessionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

Page 5: Hyperion 8.3 Developers Guide

Contents v

UnknownReportMartException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13UserValidationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

CHAPTER 3 Batch Driver Sample Program Control File

About the Batch Driver Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Accessor Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Group Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Category Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6User Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Data Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8OCE Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9BQY Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

CHAPTER 4 Sample Java Programs

Prerequisites for Running the Sample Programs . . . . . . . . . . . . . . . . . . . . . . 4-2

Running the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4AddBQYDocument.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5AddBQYJob.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5AddCategory.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5AddDocument.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6AddExternalLink.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7AddFavorites.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7AddGroup.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7AddLink.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8AddObjectType.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8AddOCEDocument.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8AddRole.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9AddSPF.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9AddSubscription.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10AddUser.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10AddVersions.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11AutoZip.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11BatchDriver.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12CategoryDelete.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12ExecuteBQYDocument.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14ExecuteBQYJob.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14ExecuteSQRJob.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Page 6: Hyperion 8.3 Developers Guide

vi Contents

ExpirationDate.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15FetchCategory.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15FetchDocument.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16ListEvents.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16ListGroups.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16ListUsers.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Login.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17NestedGroups.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17ObjectByPath.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18ObjectById.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18PublishEvent.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18PublishOutputDirectory.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19PublishPrinterResource.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19QueryGroup.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19QueryUser.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20ReplaceObject.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20SQRParms.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

Attributes and Supporting Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

PART II Customization

CHAPTER 5 HTML Templates

Customizing Hyperion Foundation Templates . . . . . . . . . . . . . . . . . . . . . . . 5-2Preparing to Write Custom Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Editing and Testing Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Importing the Contents of One Template into Another . . . . . . . . . . . . 5-4Template Element Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Template Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

Template Names and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

Modifying a Template: An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

Cascading Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

CHAPTER 6 Java Server Pages

JSP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Administrator Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Browser Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Dashboard Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Dataaccess Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Page 7: Hyperion 8.3 Developers Guide

Contents vii

IHTMLServlet Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3PersonalPage Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Scheduler Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Shared Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

JSP Pages Identified by User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

Viewing Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5Advanced Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6Browse Listing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6

Modifying File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8Modify File Properties Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9Modify BQY Document Properties Page . . . . . . . . . . . . . . . . . . . . . . . . 6-14

Creating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14Manage Jobs Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16Manage Events Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17Create Recurring Event Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18Create Externally Triggered Event Page . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20

Scheduling Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20Scheduling Information Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22General Properties Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22Select Job Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23Set Values Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24BQY Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24SQR Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28Generic Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28When to Run Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29Notification Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29

CHAPTER 7 Customizing E-mail Notifications

Configuring E-mail Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Notification Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Template File Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Choosing HTML or Text Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Template File Replacement Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Properties in the notification.properties File . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Images in HTML-Formatted E-mail Notifications . . . . . . . . . . . . . . . . . . . 7-11

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11

Page 8: Hyperion 8.3 Developers Guide

viii Contents

CHAPTER 8 SmartCuts

About SmartCuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

The get Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Getting and Viewing a Document, Report, or Form . . . . . . . . . . . . . . . 8-4Getting Report Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5Getting a Single Report Output Object . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

The run Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

The list Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

The listNav Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

The listIndex Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

The listAll Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11

SmartCut Variables for BQY Documents and Jobs . . . . . . . . . . . . . . . . . . . 8-12bqtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13mimetype or filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13dest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14SectionName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14BoundRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15JobOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15ShowForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15Limits and LimitValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

SmartCut Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18Example: Accessing Hyperion Performance Suite Content from a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18Example: Using SmartCuts Via HTML Forms . . . . . . . . . . . . . . . . . . . 8-22

CHAPTER 9 Extended Services

Integrating Extended Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2Configuration File for Extended Services . . . . . . . . . . . . . . . . . . . . . . . . 9-2URL to Access Extended Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3Examples Entries and URLs for Service Properties . . . . . . . . . . . . . . . . 9-4Aggregation of Query Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6Relative Links in Extended Service HTML Output . . . . . . . . . . . . . . . . 9-6Local Resource Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6

Displaying Extended Service Content on Personal Pages . . . . . . . . . . . . . . . 9-7

Page 9: Hyperion 8.3 Developers Guide

Contents ix

APPENDIX A How to Use the API Sample Programs for Non-Java Programmers

Preparing to Use the Sample Java Programs . . . . . . . . . . . . . . . . . . . . . . . . . A-2Installing Hyperion Performance Suite SDK . . . . . . . . . . . . . . . . . . . . . A-2Validating the Hyperion Performance Suite Connection . . . . . . . . . . . A-2Compiling the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Running the Login Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

Batch Driver Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7

Glossary

Index

Page 10: Hyperion 8.3 Developers Guide

x Contents

Page 11: Hyperion 8.3 Developers Guide

Preface

Welcome to the Hyperion Performance Suite, Developer’s Guide. This preface discusses the following topics:

■ “Purpose” on page xi

■ “Audience” on page xi

■ “Document Structure” on page xi

■ “Related Documents” on page xiii

■ “Where to Find Documentation” on page xvi

■ “Conventions” on page xvii

■ “Additional Support” on page xviii

■ “Documentation Feedback” on page xix

PurposeThis guide provides information that you need to use Hyperion Performance Suite APIs to customize and extend Hyperion Performance Suite.

AudienceThe audience for this guide consists of developers, program managers, and quality engineers. The audience should be conversant with Java programming, able to edit, compile, and execute Java programs in a development environment, and familiar with the Hyperion Performance Suite environment.

Document StructureThis document contains the following information:

Page 12: Hyperion 8.3 Developers Guide

xii Preface

Part I, “API Documentation,” provides information on the Hyperion Performance Suite APIs for experienced Java programmers. This part contains the following chapters:

Chapter 1, “Getting Started with Java APIs,” provides a high-level overview of the steps required to connect to and use the services of the Hyperion Performance Suite.

Chapter 2, “Hyperion Performance Suite Objects,” contains information on specific Hyperion Performance Suite API objects, describing some of the important SDK interfaces and classes that are publicly available.

Chapter 3, “Batch Driver Sample Program Control File,” describes how to create and modify the control file for the batch driver sample program, BatchDriver.java.

Chapter 4, “Sample Java Programs,” demonstrates some of the functionality of the APIs and provides a starting point for your own utility programs.

Part II, “Customization,” is a technical reference with information on the templates, the JSP pages, and instructions on how to customize e-mail notifications and create SmartCuts. This part contains the following chapters:

Chapter 5, “HTML Templates” explains how to modify the Hyperion Performance Suite HTML templates and how to add custom HTML templates.

Chapter 6, “Java Server Pages,” discusses the JSP pages used to create specific user interface pages in Hyperion Performance Suite.

Chapter 7, “Customizing E-mail Notifications,” shows how to configure and customize e-mail notifications. .

Chapter 8, “SmartCuts” provides information on the SmartCut commands as well as a few SmartCut examples.

Chapter 9, “Extended Services,” describes how to integrate an extended service with the Hyperion Performance Suite servlets.

Appendix A, “How to Use the API Sample Programs for Non-Java Programmers” includes instructions on preparing to use the sample programs, how to compile and run sample programs, and a tutorial on how to add a user using the Batch Driver sample program.

The Glossary contains a list of key terms and their definitions.

The Index contains a list of Hyperion Performance Suite terms and their page references.

Page 13: Hyperion 8.3 Developers Guide

Preface xiii

Related DocumentsThe Hyperion Performance Suite comprehensive documentation set offers detailed technical information, troubleshooting advice, and best practices guidelines that help you maximize your Hyperion Solutions experience. In addition to the manuals listed, Hyperion Performance Suite products include substantial online help and release notes.

Note The documents listed in this section are located on the Document CD that ships with Hyperion Performance Suite.

General DocumentationNew Features in Hyperion Performance Suite describes the new functionality of the Hyperion Performance Suite system.

The Hyperion Performance Suite Installation Guide provides the information that you need to install the Hyperion Performance Suite software successfully on both Microsoft Windows and UNIX systems. It includes operating system and third-party software requirements; installation instructions and prerequisite information; installation details including directory structure and contents, registry entries, and sample INI, config, log, and startup files; configuration information for those administration tasks necessary to complete installation; and troubleshooting information including error messages.

The Hyperion Performance Suite Migration Guide provides guidelines and recommendations for migrating from Brio Portal 7. 0.X to Hyperion Performance Suite, and for migrating from Brio Intelligence 6.5 to Hyperion Performance Suite.

The Hyperion Performance Suite Accessibility Guide describes the accessibility features of all Hyperion Performance Suite products.

Page 14: Hyperion 8.3 Developers Guide

xiv Preface

Hyperion Foundation DocumentationThe Hyperion Foundation User’s Guide explains how to use Hyperion Performance Suite to find information that you need, make often-used information readily accessible, share information with others, and generate reports. The Hyperion Foundation User’s Guide is written for all levels of Hyperion Performance Suite users, from those who need simply to find and view documents, to those who need to publish many kinds of files or schedule jobs and distribute the output around the globe.

The Hyperion Foundation Administrator’s Guide encompasses administration of Hyperion Foundation services, applications, and tools. This book helps administrators define users and access privileges, configure and maintain the Hyperion Performance Suite system, and customize the user interface. The Hyperion Foundation Administrator’s Guide is written for all levels of Hyperion Performance Suite administrators, from those who administer only a group of users, to those who oversee an entire system.

Hyperion Intelligence DocumentationThe Hyperion Intelligence Getting Started Guide provides an overview of the Hyperion Intelligence client components and explains the user interface and the basic commands. It includes information on how to retrieve data, how to query new data and change existing queries, and how to query a single database as well as multiple databases. It also covers how to work with query results. It is written for all levels of Hyperion Intelligence users.

The Hyperion Intelligence Data Analysis and Reporting Guide identifies the types of reports available in the Hyperion Intelligence client components and provides an overview of reporting concepts. It is written for all levels of Hyperion Intelligence users, from those who need only to retrieve and view data in a report format to those who need to build queries and reports as well as analyze data.

The Hyperion Intelligence Object Model and Dashboard Design Guide provides an explanation of Dashboard sections and of the JavaScript syntax and object framework, specifically as they apply to interacting with BQY document elements. This book is written for developers who use Hyperion Explorer or Hyperion Designer to create documents and who need use the Dashboard functionality provided by Hyperion Intelligence to create front-ends .

Page 15: Hyperion 8.3 Developers Guide

Preface xv

The Hyperion Intelligence Administrator’s Guide helps administrators manage Hyperion Intelligence. The book is written for Hyperion Explorer and Hyperion Designer users who have access to more advanced features (such as connectivity and data modeling) and who may have responsibility for implementing Hyperion Intelligence in an enterprise environment.

Hyperion SQR DocumentationThe Hyperion SQR Getting Started Guide provides procedures and code examples to help develop SQR reports. This book is written for programmers who have a working knowledge of SQL and experience in writing software programs and who are developing reports for relational databases.

The Hyperion SQR Language Reference describes the structure, command set, and syntax of the SQR language. It also provides a directory to the library of sample SQR programs, an overview of the SQR initialization file, and a list of SQR messages. This reference is intended for Hyperion SQR and SQL developers who must report on data from a wide range of enterprise data sources.

Designing Reports with Hyperion SQR Developer explains how to create SQR reports on Windows systems: use the Hyperion Solutions GUI report design and layout tool, Hyperion SQR Developer. This book is written for anyone who wants to use the SQR Developer graphical user interface to create reports. To use this book effectively, you should be familiar with general report creation and your particular database and operating system. If you want to use Hyperion SQR to create more complex reports you should be familiar with SQR syntax and commands.

Accessing Data with Hyperion SQR for DDO provides an abstraction layer for heterogeneous data sources. This book describes DDO, its architecture and interfaces. It provides examples and instructions for accessing data from a DDO application and for writing a DDO driver. The book also discusses programming considerations and DDO common utilities. This book is written for developers who want to write DDO drivers that implement the DDO interfaces, as well as for application developers who want to use the DDO interfaces for data access in their applications.

Page 16: Hyperion 8.3 Developers Guide

xvi Preface

Using Hyperion SQR Activator explains how to use an application development environment to integrate Hyperion SQR into a business application. This book is written for application developers familiar with Micorsoft ActiveX controls who want to give their users the ability to run, view, and print SQR reports as part of their applications.

Where to Find DocumentationAll Hyperion Performance Suite documentation is accessible from the following locations:

■ Online help is accessible from the product that it documents. Start the product and click the Help button or menu command.

■ 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 documentation from the Hyperion Solutions Web site:

1 Log on 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 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.

4 Follow the on-screen instructions.

Page 17: Hyperion 8.3 Developers Guide

Preface xvii

You can order printed documentation in any of the following ways:

■ 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.

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

Table 1 Conventions Used in This Document

Item Meaning

➤ Arrows indicate one-step procedures.

Bold Bold highlights options, buttons, or tabs that you need to choose and text that you need to type.

CAPITAL LETTERS Capital letters denote commands, various IDs, and file name exten-sions.

For 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 font is also used for file names, directory and folder names, and path names.

For example: Sample1.bqy is located in the \HYPERION_HOME\Samples directory.

Page 18: Hyperion 8.3 Developers Guide

xviii Preface

Additional SupportIn 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 ServicesHyperion 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 ServicesExperienced 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.

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

Mouse orientation This document provides examples and procedures that use a right-handed mouse. If you use a left-handed mouse, adjust the proce-dures 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.

Table 1 Conventions Used in This Document (Continued)

Item Meaning

Page 19: Hyperion 8.3 Developers Guide

Preface xix

Technical SupportHyperion 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 FeedbackHyperion strives to provide complete and accurate documentation. Hyperion values your opinions on this documentation and want to hear from you. Give us your comments by going to http://www.hyperion.com/services/support_programs/doc_survey/index.cfm.

Page 20: Hyperion 8.3 Developers Guide

xx Preface

Page 21: Hyperion 8.3 Developers Guide

P A R T I

IAPI Documentation

Page 22: Hyperion 8.3 Developers Guide
Page 23: Hyperion 8.3 Developers Guide

1 Getting Started with Java APIs

Hyperion-provided APIs, which are a collection of 100% pure Java APIs, and sample programs are designed to enable organizations that use Hyperion Performance Suite to access features and capabilities from their own Java programs. This chapter provides a high-level overview of the steps required to connect to and use the services of Hyperion Performance Suite from a Java application program.

For detailed instructions, see Chapter 4, “Sample Java Programs.”

Note Using APIs to enhance, extend, or customize your Hyperion Performance Suite system is considered nonstandard and is not supported by Hyperion customer support.

In This Chapter Basic Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Java Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4

Java-Accessed Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

Page 24: Hyperion 8.3 Developers Guide

1-2 Getting Started with Java APIs

Basic Steps

Using Hyperion Performance Suite services from a Java application program requires only a few basic steps:

1 Import the Software Development Kit (SDK) package into the program by using an import statement.

2 Obtain a Session interface. This process authorizes the account to Hyperion Performance Suite and provides access to all Hyperion Performance Suite services.

3 Invoke Hyperion Performance Suite services from a Java program.

Importing the SDK PackageImport statements enable the Java compiler to find all class definitions referenced by a program. In order to access the classes and methods provided by the SDK package, you need to include the following statement in the source code for your Java program:

import com.sqribe.rm.*;

This statement defines each of the interfaces that your program uses during the course of its execution. You should make sure that the path describing the location of the SDK package is defined in the classpath environment variable used by your Java compiler. For the Windows environment, you can specify the following as classpath:

.;%Install_Home%\SDK;%Install_Home%\SDK\lib\rmapi.jar;%Install_Home%\SDK\lib\jython.jar;%Install_Home%\lib;%Install_Home%\SDK\etc\log4j;%Install_Home%\lib\log4j.jar;%Install_Home%\lib\foundation.jar;%Install_Home%\lib\iona61.jar;%Install_Home%\lib\comutil1_01.jar;%Install_Home%\lib\logi.crypto1.1.2.jar;%Install_Home%\lib\xercesImpl.jar;%Install_Home%\lib\xmlParserAPIs.jar;%Install_Home%\lib\spf82.jar;%Install_Home%\lib\commons_collections.jar;%Install_Home%\BrioPlatform\lib\bqservice.jar;

Note: Replace %Install_Home% with the correct location. For example, if Hyperion Performance Suite installation has the directory structure D:\Hyperion\BrioPlatform, replace %Install_Home% with D:\Hyperion. For UNIX installations, replace with the equivalent directory (for example, /usr/apps/hyperion) and also change each \ (back slash) to a / (front slash).

Page 25: Hyperion 8.3 Developers Guide

Basic Steps 1-3

Obtaining a Session InterfaceThe first step in establishing contact with Hyperion Performance Suite services is to obtain a Session interface by using one of the static getInstance() methods of the SDK SessionFactory class. This class validates the login information that you pass from your program to Hyperion Performance Suite and subsequently passes back to your program the Session interface that represents the connection between Hyperion Performance Suite and your program. The following code fragment demonstrates how to use SDK to connect to Hyperion Performance Suite:

try{String user = args[0];String pwd = args[1];String host = args[2];Session theSession = SessionFactory.getInstance(user, pwd, host);……}catch (ReportMartException e)

Invoking Hyperion Performance Suite ServicesAfter you establish the connection to Hyperion Performance Suite and you have a Session interface, use the returned Session to obtain access to the other interfaces that provide access to Hyperion Performance Suite services. For example, a highly-used interface is the Repository interface, which provides various methods for obtaining lists of users, groups, and other entities. Your program can obtain the Repository interface as follows:

try{String user = args[0];String pwd = args[1];String host = args[2];Session theSession = SessionFactory.getInstance(user, pwd, host);Repository theRepository = theSession.getRepository();}catch (ReportMartException e)

Page 26: Hyperion 8.3 Developers Guide

1-4 Getting Started with Java APIs

Java ExceptionsMost method calls to classes in the com.sqribe.rm.* package throw a ReportMartException, which is an Exception class derived from the standard java.lang.Exception class. Throwing exceptions is the normal mechanism used in the APIs to communicate a negative result from a method invocation. To avoid providing countless subclasses of ReportMartException to cover all possible failure scenarios, the ReportMartException classes are limited, with most of the subclasses related to login processing:

■ UnknownReportMartException: Thrown when the host name cannot be resolved or when no Service Agent is running on the host

■ UserValidationException: Thrown when the user ID or password that is provided is invalid

All calls to API methods must be enclosed in a try / catch block, as seen in the following example code that shows how to log on to Hyperion Performance Suite:

import com.sqribe.rm.*;public class TestSDK{static Session theSession = null;public static void main(Strings [] args){// assume that args contains username, password and hosttry{theSession = SessionFactory.getInstance(args[0], args[1], args[2]);...... your code goes here...}catch (UnknownReportMartException e1){// unable to connect to specified hostSystem.out.println(e1.getMessage());}catch (UserValidationException e2){// invalid account or passwordSystem.out.println(e2.getMessage());}}}

Page 27: Hyperion 8.3 Developers Guide

Java-Accessed Functions 1-5

Java-Accessed FunctionsJava programs can take advantage of Hyperion Performance Suite services in order to access various Hyperion Performance Suite functions, depending on the privileges granted by the administrator to the account used to connect to Hyperion Performance Suite.

The following list identifies examples of the functions that can be accessed by a Java API program:

■ Creating, modifying, or deleting user accounts or querying the attribute information related to accounts

■ Creating or deleting Hyperion Performance Suite folders or hierarchies of Hyperion Performance Suite folders and copying data files between folders and the local file system

■ Creating, modifying, or deleting Hyperion Performance Suite groups and, based on group membership specifying access rights to objects

■ Publishing or modifying properties for documents or jobs

■ Creating, modifying, or deleting resources, such as printers or output directories

Page 28: Hyperion 8.3 Developers Guide

1-6 Getting Started with Java APIs

Page 29: Hyperion 8.3 Developers Guide

2 Hyperion Performance Suite Objects

This chapter contains information on specific Hyperion Performance Suite API objects, describing some of the important SDK interfaces and classes that are publicly available. You can use the described interfaces and classes when creating a Java application program that interacts with Hyperion Performance Suite.

For more information on Hyperion Performance Suite interfaces and classes, see the Hyperion Performance Suite Javadocs in Install_Home/SDK.

In This Chapter Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2

Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11

Page 30: Hyperion 8.3 Developers Guide

2-2 Hyperion Performance Suite Objects

Interfaces

AbsoluteTimeEventSee: com.sqribe.rm.AbsoluteTimeEvent

This interface is used to create an event that is triggered at a given time. This event is a nonrecurring, one-time event which occurs only once at the specified point in time. This is an unnamed type of event. APIs modify and retrieve various properties of the event.

AuthenticationSee: com.sqribe.rm.Authentication

This interface provides methods for querying the Authentication System capabilities, creating new users and groups, listing users and groups or removing user and groups. In Hyperion Performance Suite, removing a user, or group object essentially means deactivating it. Methods are available in this interface to retrieve and list deactivated users and groups. Any deactivated user and group can be brought back to active state by applying the setActive() method to them. In Hyperion Performance Suite, users and groups cannot be completely removed from the system. Release 8.2 has been enhanced to support adding users and groups to a specified Authentication System as well to support logging on to a specific Authentication System (See class SessionFactory). APIs for configuring an Authentication System to support the Single Sign On (SSO) feature have been added.

AuthorizationSee: com.sqribe.rm.Authorization

This interface provides methods used to obtain or modify information about entities stored in the Authorization System. Methods are provided for creating, accessing and updating roles. In addition, methods for retrieving and listing system or business roles are available.

BaseObjectSee: com.sqribe.rm.BaseObject

Page 31: Hyperion 8.3 Developers Guide

Interfaces 2-3

This interface extends ReportMartEntity and provides additional methods used to access additional attributes of data objects stored in Hyperion Performance Suite. These additional attributes are infused to obtain or modify information about objects stored in Hyperion Performance Suite. Methods are provided that enable specifying and querying the following attributes associated with a BaseObject:

■ Custom property values that have been specified and saved with the object in Hyperion Performance Suite

■ Object type or metatype for the object

■ Ownership of the object

■ Automatic deletion of the object when an expiration date has been assigned

■ Whether the object can be browsed

BQYDocumentSee: com.sqribe.rm.BQYDocument

This interface provides methods to get information regarding BQY documents. It provides mechanism to get OCE mapping for the BQY query sections and enables you to set the OCEs for the query sections. It also supports methods to check and set the iHTML rendering of BQY documents.

BQYJobSee: com.sqribe.rm.BQYJob

This interface extends the Job interface. It enables you to set and update actions associated with a BQY job. Methods are available for setting cycles and actions associated with those cycles. It is possible to set the BQY job to run in the foreground or background and to assign a default calendar to be associated with this job by using the methods included for this interface. New classes (such as BQYOLAPParameter, BQYOLAPSlicerParameter, etc) have been added to support OLAP and OLAP Slicer parameters for BQY jobs. Also new methods have been added to the BQYParameter class and the BQYSectionInfo interface to support variable limit parameters containing complex sections (union subquery and master data model).

Page 32: Hyperion 8.3 Developers Guide

2-4 Hyperion Performance Suite Objects

CategorySee: com.sqribe.rm.Category

This interface provides methods that enable your program to copy files and the contents of directories to and from the local file system, automatically creating the corresponding Category hierarchy in Hyperion Performance Suite as needed. Methods are also provided to enable recursive deletion of categories and their contents.

CollectionSee: com.sqribe.rm.Collection

This interface provides utility methods similar to a Vector that enables you to access sets of objects. These Collection interfaces are commonly associated with the output from job executions.

CustomCalendarSee: com.sqribe.rm.CustomCalendar

This interface is used to define a calendar specific to the business, such as fiscal and manufacturing etc. CustomCalendar and CalendarYear together provide a structure to define a customizable calendar. Different types of custom calendars could be defined including internal, external, and default. Only one default calendar can be defined, and it is already constructed by the system. CustomCalendar contains a list of calendar years and also contains information about nonworking days. A calendar year contains information about a custom year, such as the period limits and quarters limits. Calendar years are defined only for internal calendars.

DataObjectSee: com.sqribe.rm.DataObject

This interface defines additional methods that can be invoked on objects that have been stored in Hyperion Performance Suite, such as HTML documents, SQR Reports, and comma-separated value data files. The interface enables your program to obtain lists of keywords associated with the object, to update the contents of the DataObject, and to retrieve contents from the local file system.

Page 33: Hyperion 8.3 Developers Guide

Interfaces 2-5

ExternallyTriggered EventSee: com.sqribe.rm.ExternallyTriggeredEvent

This interface defines an event that is triggered by an external action. The triggering of this event is a two stage process. When this event is triggered, it is set to run immediately. Externally Triggered Events are always PUBLIC events.

GroupSee: com.sqribe.rm.Group

This interface provides methods used to access the attributes of Group objects defined in Hyperion Performance Suite. Using this interface, your program can invoke methods that enable you to add a member to the group, to discover the roles that are members of the group, or to delete the group.

InstancePermissionSee: com.sqribe.rm.InstancePermission

The system automatically creates this interface including default access control when the Hyperion Performance Suite system creates an object.

The default access control grants full control to the owner of the object. This interface is equivalent to the Permissions class in Brio Portal and has been deprecated in Hyperion Performance Suite. The interface is obtained by invoking the getInstancePermission() method on an object. After retrieval, it can be modified to enforce new access control on it. It provides necessary methods to grant different levels of access control for different users, groups, and business roles.

Two other interfaces, RoleAccessor and Role, are very closely related to this interface. For example,here are the steps to grant the “MODIFY” role to “User1” on an object “doc1”:

■ Retrieve the instance permission associated with the object by invoking the doc1.getInstancePermission() method.

■ Create a RoleAccessor object using the createRoleAccessor() method in the Authorization interface by sending User1 as a parameter.

Page 34: Hyperion 8.3 Developers Guide

2-6 Hyperion Performance Suite Objects

■ Retrieve the role object for “MODIFY” role using the getRoleByName() method of the Authorization interface and passing “MODIFY” as the parameter.

■ Add this role to the roles accessor created previously by invoking the addSystemRole() method on the role accessor object.

■ Add the role accessor to the instance permission object using the addRoleAccessor() method on the instance permission object.

■ Use the update() method on the instance permission object.

JobSee: com.sqribe.rm.Job

This interface executes predefined Hyperion Performance Suite jobs, submits the jobs to the Job Service, and retrieves the data objects that have been generated by the execution of the job. By using this interface, your program can alter runtime parameters prior to running the job. It can also query the job for information about databases used, the lifespan of output objects, and a host of other job attributes. New methods have been added in release 8.2 to support execution of jobs asynchronously in the background, as well as to get their execution status.

JobOutputSee: com.sqribe.rm.JobOutput

This interface is generated by the execution of a Hyperion Performance Suite job by a Job Service. After the job executes, your program may extract a JobOutput interface from the Job, and using the methods in JobOutput, can extract all the output data objects that were generated during the execution of the job.

ObjectIDSee: com.sqribe.rm.ObjectID

Page 35: Hyperion 8.3 Developers Guide

Interfaces 2-7

Each object stored in Hyperion Performance Suite contains a unique identifier that represents the object. Whereas multiple objects can be stored in a folder with the same name and metatype, they are distinguished from each other by the universally unique identifier (UUID) assigned to the object. This interface represents the UUID when invoking SDK methods that require an object ID.

OCEDocumentSee: com.sqribe.rm.OCEDocument

This interface is the object wrapper around the OCE file that is published to the repository. It provides methods to retrieve or set properties for the OCE file, such as the default database username and password to be used. It also provides methods to set the OCE to prompt users for the database username and password and to enable the single sign on feature for this OCE.

ParameterListSee: com.sqribe.rm.ParameterList

This interface encapsulates a vector of JobDef objects and other attributes controlling the execution of the jobs contained within the cluster. In addition to the JobDef vector, the ParameterList interface maintains a hold feature that enables the user to suspend execution of all Scheduled tasks associated with this ParameterList object until the hold mechanism is turned off. Parameter lists can be of three view types, public, personal, and unnamed. By default, the view type of a task is personal.

PhysicalResourceSee: com.sqribe.rm.PhysicalResource

This interface defines methods common to printer and output directory resources in a Hyperion Performance Suite system. Two types of physical resource objects are extended from the PhysicalResource interface:

■ PrinterPhysicalResource

■ OutputDirPhysicalResource

Page 36: Hyperion 8.3 Developers Guide

2-8 Hyperion Performance Suite Objects

Physical resource objects are created using methods in the Repository interface. They are addPrinterResource() and addOutputDirectory() for publishing a printer and an output directory, respectively. Two types of OutputDirPhysicalResource objects can be created; they are a simple output directory and an FTP output directory. Both PrinterPhysicalResource and OutputDirPhysicalResource interfaces define methods to modify properties of the physical resource objects.

QuerySee: com.sqribe.rm.Query

Your program obtains this interface using the Repository interface when the program wants to search Hyperion Performance Suite for a set of data objects that match a set of filter specifications. The Query interface defines methods that enable you to obtain lists of groups and users. It also provides other more generic methods that enable searching by object name, by keywords, or by a list of other object attributes, such as creation and access dates, object type, or object ownership.

QueryVectorSee: com.sqribe.rm.QueryVector

This interface is returned from each of the search methods supported by the Query interface. QueryVector provides access functions that enables your program to recover each of the elements returned from the search method invocation. The interface enables the program to discover the number of elements returned by the search, to determine whether the returned list of elements is empty, to access each element in the QueryVector interface by a numeric index value, or to obtain an Enumeration interface for more comprehensive manipulation of the set of objects returned by the search request.

RecurringTimeEventSee: com.sqribe.rm.RecurringTimeEvent

Page 37: Hyperion 8.3 Developers Guide

Interfaces 2-9

Use this interface for repetitive triggering of an event by specifying the date and time in various ways. The recurring time event can be of three types namely public, personal, or unnamed. By default the view type of a Recurring Time Event is personal. An unnamed event is a per-schedule event. It is valid only for the schedule for which it is created. It is deleted as soon as the schedule is deleted or the schedule is updated with another event. Notice that you can also create combo events that would be a combination of a Recurring Time Event and an Externally Triggered Event.

ReportMartEntitySee: com.sqribe.rm.ReportMartEntity

This interface provides access to object attribute information that is common to all objects stored in Hyperion Performance Suite, with the exception of Session-related data objects. It is used by an application to obtain or set basic attributes related to identifying an object in Hyperion Performance Suite, and for finding out certain key attributes such as these:

■ The various timestamps associated with an object, such as its creation or last modification date

■ Information related to the identity of the object, such as the name and description

RespositorySee: com.sqribe.rm.Repository

This interface provides access to a number of utility methods in the SDK. It is used to obtain most of the major interfaces through which your program can access the services of Hyperion Performance Suite.

ScheduledTaskSee: com.sqribe.rm.ScheduledTask

This interface is used to associate a parameter list with an event. In addition to the parameter list and event, this object also contains additional properties to control how the parameter list is executed.

Page 38: Hyperion 8.3 Developers Guide

2-10 Hyperion Performance Suite Objects

SchedulerSee: com.sqribe.rm.Scheduler

Use this interface to access the Hyperion Performance Suite Event Service to create, retrieve, list and delete the following objects:

■ AbsoluteTimeEvent

■ RecurringTimeEvent

■ ExternallyTriggeredEvent

■ ParameterList

■ CustomCalendar

■ CalendarYear

■ ScheduledTask

SessionSee: com.sqribe.rm.Session

This interface is the primary interface through which your program accesses all services provided by Hyperion Performance Suite. It is returned to your program when it has successfully logged in to Hyperion Performance Suite using one of the SessionFactory.getInstance() methods.

SPFSetSee: com.sqribe.rm.SPFSet

This interface represents the output from execution of SQR jobs by a Hyperion Performance Suite Job Service. This interface enables you to access the various types of output such as HTML, postscript, or other output formats that were generated by the SQR execution.

SQRJobSee: com.sqribe.rm.SQRJob

This interface is an extension of the Job interface that provides additional functionality supported by the execution and processing of SQR jobs in a Hyperion Performance Suite Job Service. Additional methods are available in

Page 39: Hyperion 8.3 Developers Guide

Classes 2-11

this interface to set and retrieve the ask parameters that are processed at the time of job execution, and to obtain the program output data objects generated during the execution of the SQR job.

SQRJobOutputSee: com.sqribe.rm.SQRJobOutput

This interface is returned by the getProgramOutputs() method of SQRJob interface. This extended interface enables your program to obtain the data objects generated by the execution of an SQR job, as well as the SPFSet interface that enables the program to obtain the various listing data objects.

UserSee: com.sqribe.rm.User

This interface is returned from various SDK method calls to represent a user account defined in Hyperion Performance Suite. This interface enables your program to obtain various attributes of the account such as group membership, default category, and default permissions. In addition, methods are provided to add the user to new groups, set new default permissions, descriptions, and other attributes, and to access and modify single sign-on properties for a User object.

Classes

JobParameterSee: com.sqribe.rm.JobParameter

The SDK generates this class when you invoke the setParameters() method on a Job interface. This class provides information about one of the data parameters passed to a job executing at runtime.

LoggerSee: com.sqribe.rm.Logger

Page 40: Hyperion 8.3 Developers Guide

2-12 Hyperion Performance Suite Objects

This class provides methods to enable clients to log their messages using the new log4j logging architecture. The client acquires an instance of a Logger object in every source file in which it wants to log messages. The client uses the static getLogger() method that takes a class name (String or Class object) as a parameter. Usually, this class is the fully qualified name of the source file. The new system works as follows:

The installer creates the %Install_Home%/SDK/log/ directory that will contain log files generated by a log4j model. If the default SDK directory is not used as the working directory, then the /log subdirectory will be created in the working directory. Users can create the /log subdirectory, however, in any place they want by using the -Ddirectory system property.

The directory containing the SdkLog4jConfig.xml file, <Install_Home>/SDK/etc/log4j, must be added to the classpath so that the log4j XML configuration file can be read.

The installer creates the %Install_Home%/SDK/etc/log4j/ directory that will contain the default XML configuration file for the log4j model. The name of this configuration file is SdkLog4jConfig.xml.

The following options for configuration remains open to the client:

■ Do nothing. SDK will read the default XML configuration file from the specified (default) location and create a log file – sdk.log in the appropriate directory. Clients can append their logging information to that log file.

■ Use the default XML configuration file and customize it. For example, the client can add its own appender and send its logging information to the new appender.

■ Write an XML configuration file and configure log4j logging model according to your preference. See Javadoc for the LogManager class for the appropriate method. The system property -Drmapi.log4j=false needs to be used.

■ Use the -Drmapi.log4j=false system property, for your JVM, if you do not want to use SDK logging system.

ObjectTypeSee: com.sqribe.rm.ObjectType

Page 41: Hyperion 8.3 Developers Guide

Classes 2-13

When objects are stored in Hyperion Performance Suite, they are associated with a metatype or object type that enables your program to filter search operations based on the type of object, as well as by keyword searches or by name. This class provides static methods that enable you to extract predefined ObjectType class instance variables that represent all the built in types found in Hyperion Performance Suite.

ReportMartExceptionSee: com.sqribe.rm.ReportMartException

This class is an Exception object thrown by most method invocations on the SDK package. To handle these exceptions, your program must use “try-catch” constructs to handle the exceptions when they are thrown. Each ReportMartException object provides a message that describes the error condition responsible for generating the exception.

SessionFactorySee: com.sqribe.rm.SessionFactory

This class provides a number of static getInstance() methods that enable your program to obtain the initial Session interface that it will require to do any useful work in Hyperion Performance Suite. Variations of the getInstance() methods are available. These methods enable you to specify various combinations of account, password, hostname, and TCP port number that are required so that your program can log on to Hyperion Performance Suite . One of the methods supports logging on to a specified Authentication System . The names of the available Authentication Systems can be obtained using a static method in class SystemObjects just by specifying the GSM host and port before logging on.

UnknownReportMartExceptionSee: com.sqribe.rm.UnknownReportMartException

Page 42: Hyperion 8.3 Developers Guide

2-14 Hyperion Performance Suite Objects

This Exception class can potentially be thrown during the initial invocation of a SessionFactory#getInstance() method by your program when the program is attempting to establish contact with Hyperion Performance Suite. If your program handles this exception, then either one of these events can occur:

■ The hostname you passed cannot be resolved to a TCP/IP address

■ The server itself is not accessible by the network

■ Contact cannot be established with Hyperion Performance Suite Service Broker running on that host

In the last case, check to make sure that the port number specified corresponds to the port on which the ServiceBroker is listening.

UserValidationExceptionSee: com.sqribe.rm.UserValidationException

This Exception class is thrown if a validation error occurs when your program is connecting to Hyperion Performance Suite. If the try-catch logic traps this error, then either the user account or password provided to the SessionFactory.getInstance() method is invalid.

Page 43: Hyperion 8.3 Developers Guide

3 Batch Driver Sample Program Control File

This chapter describes how to create and modify the control file for the batch driver sample program, BatchDriver.java. The control file must contain all the information for the objects that you want to create or publish to Hyperion Performance Suite. The control file is passed as an argument to the batch driver sample program.

For more information on BatchDriver.java, see “BatchDriver.java” on page 4-12.

For detail information on how to use the sample programs see Appendix A, “How to Use the API Sample Programs for Non-Java Programmers.”

In This Chapter About the Batch Driver Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2

Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2

Page 44: Hyperion 8.3 Developers Guide

3-2 Batch Driver Sample Program Control File

About the Batch Driver Control FileThe batch driver control file contains the data that the batch driver program processes. The batch driver program reads a batch driver control file and processes the data in it. A sample batch driver control file, batch_driver.cf is located in the same directory as the sample program source files. The sample file shows the syntax for all objects that can be bulk loaded using the batch driver sample program.

The following file is an example of a batch_driver.cf file that adds one new user:

#user uid=jwilliams^pwd=password^name=John Williams^desc=A Test User^defcat=/batchFolder^[email protected]^authensystem=default_system^group=testGroup1^group=testGroup3

Batch driver control files use the following syntax:

■ All parameters of each control statement must be included on the same physical line. Each line of the file is read and executed one-at-a-time.

■ Control files can contain any number of control statements including no statements.

■ Comments are supported and must be entered on their own lines. A comment line is any statement where the first non-blank character on the line is '#', '//', or '!'.

■ Blank lines are comments.

■ Each attribute name-value pair is separated by the symbol '^' .

■ No spaces can occur between the attribute name, the equal sign (=), and the attribute value of the statement parameters.

■ A value can contain one or more blanks. Attribute parameters can be specified in any order after the control verb.

Control StatementsControl statements are used to specify attributes of Hyperion Performance Suite objects that you want to add to Hyperion Performance Suite using the batch driver sample program. Control statements are composed of a starting term that denotes the type of control line and attribute-value assignment statements. The terms and attribute names are not case sensitive, but the values assigned to attributes are case sensitive.

Page 45: Hyperion 8.3 Developers Guide

Control Statements 3-3

The following types of control statements are supported by the BatchDriver program. Although the syntax descriptions in the following topics may show the attribute values on multiple lines, in practice all must be specified on a single control line.

.

Note Each attribute marked by an asterisk (*) can be specified multiple times. In any statement where the attribute value is specified as choice1|| choice2, one of the specified values may be provided. Assigned attribute values are interpreted as follows:

.

Table 3-1 Control Statements

Term Description

accessor Define an accessor for access control (permission)

group Define a group

category Define category attributes

user Add a user

data Add a data object

oce Add an OCE document

bqydoc Add a BQY document

Table 3-2 Attribute Descriptions

Attribute Description

date YYYY-MM-DD_HH:MM:SSZZZ where ZZZ is an optional time zone offset from GMT, for example, PST is '-08'

name Name string uniquely identifying an object

int Integer value

string String value; for example, e-mail address

path Folder in the repository where the object will be published

Page 46: Hyperion 8.3 Developers Guide

3-4 Batch Driver Sample Program Control File

The following topics describe each control statement in detail:

■ “Accessor Control Statements” on page 3-4

■ “Group Control Statements” on page 3-5

■ “Category Control Statements” on page 3-6

■ “User Control Statements” on page 3-7

■ “Data Control Statements” on page 3-8

■ “OCE Control Statements” on page 3-9

■ “BQY Control Statements” on page 3-11

Accessor Control StatementsAccessor control statements create accessor objects in the cache, but accessor objects are not stored in the database separately. Accessor objects are used in one or more objects as the value for the permission (perm) attribute and thus defines access control for other objects. Assessor ids are used to reference accessor objects when defining access control for other objects. A user, group, or role must be in the system before it is assigned as an accessor.

Example: accessor id=accessor1^type=group^name=world^sysrole=FULL CONTROL

id Unique non-blank string value used to reference a control statement

dref Reference to the control statement in which <id> value was used

boolean Value either TRUE or FALSE

datasource Repository database, SQR Engine combination, for example, HPS:SQR_Version_8.2

ifile Name of file on local file system

Table 3-2 Attribute Descriptions (Continued)

Attribute Description

Page 47: Hyperion 8.3 Developers Guide

Control Statements 3-5

Group Control StatementsGroup control statements are used to define new groups in the Hyperion Performance Suite database. Member assignment statements add members to the group by name. The name value is not type-specific so an attempt is made to locate the objects in the following order:

■ User object

■ Group object

The first object retrieved is the first object added as the group member.

The value passed to the perm attribute is the name of an accessor object that was previously defined in the control file and assigned a name; for example, accessor1, accessor2.

Example: group name=testGroup1^desc=A Test Group #1 ^authensystem=default_system^perm=accessor1

group name=testGroup2^desc=A Test Group #3 ^authensystem=default_system^member=testGroup1^perm=accessor1

Table 3-3 Accessor Control Statement Descriptions

Attribute Name Attribute Type Description

id id Accessor identifier in this program; not the objectID or uuid

type user|group|brole Type of the accessor—user, group, or business role

name name Name of the user, group, or business role

sysrole role name Name of the system role to be associated

Page 48: Hyperion 8.3 Developers Guide

3-6 Batch Driver Sample Program Control File

Category Control StatementsCategory control statements create categories or update properties of existing categories. The value passed to the perm attribute is the name of an accessor object that was previously defined in the control file and assigned a name; for example: accessor1, accessor2.

Example category path=/batchFolder^browse=true^autodelete=true^desc=A test Folder by batchdriver^expire=2005-06-20 12:00:00^perm=accessor2

Ca

Table 3-4 Group Control Statement Descriptions

Attribute Name Attribute Type Description

name name Name of the group

desc string Description of the group

authensystem string Name of the authentication system. The default is default_system.

member name* Members of the group. Members are usually other groups and users.

perm accessor* Access control—other users privileged to access

Table 3-5 Category Control Statement Descriptions

Attribute Name Attribute Type Description

path path Category path

browse boolean Browsable

autodelete boolean Autodelete

Page 49: Hyperion 8.3 Developers Guide

Control Statements 3-7

User Control StatementsUser control statements create new users with the properties provided in the control statement. The value passed to the perm attribute is the name of an accessor object that was previously defined in the control file and assigned a name; for example: accessor1, accessor2.

Example: user uid=testUser^pwd=testUser^name=Test User^desc=A TestUser^defcat=/batchFolder ^[email protected]^authensystem=default_system ^group=testGroup1 ^group=testGroup3^role=CONTENT PUBLISHER ^role=USER^perm=accessor2^perm=accessor4

desc string Description of the category

expire date Expiration date

perm accessor * Access control—other users, groups, and roles privileged to access this folder

Table 3-6 User Control Statement Descriptions

Attribute Name Attribute Type Description

uid string User login id

pwd string Password

name string User's full name

desc string Description of the user

defcat path Default folder path

email string e-mail address

Table 3-5 Category Control Statement Descriptions (Continued)

Attribute Name Attribute Type Description

Page 50: Hyperion 8.3 Developers Guide

3-8 Batch Driver Sample Program Control File

Data Control StatementsData control statements load or publish files into the repository from specified locations on your desktop. The resulting data object is loaded into the specified folder and is assigned the attributes specified by the parameters.

The value passed to the perm attribute is the name of an accessor object that was previously defined in the control file and assigned a name; for example: accessor1, accessor2.

Example: data name=aDocument^path=/batchFolder^file=D:\Doc\bart.doc ^desc=A test document by batchdriver ^browse=true^autodelete=true^expire=2004-06-22 12:00:00^keyword=MS doc^keyword=Design doc^perm=accessor2^perm=accessor4

authensystem string Name of the authentication system. The default is default_system.

group name * Group memberships

role role name* This user's privilege specified by business roles to access other objects

perm accessor * Access control—other users privileged to access this user

Table 3-7 Data Control Statement Descriptions

Attribute Name Attribute Type Description

data name Name in the repository

path path Folder in the repository where the object will be published

file filename Name of the file on the file system

desc string Description of the data name

Table 3-6 User Control Statement Descriptions (Continued)

Attribute Name Attribute Type Description

Page 51: Hyperion 8.3 Developers Guide

Control Statements 3-9

OCE Control StatementsOCE control statements load OCE files into the repository from the specified file source from specified locations on your desktop. The resulting OCE documents are loaded into specified folders and are configured according to the attributes specified by the parameters.

Example: oce name=anOCEDocument^path=/batchFolder^file=D:\Foundation\BQYFiles\odbc.oce^desc=A test OCE document by batchdriver ^prompt=false^dbuser=guest^dbpass=guest ^metaoce=Cqdb.oce^metaUseThis=false^metauser=guest ^metapass=guest^allowSSO=true^browse=true^autodelete=true ^expire=2004-06-24 12:00:00^keyword=OCE doc^keyword=Connection file^perm=accessor2^perm=accessor4

browse boolean Browsable

autodelete boolean Autodelete

expire date Expiration date

keyword string * Keyword strings

perm accessor * Access control—other users privileged to access this object

Table 3-7 Data Control Statement Descriptions (Continued)

Attribute Name Attribute Type Description

Page 52: Hyperion 8.3 Developers Guide

3-10 Batch Driver Sample Program Control File

Table 3-8 OCE Control Statement Descriptions

Attribute Name Attribute Type Description

id string OCE identifier, usually the name (not objectID/uuid); this is optional and may be omitted if the OCE is not used in this run of the program.

name name Name of the OCE in the repository

path path Folder in the repository where the object will be published

file filename File name to load

desc string Description of the OCE

prompt boolean Whether to prompt the user

dbuser string If prompt is false, the user for database connectivity

dbpass string If prompt is false, the password for database connectivity

metaoce oce name If there is a meta OCE, specify its name

metaUserThis boolean Whether to use the OCE connectivity information for the meta OCE

metauser string If metaUseThis is false, the user for meta OCE database connectivity

metapass string If metaUseThis is false, the password for meta OCE database connectivity

browse boolean Browsable

autodelete boolean Auto delete on expire

keyword string * Keyword strings

expire date Expiration date

perm accessor * Access control—other users privileged to access this object

Page 53: Hyperion 8.3 Developers Guide

Control Statements 3-11

BQY Control StatementsBQY control statements load BQY files into the repository from specified file sources from specified locations on your desktop. The resulting BQY documents are loaded into specified folders and are configured according to the attributes specified by the parameters.

Example: bqydoc name=aBQYDocument^path=/batchFolder^file=Simple.bqy^desc=A test BQY document by batchdriver^desc=A test BQY document by batchdriver^ihtml=true^oce=anOCEDocument^oceprompt=2 ^dbuser=guest^dbpass=guest^pregen=2^browse=true^autodelete=true^expire=2005-06-24 12:00:00^keyword=BQY doc^keyword=CQ 22535^perm=accessor1^perm=accessor3

Table 3-9 BQY Control Statement Descriptions

Attribute Name Attribute Type Description

name name Name of the BQY in the repository

path path Folder in the repository where the object will be published

file filename File name to load

desc string Description the BQY Control Statement

ihtml boolean Whether to enable BQY for use in HTML

oce idref||oce name OCE id or the name of the oce;<oce name> may be used if the OCE is published beforehand.For example, not in this run of this program

prompt boolean Whether to prompt the user for the OCE by using the OCE prompt

dbuser string If prompt is false, the user for database connectivity

dbpass string If prompt is false, the password for database connectivity

Page 54: Hyperion 8.3 Developers Guide

3-12 Batch Driver Sample Program Control File

pregen int HTML pregeneration options for the BQYdoc:

■ 0: Pregenerate ALL sections

■ 1: Pregenerate no sections

■ 2: Pregenerate selected sections

browse boolean Browsable

autodelete boolean Auto delete on expire

keyword string * Keyword strings

expire date Expiration date

perm accessor * Access control—other users privileged to access this object

Table 3-9 BQY Control Statement Descriptions (Continued)

Attribute Name Attribute Type Description

Page 55: Hyperion 8.3 Developers Guide

4 Sample Java Programs

You can use the Hyperion Performance Suite APIs in many ways to access Hyperion Performance Suite functionality from within your Java programs. The samples in this chapter demonstrate this functionality and provide a starting point for your own utility programs. The sample Java programs, sample property files, and sample control files are located at Install_Home\SDK\samples\java.

UNIX users replace the batch (BAT) files with shell (SH) files and reverse the slash marks in the path names, for example, Install_Home\SDK\lib\rmapi.jar is Install_Home/SDK/lib/rmapi.jar in UNIX. Other differences are noted in the text.

In This Chapter Prerequisites for Running the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2

Running the Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2

Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4

Attributes and Supporting Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21

Page 56: Hyperion 8.3 Developers Guide

4-2 Sample Java Programs

Prerequisites for Running the Sample ProgramsFor detail information on how to use the sample programs see Appendix A, “How to Use the API Sample Programs for Non-Java Programmers.”

To use the sample programs you will need the following:

■ Hyperion Performance Suite SDK installed on your machine

■ Java compiler and runtime environment installed on your machine

■ Access to the Hyperion Performance Suite core services via a URL (host name and port number), for example, http://venice:8100/Hyperion/browse/Main

■ Valid username and password with administrator access control

Running the Sample Programs

The execapi.bat file, located in <Install_Home>\SDK\bin\, is generated by the installer and can be used to set up the environment and run any of the sample programs.

To run a sample program:

1 Compile the program.

For compilation information, see “Compiling the Sample Programs” on page A-3.

2 Check that Hyperion Performance Suite is up and running.

a. Enter URL in Web browser: http://<host>:<port>/<path>

For example: http://venice:8100/Hyperion/browse/Main

b. Enter a valid username and password.

You should see the following page:

Page 57: Hyperion 8.3 Developers Guide

Running the Sample Programs 4-3

3 Open a command prompt window and run execapi.bat, passing the name of the program and the arguments for the program.

For example: C:\Program Files\Brio\hp276\SDK\bin>execapi BatchDriver administrator administrator qastar 1800

batch_driver.cf

4 Log in to Hyperion Performance Suite to validate your changes.

Page 58: Hyperion 8.3 Developers Guide

4-4 Sample Java Programs

SamplesThe following topics provide detailed descriptions of the samples:

Table 4-1 Links to Descriptions of API Samples

Samples A - EX Sample Exec - SQ

“AddBQYDocument.java” on page 4-5 “ExecuteBQYJob.java” on page 4-14

“AddBQYJob.java” on page 4-5 “ExecuteSQRJob.java” on page 4-15

“AddCategory.java” on page 4-5 “ExpirationDate.java” on page 4-15

“AddDocument.java” on page 4-6 “FetchCategory.java” on page 4-15

“AddExternalLink.java” on page 4-7 “FetchDocument.java” on page 4-16

“AddFavorites.java” on page 4-7 “ListEvents.java” on page 4-16

“AddGroup.java” on page 4-7 “ListGroups.java” on page 4-16

“AddLink.java” on page 4-8 “ListUsers.java” on page 4-17

“AddObjectType.java” on page 4-8 “Login.java” on page 4-17

“AddOCEDocument.java” on page 4-8 “NestedGroups.java” on page 4-17

“AddRole.java” on page 4-9 “ObjectByPath.java” on page 4-18

“AddSPF.java” on page 4-9 “ObjectById.java” on page 4-18

“AddSubscription.java” on page 4-10 “PublishEvent.java” on page 4-18

“AddUser.java” on page 4-10 “PublishOutputDirectory.java” on page 4-19

“AddVersions.java” on page 4-11 “PublishPrinterResource.java” on page 4-19

“AutoZip.java” on page 4-11 “QueryGroup.java” on page 4-19

“BatchDriver.java” on page 4-12 “QueryUser.java” on page 4-20

“CategoryDelete.java” on page 4-12 “ReplaceObject.java” on page 4-20

“ExecuteBQYDocument.java” on page 4-14

“SQRParms.java” on page 4-20

Page 59: Hyperion 8.3 Developers Guide

Samples 4-5

AddBQYDocument.java Use this sample to publish a BQY document to Hyperion Performance Suite and to set essential attributes. The Intelligence Service, in addition to the common services, must be running to publish BQY documents using this sample. A properties file is used to get information needed for publishing a BQY document. A sample properties file, inputBQYDoc.txt, is included in the same directory as the source code.

A sample attribute in the property file is the BQY.iHTMLView flag which determines if the BQY file is available when using the Intelligence iServer.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Target Folder> <BQY File> <Property File, e.g. inputBQYDoc.txt>

Output: BQY document is published in the Hyperion Performance Suite repository in the target folder.

AddBQYJob.java Use this sample to publish a BQY job and to set some of its properties. The Intelligence Service, in addition to the common services, must be running in order to publish BQY jobs using this sample. A properties file is used to get information needed for publishing a BQY document. A sample properties file, inputBQYDoc.txt, is included in the same directory as the source code.

A sample property in the property file sets the BQY.iHTMLView flag to true, which makes the BQY file available when using the Intelligence iServer.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Target Folder> <BQY File> <Property File, e.g. inputBQYJob.txt>

Output: BQY job is published in the Hyperion Performance Suite repository in the target folder.

AddCategory.java The Addcategory.java sample demonstrates the creation of a folder and is installed with the Hyperion Performance Suite SDK located on Install_Home\SDK\Samples\java in Hyperion Performance Suite. All folders in the path that do not exist in the system are created in the process.

Page 60: Hyperion 8.3 Developers Guide

4-6 Sample Java Programs

Input parameters: <user> <pwd> <host> <port> <catpath>

For example:

java AddCategory username password saturn 1800 /Sales

Output: Folders are created in Hyperion Performance Suite.

AddDocument.javaUse this sample to publish a document to an existing target folder and to set the properties of the document.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Document Name> <Target Folder>

Output: Document is published to the Hyperion Performance Suite target folder.

Page 61: Hyperion 8.3 Developers Guide

Samples 4-7

AddExternalLink.javaUse this sample to create an external link (URL) from Hyperion Performance Suite to another Web site. Link properties and the target folder are passed as arguments.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Target Folder> <Link Name> <Description> <URL>

Output: An external Link (<Link Name>) is created in the Hyperion Performance Suite target folder.

AddFavorites.javaUse this sample to add new folders and new favorite items. The user needs administrator privileges to create the objects.

Input parameters: <user> <pwd> <GSM host> <GSM port> <gif1> <gif2>

Output: New folders are created and new favorite items are added to a user’s favorite item list in Hyperion Performance Suite.

Example of syntax:

java -classpath %CLASSPATH% AddFavorites administrator administrator localhost 1800 D:\Test1.gif D:\Test2.gif

AddGroup.javaUse this sample to add groups and to add child groups to a parent group. This sample specifically adds Group1, Group2, Group3, and Group4 to the parent group, Master. If the Master group does not exist, it is also added.

Input parameters: <user> <pwd> <GSM host> <GSM port>

Output: New groups are created in Hyperion Performance Suite.

Page 62: Hyperion 8.3 Developers Guide

4-8 Sample Java Programs

AddLink.javaUse this sample to add a link into the repository. The sample publishes a file in the specified folder and creates a link to the file in the root folder.

Input parameters: <user> <pwd> <host> <port> <path> <document>

Output: New links are created in Hyperion Performance Suite.

AddObjectType.javaUse this sample to show how to add a new metatype to Hyperion Performance Suite. The user needs administrator privileges to create the objects.

Input parameters: <user> <pwd> <host> <port> <mimetype> <filenameextension> <iconpath>

Output: New links are created in Hyperion Performance Suite.

AddOCEDocument.javaUse this sample to publish an Open Catalog Extension (OCE) file and to set some of its properties. The database user ID and password are optional. An OCE file is used by a BQY document or job for making a connection to a data source.

Input parameters: <user> <pwd> <GSM host> <GSM port> < Target Folder> <OCE Name> [<isPrompt> <dbUsername> <dbPassword>]

Output: OCE file is added to the target folder in Hyperion Performance Suite.

Page 63: Hyperion 8.3 Developers Guide

Samples 4-9

AddRole.javaUse this sample to add a role definition.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Role> <Role Description>

Output: New role is included in Hyperion Performance Suite system.

AddSPF.javaUse this sample to publish an SQR output collection, which includes all output produced by an SQR program (job). An output collection includes SPF files, which are Hyperion proprietary output, and other formats such as PDF and HTML.

Input parameters: <user> <pwd> <GSM host> <GSM port> <target Folder> <SPF File>

Output: A group of files (output collection) is published to the target folder in Hyperion Performance Suite.

Page 64: Hyperion 8.3 Developers Guide

4-10 Sample Java Programs

AddSubscription.javaUse this sample to add subscriptions for a user to a document category. A subscribed user will receive e-mail notifications on a document whenever it changes. The user needs administrator privileges to create the objects.

Input parameters: <user> <pwd> <host> <port> <subscribed_user> <path> [subscribed_user_email]

Output: A subscribed user will receive a notification e-mail whenever the document changes. Log on to the servlet as the same user who ran this sample program. Navigate to the object and look at its subscriptions. The corresponding check box should be selected.

Examples of the syntax:

java -classpath %CLASSPATH% AddSubscription administrator administrator localhost 1800 TESTSUBS1 D:\Test1.txt email@some_address.com

or

java -classpath %CLASSPATH% AddSubscription administrator administrator localhost 1800 TESTSUBS1 /TestDir1/TestObj email@some_address.com

AddUser.javaUse this sample to add a user to Hyperion Performance Suite. In addition it is possible to specify if the user being created has the administrator role or has the ability to execute jobs.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Username> <Password> <Allow Job Run - boolean> <Administrator Role - boolean>

Output: A user is created in Hyperion Performance Suite with or without the administrator role.

Page 65: Hyperion 8.3 Developers Guide

Samples 4-11

AddVersions.javaUse this sample to demonstrate version capability in Hyperion Performance Suite for documents. An existing version of the document to be published must exist in the system.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Hyperion Performance Suite Document (e.g. /Finance/Sales.doc)> <Local Document (e.g. c:\Sales2.doc)>

Output: A new version of an existing document is published.

AutoZip.javaUse this sample to show the use of autozip functionality. This program publishes a document in Hyperion Performance Suite along with a zipped version of the same document.

Input parameters: <user> <pwd> <GSM host> <GSM port> <Target Folder> <Document>

Output: A document and a zipped version of the same are published in Hyperion Performance Suite.

Page 66: Hyperion 8.3 Developers Guide

4-12 Sample Java Programs

BatchDriver.javaUse this sample to bulk load objects into Hyperion Performance Suite and to modify assessors of existing objects. You can bulk load the following objects using this sample program:

■ Groups

■ Users

■ Folders

■ Documents

■ OCEs

■ BQY documents

BatchDriver.java reads a control file that contains control statements describing objects that are created in the repository. For more information on the control file and the control statements used for this sample, see “Batch Driver Sample Program Control File” on page 3-1. A sample control file, batch_driver.cf is located at Install_Home\SDK\samples\java.

Input parameters: <user> <pwd> <host> <port> <Control file (for example, batch_driver.cf)>

Output: A batch load of one or more of the following objects: accessor, group, category, user, data, OCE Document, BQY Document.

An example of the syntax when you compile the program:

java -cp .;%classpath% BatchDriver administrator administrator venice 1800 TEST1 C:\Hyperion\Brio\batch_driver.cf

An example of the syntax when using the installed compiled version of the program:

java -cp .;%classpath% com.sqribe.rm.BatchDriver administrator administrator venice 1800 TEST1 C:\Hyperion\Brio\batch_driver.cf

CategoryDelete.javaUse this sample to delete an empty folder in Hyperion Performance Suite. If the folder to be deleted does not exist, a message is displayed.

Page 67: Hyperion 8.3 Developers Guide

Samples 4-13

Input parameters: <user> <pwd> <host> <port> <Folder (e.g. /Sales/West)>

Output: Named empty folder is deleted.

Page 68: Hyperion 8.3 Developers Guide

4-14 Sample Java Programs

ExecuteBQYDocument.javaUse this sample to show the use of execute pregeneration for BQY documents. This program is derived from the SampleBase class and makes heavy use of the getSymbol() method implemented in that class. Refer to SampleBase.java for information about how to pass attribute values to this and other classes derived from SampleBase.

*Input parameters: <user> <pwd> <GSM host> <GSM port> <BQY Doc Path> <Document>

Output: A document and a zipped version of the same are published in Hyperion Performance Suite.

An example of the syntax:

*java -classpath %CLASSPATH% ExecuteBQYDocument <user> <password> <host> <port> bqypath=/SampleSDK/Brio8.0_Sample1.bqy

ExecuteBQYJob.javaUse this sample to execute (or schedule) a BQY job. It is derived from the SampleBase class and makes use of the getSymbol() method implemented in that class. Refer to SampleBase.java for information about how to pass attribute values to this and other classes derived from SampleBase.

Input parameters: <user> <password> <host> <port> bqypath=/Folder /BQYJob (e.g. /SampleSDK/TestBQYjob)

Output: Job output from the BQY job. This will vary based on job run.

Page 69: Hyperion 8.3 Developers Guide

Samples 4-15

ExecuteSQRJob.javaUse this sample to load an SQR program into a target folder. After the program is loaded, it is executed once to create an output collection.

Input parameters: <user> <pwd> <host> <port> <Target Folder> <SQR program file (for example, Sales.sqr)>

Output: Published SQR program and the corresponding output collection for a single run.

ExpirationDate.javaUse this sample class to load and set an auto-deletion date for a Hyperion Performance Suite file. The file to be loaded for this sample should not be a BQY document or an SQR program.

Input parameters: <user> <pwd> <host> <port> <Folder> <File to be loaded>

Output: Published file set to auto-deletion after thirty days from the system date on which the program is run.

FetchCategory.javaUse this sample to obtain information about folder properties.

Input parameters: <user> <pwd> <host> <port> <Folder (for example, /Finance)>

Output: Output with folder name goes to the console.

Page 70: Hyperion 8.3 Developers Guide

4-16 Sample Java Programs

FetchDocument.javaUse this sample to obtain a file, for example, a DOC or TXT file from the repository. If multiple versions exist, all of them are extracted and stored on the local machine. The files have .0, .1,…,.n extensions added to the original name after the extraction.

Input parameters: <user> <pwd> <host> <port> <Folder> <DocName>

Output: One or more (if multiple versions exist) document objects.

ListEvents.javaUse this sample to list events defined in the Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port>

Output: Console listing of events in the system.

ListGroups.javaUse this sample to define a list of groups in the Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port>

Output: Console listing of groups in the system.

Page 71: Hyperion 8.3 Developers Guide

Samples 4-17

ListUsers.javaUse this sample to list all users defined in the Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port>

Output: Console listing of users in the system.

Login.javaUse this sample to establish and close connection with Hyperion Performance Suite system. It is recommended that you run this sample before running others. Running the sample ensures that the basic connection to the Hyperion Performance Suite system is established without any problems.

Input parameters: <user> <pwd> <host> <port>

Output: Messages “Connection Established” and “Connection closed.”

NestedGroups.javaUse this sample to assign a group as a member of another group in the Hyperion Performance Suite system. This is a variation of the AddGroups sample.

Input parameters: <user> <pwd> <host> <port>

Output: Two groups (GROUP1, GROUP2) created. GROUP1 is made a member of GROUP2.

Page 72: Hyperion 8.3 Developers Guide

4-18 Sample Java Programs

ObjectByPath.javaThis sample shows how to fetch a BaseObject from the repository using the full path object name. The object name passed as an argument must include the full path.

Input parameters: <user> <pwd> <host> <port> <object path>

Output: Some of the object properties are listed on the console

ObjectById.javaUse this sample to demonstrate fetching a BaseObject from the repository using the object ID passed as an argument. Object ID is unique to every object in the system and is used internally by Hyperion Performance Suite to access documents or folders in the system.

Input parameters: <user> <pwd> <host> <port> <object ID>

Output: Some of the object properties are listed on the console

PublishEvent.javaUse this sample to create or update an event in the Hyperion Performance Suite system. The sample control file, rte.cf, is included in the folder with the source program.

Input parameters: <user> <pwd> <host> <port> <Control File> (for example, rte.cf)

Output: Event named in the control file is created in Hyperion Performance Suite.

Page 73: Hyperion 8.3 Developers Guide

Samples 4-19

PublishOutputDirectory.javaUse this sample to define an output directory in Hyperion Performance Suite. You can run this sample in two ways. The input parameters section shows the two available options. The sample control file, outdir.cf, is included in the folder with the source program.

Input parameters: Option I: <user> <pwd> <host> <port> name=OutputDir1 dirname="C:\BPS\OutDir"

Option II: <user> <pwd> <host> <port> <Control File, e.g. outdir.cf>

Output: Named directory is created in Hyperion Performance Suite.

PublishPrinterResource.javaUse this sample to define a printer resource in Hyperion Performance Suite. You can use this sample in two different ways. The input parameters section shows the two available options. The sample control file, printer.cf, is included in the folder with the source program.

Input parameters: Option I: <user> <pwd> <host> <port> name=myPrinter1 pname="HP LaserJet"

Option II: <user> <pwd> <host> <port> <Control File printer.cf>

Output: Named event is created in Hyperion Performance Suite.

QueryGroup.javaThis sample shows how to query group members of a group in the Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port> <group>

Output: Shows members of the group being queried.

Page 74: Hyperion 8.3 Developers Guide

4-20 Sample Java Programs

QueryUser.javaUse this sample to query user properties in Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port> <user>

Output: Shows user properties on the console.

ReplaceObject.javaUse this sample to replace the contents of the specified object in Hyperion Performance Suite system.

Input parameters: <user> <pwd> <host> <port> <user> <Folder> <Document>

Output: Replaces the original document with a new copy.

SQRParms.javaUse this sample to obtain the parameters and their type, with the specified SQR job.

Input parameters: <user> <pwd> <host> <port> <user> <SQR Job UUID>

Output: Shows SQR Job parameters and their properties on the console.

Page 75: Hyperion 8.3 Developers Guide

Attributes and Supporting Classes 4-21

Attributes and Supporting ClassesMost of the sample API programs that are provided include the following common attributes:

■ Command line arguments

■ Opening and processing data lines read from a data file

■ Look up of Hyperion Performance Suite folder, account, and group objects

These example programs take advantage of object-oriented programming techniques by extending the base class that implements a set of common functions. The following list contains supporting classes:

■ AddBQYBase.java

■ SampleBase.java

■ SampleUtilities.java

Page 76: Hyperion 8.3 Developers Guide

4-22 Sample Java Programs

Page 77: Hyperion 8.3 Developers Guide

P A R T I I

IICustomization

Page 78: Hyperion 8.3 Developers Guide
Page 79: Hyperion 8.3 Developers Guide

5 HTML Templates

This chapter explains how to modify the Hyperion Performance Suite HTML templates and how to add custom HTML templates. A reference table of template names and descriptions and a description of Hyperion Foundation cascading style sheets are also included in this chapter.

Note This section on custom templates is offered to meet your customization needs. However, customizing templates is considered nonstandard and Hyperion is unable to support them.

In This Chapter Customizing Hyperion Foundation Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2

Template Names and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-6

Modifying a Template: An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-14

Cascading Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-15

Page 80: Hyperion 8.3 Developers Guide

5-2 HTML Templates

Customizing Hyperion Foundation TemplatesThe Hyperion Foundation servlets use JavaScript/HTML templates and Java Server Pages (JSP) to construct their Web pages. The following topics explain how to create custom versions of the templates, modifying the appearance and behavior of the servlets:

■ Preparing to Write Custom Templates

■ Editing and Testing Template Files

■ Importing the Contents of One Template into Another

■ Template Element Tags

■ Template Elements

■ Caveats

For more information on JSP pages, see Chapter 6, “Java Server Pages.”

Preparing to Write Custom TemplatesBefore attempting to write a custom template, read this section, “Customizing Hyperion Foundation Templates,” in its entirety. Also learn the basics of HTML and JavaScript. The following are requirements for starting template customization:

■ Familiarity with the product template elements

■ Knowledge of HTML and JavaScript

■ An HTML editor that does not alter the code

Disabling the template cache enables you to see your template changes quickly as you test and edit your templates.

To disable the template cache

1 Start the Servlet Configurator.

2 Select Properties→Cache→Templates.

3 In the right hand frame, turn off Cache parsed HTML templates.

4 Save your changes.

Page 81: Hyperion 8.3 Developers Guide

Customizing Hyperion Foundation Templates 5-3

5 Restart the servlets.

Note Disabling the caching of templates is a convenience for testing. It enables you to see the effects of your template modifications without restarting the servlet. However, after you complete testing, you should re-enable Cache parsed HTML templates for better system performance.

Page 82: Hyperion 8.3 Developers Guide

5-4 HTML Templates

Editing and Testing Template FilesBe sure to edit copies of the standard templates, keeping the original versions in case you want to refer to or revert to them.

Note To edit templates, use an HTML editor that does not alter the code you enter. (Macromedia HomeSite is a safe editor. FrontPage 2000 is good if you understand how to keep groups of tags together. Notepad is sufficient for light editing.)

A template file contains:

■ HTML/JavaScript

■ Hyperion Foundation template elements (these elements follow syntax rules borrowed from XML)

When you add a new template, you must restart the affected servlet in order to test the template. If you only modify a template that already existed when the servlet was started, you can test modifications by choosing your browser’s Refresh or Reload button, assuming Cache parsed HTML templates is disabled.

Importing the Contents of One Template into AnotherThe Hyperion Foundation servlets support an import element that allows one template to import the contents of another. By convention, import files have an .imp extension. To import a file, use the following element:

<WS:Import file=”filename.imp"/>

Page 83: Hyperion 8.3 Developers Guide

Customizing Hyperion Foundation Templates 5-5

The import element works very well with inheritance and has other important benefits:

■ Redundancy is avoided where two servlet pages need to implement the same function.

For example, item.imp is a file used to display the listing information for any item (job, document, or report). This file is imported by the templates that generate the different listing pages.(For example, browseList.htm, favoriteCategoryList.htm, and so on.)

■ Reduced size of the templates stored in memory due to reduced redundancy.

■ Easier customization because of reduction of the template file granularity.

Template Element TagsAs in XML, Hyperion Foundation templates delimit elements in angle brackets. An element has a start tag and an end tag. When the element does not span other code, Hyperion Foundation uses a start-end tag. The syntax of these tag types is as follows:

■ Start tag – Has the form <WS:XXX>

Enclosed within the angle brackets are:

❑ Domain, which is set to WS

❑ ElementName

❑ Parameter followed by an equal sign (=) and a value enclosed in quotation marks; for example, hasvalue="yes". Note that multiple parameters can follow an element name.

For example, <WS:JobRunCond hasValue="yes">

■ End tag – Has the form </WS:XXX>

For example, </WS:JobRunCond>

■ Start-end tag – Has the form <WS:XXX/>

For example, <WS:JobName/>

Page 84: Hyperion 8.3 Developers Guide

5-6 HTML Templates

Template ElementsHyperion Foundation provides three types of template elements:

■ Basic (start-end) – Has the form: <WS:XXX param="yyy"/>

■ Conditional – Has the form:

<WS:XXXCond hasValue="yes"> more elements (Only processed if the condition evaluates

to true.) </WS:XXXCond> or<WS:XXXCond hasValue="no">

more elements (Only processed if the condition evaluates to false.)

</WS:XXXCond>

You can use a conditional element to construct an if or an if-then-else statement.

■ Loop – Has the form:

<WS:XXXLoop param="yyy">

more elements (processed until the loop evaluates to false)</WS:XXXLoop>

CaveatsNote the following when you customize Hyperion Foundation templates:

■ Not all elements can be used in all templates.

■ Adding custom template sets may increase the memory requirements for the servlets, because all parsed Hyperion Foundation templates can be cached.

Template Names and Descriptions Table 5-1 describes the Hyperion Foundation JavaScript templates.

Page 85: Hyperion 8.3 Developers Guide

Template Names and Descriptions 5-7

Table 5-1 Templates Used by Hyperion Foundation Servlets

Template Name Description

adminCategory.scp Content window that displays links to objects within one of the pre-configured folders under the Broadcast Messages folder.

appletObject.htm Displays applet accessed from folder listing page.

appletObject.imp Loads and displays applet.

appletObject.scp Displays applet as a content window on Personal Page.

backGroundJobCancel.htm After you cancel a background job, this page displays to confirm that the job is no longer running.

backGroundJobConfirm.htm Used to draw the page that confirms that a job has been configured to run in background mode. This page also indicates where to place the job’s output.

backgroundJobs.htm Used to list all the background jobs that are currently running. This page also enables you to cancel jobs.

backgroundJobsEmpty.htm If no background jobs are currently running, this file is used to present a page that informs the user that there are no jobs running in background mode.

bgjStartDatePrint.imp When listing background jobs, like in “BackgroundJobs.htm”, this import is used to format the start dates of each job.

bookmarks.scp Content window that displays bookmarks to Hyperion Performance Suite content and Web sites.

bqyJavaScript.imp JavaScript include file for BQY job and document personalization.

bqyObject.scp Render BQY job or document SCP within a Personal Page.

bqyObjectEdit.scp Render edit button options for BQY job and document.

brioPortalExceptionsDashboard.scp Content window that displays monitored exceptions.

brioPortalGraphicBookmark.scp Content window that displays an image bookmark – i.e. graphic bookmark to Hyperion Performance Suite content.

broadcastMsgCategory.scp Content window that displays links to non-embedded content of the Broadcast Messages folder.

browseIndex.htm Frameset for pages in Browse tab.

browseList.htm Right hand frame in Browse tab.

Page 86: Hyperion 8.3 Developers Guide

5-8 HTML Templates

browseNav.htm Navigation frame (on left) for Browse tab.

JavaScript Edition: Provides highlighting of folder entries as mouse moves over entry. Also provides better navigation when folder is selected – only LHS frame and RHS frame is updated, rather than entire frameset.

categoryScp.imp Displays items for content windows of folders-- Broadcast Messages folder, and administrative folders (subfolders of Broadcast Messages).

changeColor.imp JavaScript color functions.

delayedRedirectToCaller.imp The basic edition does nothing.

JavaScript Edition: Redirects the importing page to the CALLER after waiting a few seconds. For example, when you submit a background job, a page displays to confirm the job has been submitted. The “submit conformation page” only displays for a number of seconds before automatically redirecting to the browse page. DelayedRedirectToCaller is responsible for the redirect.

deleteParameterListsResults.htm Page showing the results of attempting to delete one or more Parameter Lists, including any Schedules that were deleted as a result.

deleteSchedulesResults.htm Page showing the results of delete one or more Schedules.

descrip.htm Framework support. Displays a message about browser feature support.

displayPreferences.imp Displays the display preferences controls, such as show multiple versions, sorting, and so on.

editBookmarks.scp Enables editing of the set of bookmarks.

editBrioPortalExceptionsDashboard.scp Enables editing of the properties of the Exceptions Dashboard content window.

editGraphicBookmark.scp Enables editing of an Internet Image Bookmark.

embeddedObject.scp Content window for display of embedded content.

error.htm Used to display an error message.

favoriteCategoryList.htm Right hand frame in Personal Pages for displaying Favorite Folder Listing.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 87: Hyperion 8.3 Developers Guide

Template Names and Descriptions 5-9

favoriteItemsList.htm Right hand frame in Personal Pages for displaying Favorite Items Listing.

graphicBookmark.scp Content window that displays Internet Image Bookmark.

graphicBookmarkJavaScript.imp JavaScript functions that validate the create/edit Internet Image bookmark input.

graphicBookmarkJavaScriptUtil.imp JavaScript functions that validate size settings for Image bookmark.

groupAccess.imp Interface for restricting access to published items based on group.

item.imp Displays one item – its name, description and any version information associated with it. Referenced by the *List.htm templates.

itemsList.htm Used to display result of running non-Brio job or SQR Program, if there are multiple outputs and there is no one default for which output should be displayed.

jcnBgMessage.imp Constructs the job completion notification message for background jobs.

jcnEndDatePrint.imp Formats the job completion notification end date.

jcnSchMessage.imp Constructs the job completion notification message for scheduled jobs.

jcnStartDatePrint.imp Formats the job completion notification start date.

list.htm Displays result of SmartCut ‘list’.

listAll.htm Displays result of SmartCut ‘listAll’.

JavaScript Edition: Provides highlighting of folder entries as mouse moves over entry.

listIndex.htm Displays result of SmartCut ‘listIndex’.

listNav.htm Display result of SmartCut ‘listNav’.

JavaScript Edition: Provides highlighting of folder entries as mouse moves over entry. Also provides better navigation when folder is selected – only LHS frame and RHS frame is updated, rather than entire frameset.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 88: Hyperion 8.3 Developers Guide

5-10 HTML Templates

login.htm Login page.

navbar.htm Displays the navigation bar used to display HTML files. (Displays each of the 5 tabs, a back button and an exit button).

navFrameset.htm Frameset for displaying the navbar.htm and the HTML file.

newGraphicBookmark.scp Page for creating an Internet Image Bookmark.

notificationsJcn.htm Presents the page that displays Job Completion Notifications. This page also provides the ability to delete selected notifications.

JavaScript Edition: In addition to the basic functionality, the Java-Script version provides an automated option to “select all notifications” for deletion.

odsItemLink.imp Deprecated. Provides hyperlink to ODS content. JavaScript version launches a separate window.

odsJavaScript.imp Deprecated. JavaScript for ODS integration.

odsZeroAdmin.imp Deprecated. For integration of ODS Zero Admin support.

outputMsg.imp Display a context-sensitive output message, usually as a result of user input.

parameterForm.htm Run a job that requires parameters or database information, create or edit a job parameter list.

parameterFormJavaScript.imp JavaScript support for parameterForm.htm.

parameterListNone.imp Displayed when there are no parameter lists.

parameterListReadonly.htm Displayed when a parameter list is read-only and cannot be edited by the user.

parameterListSubmit.imp Used to submit a parameter list. (Defined Form action)

JavaScript Edition: Provides JavaScript functions that perform some form validation. Specifically, if the parameter list is used in the context of running a job and database login info is required, validates that this information is supplied. If the parameter list is used in the context of scheduling, validates that a parameter list name is supplied.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 89: Hyperion 8.3 Developers Guide

Template Names and Descriptions 5-11

parameterList.htm Standard template for displaying job parameters when there is no associated parameter form. This is used both when running a job and when creating/editing parameter lists (when scheduling a job).

parameterListSelection.imp

parametersReadonly.imp Displays a read-only table of the parameters in a Parameter List.

paramLists.htm Displays parameter lists and schedules for a job.

paramListsDisplay.imp Displays parameter lists associated with a job.

parentRedirect.htm Redirects the URL to the parent frame. (This is used in cases where it is not known whether a URL should display in the parent frame. For example, the link to run a job uses this if the output returns an HTML file.

JavaScript Edition: Does the redirect automatically.

personalIndex.htm Frameset for Personal Pages.

personalNav.htm Navigation frame (on left) for Personal Pages.

JavaScript Edition: Provides highlighting of entries in left frame as mouse moves over entry. Also provides better navigation when entry is selected – only LHS frame and RHS frame is updated, rather than entire frameset.

prefsBrowserType.htm Page allowing users to select the set of templates to use.

prefsEmail.htm Page allowing the user to specify a default e-mail address for subscription/scheduling notifications.

prefsFavCategory.htm List of user’s Favorite Folders.

prefsFavItem.htm List of user’s Favorite Items.

prefsHighlightDuration.htm Page allowing the user to specify the criteria for highlighting an item as new or updated.

prefsIndex.htm Frameset for pages in Preferences tab.

prefsList.imp Defines the common format for displaying Personal Preferences items (for example, Favorite Items, Favorite Folders, and so on)

prefsMaxVersions.htm Page allowing users to specify the maximum number of versions of an item to display on their listing pages.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 90: Hyperion 8.3 Developers Guide

5-12 HTML Templates

prefsNav.htm Navigation frame (on left) for Preferences tab.

prefsPassword.htm Page allowing users to change their password.

prefsSubscribeCategory.htm List of user’s folder subscriptions.

prefsSubscribeItem.htm List of user’s item and job output subscriptions.

rollover.imp Basic version does nothing.

JavaScript edition: Provides JavaScript functions to give a roll-over/highlighting effect as a user moves the mouse over an entry.

scheduleIndex.htm Frameset for pages in Schedule tab.

scheduleNav.htm Navigation frame (on left) for Schedule tab.

scheduleTop.htm Top frame for Schedule tab.

scheduledJobListing.htm Page listing jobs that have associated Schedules.

schedulesLists.htm Page displaying Scheduling information for a particular job.

scp.imp Heading for a content window.

scpBroadcast.imp Heading for the Broadcast Messages content window.

search.htm Page displaying detailed Search options.

searchIndex.htm Frameset for pages in Search tab.

searchNav.htm Navigation frame (on left) for Search tab.

searchResultsList.htm Page displaying results of a Search.

smartCut.htm

smartpage.htm Personal Page.

smartpageAdd.htm Page that enables users to choose whether to copy a published Personal Page or create a new one.

smartpageAddExisting.htm Page that enables users to choose from a list of published Personal Pages to add to their own Personal Page collection.

smartPageColumn.imp Displays content windows for a particular column of a Personal Page.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 91: Hyperion 8.3 Developers Guide

Template Names and Descriptions 5-13

smartPageContent.htm Page for modifying content of a Personal Page.

smartPageContentLayout.htm Page for modifying the layout of content windows on a Personal Page

smartPageContentPortal-Options.imp Items that appear in top box on lefthand side of Personal Page.

smartPageCustomizeColors.htm Page that allows customization of colors for a Personal Page.

smartPageEdit.htm Page for editing Personal Pages color properties.

smartPageJavaScript.imp Common JavaScript routines used by Personal Pages. Basic version does nothing.

smartPageLayoutSelect.htm Page that allows selection of layout style (one-column, two-column, and so on) for a Personal Page.

smartPagePublish.htm Page that allows publishers to replace a published Personal Page or publish a new one.

smartpages.htm Displays list of Personal Pages in the user’s Personal Page collection.

smartPageToolbar.imp Toolbar that allows modification of Personal Page (Content, Layout, and so on).

spCategory.htm Page that allows users to update their personalization settings for a specific folder.

spGraphicSelection.imp Provides image selection options on pages for creating/editing Image bookmarks.

spItem.htm Page that allows users to update their personalization settings for a specific item or job.

spSmartPages.imp Personal Pages section of Subscribe page.

spSubRestrict.imp Section of Subscribe/Personalize page for restricting subscriptions to high-priority items or exception items.

updateInternetBookmark.scp Page for creating/editing a specific Internet Bookmark.

updateSchedule.htm Page that allows users to create or edit a Schedule.

util.imp Some common JavaScript functions.

welcome.htm Used to construct the Welcome page, which requests the user’s template type.

Table 5-1 Templates Used by Hyperion Foundation Servlets (Continued)

Template Name Description

Page 92: Hyperion 8.3 Developers Guide

5-14 HTML Templates

Modifying a Template: An ExampleThe example in this section illustrates the process of customizing a template.

In this example, you customize a Browse servlet template, removing the Search bar that appears at the bottom of item lists:

i

F igure 5-1 An Item List, Before Customization

To remove the Search bar from item lists in the Browse module:

1 Save a backup copy of the original browseList.htm template.

2 In Notepad, open the copy of browseList.htm you want to modify.

3 Search for the element <WS:AllowSearchCond hasValue="yes"> in this template.

4 Delete the code between the elements <WS:AllowSearchCond hasValue="yes"> and </WS:AllowSearchCond>.

5 Save your changes.

To test the changes:

1 Stop and restart the Browse servlet.

2 To see the results of the customization, log into the Browse servlet (even if you are already logged in).

Page 93: Hyperion 8.3 Developers Guide

Cascading Style Sheets 5-15

The displayed item list should lack the Search bar, as in Figure 5-2.

F igure 5-2 An Item List, After Search Bar is Removed

Cascading Style SheetsThe colors, fonts, backgrounds, and general appearance of pages used by the Hyperion Performance Suite are determined by cascading style sheets located in \Install_Home\servlets\deployment\css. All the Hyperion Performance suite servlets use the same three cascading style sheets, application.css (the main style sheet), globalNav.css, and horzNav.css, except the iHTML servlet which uses these additional cascading style sheets, limit.css, limitNS.css, and tc.css.

ViewApplicationCSS.html shows the look and feel of application.css.

Page 94: Hyperion 8.3 Developers Guide

5-16 HTML Templates

Page 95: Hyperion 8.3 Developers Guide

6 Java Server Pages

Hyperion Performance Suite uses Java Server Pages (JSP) and HTML templates to create the user interface. This chapter concentrates on the JSP pages used to create specific pages in Hyperion Performance Suite.

Note Customizing JSP pages should only be done by developers with JSP and Java programming experience. Custom JSP pages are not supported by Hyperion customer support.

In This Chapter JSP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2

JSP Pages Identified by User Tasks

Viewing Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4

Modifying File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-8

Creating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-14

Scheduling Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-20

Page 96: Hyperion 8.3 Developers Guide

6-2 Java Server Pages

JSP DirectoryHyperion Performance Suite uses about one thousand JSP pages. . All the Hyperion Foundation JSP pages are located in the /Install_Home/servlets/deployment/jsps directory. This directory is divided into the following subdirectories:

■ administrator

■ browser

■ dashboard

■ dataaccess

■ iHTMLServlet

■ personalpage

■ scheduler

■ shared

Administrator DirectoryThis directory includes all the JSP pages using in the Administration module. The Administration module is a web-based administrator’s tool in which the administrator can configure many system properties, administrator’s preferences, and the properties for usage tracking.

Browser DirectoryThis directory includes all the JSP pages used in the Browse module. The Browse module is used for browsing, viewing, and publishing content, and for running jobs. Subdirectories in the browse directory contain the JSP pages for browse preferences (which allows users to customize the Browse module), running BQY jobs, and running generic jobs. The JSP pages for access control are in the shared directory.

Dashboard DirectoryThis directory includes all the JSP pages that make-up the View Manager module. The View Manager module is used for viewing and managing all dashboards and pushed items.

Page 97: Hyperion 8.3 Developers Guide

JSP Directory 6-3

Dataaccess DirectoryThis directory contains the jsp pages used by the data access servlet.

IHTMLServlet DirectoryThis directory includes all the JSP pages used by the Intelligence iServer.

PersonalPage DirectoryThis directory contains the personalTop.jsp which is used for the top frame of all Personal Pages.

Scheduler DirectoryThis directory includes all the JSP pages that make-up the Job Manager module. The Job Manager is used for managing scheduled jobs and for creating and managing events.

Shared DirectoryThis directory includes most of the JSP pages that are used by more than one module. This includes all the JSP pages used by the access control user interface, the widgets, the wizards, and the top and bottom frames. The following JSP pages are examples of the JSP pages in this directory:

■ hiddenWidget.jsp

■ widgetBeginBorder.jsp

■ widgetEndBorder.jsp

■ setTimeZoneOffset.jsp

■ tooltipsHandler.jsp

■ statusMessage.jsp

Page 98: Hyperion 8.3 Developers Guide

6-4 Java Server Pages

JSP Pages Identified by User TasksIn an attempt to show which JSP pages go with which user interface pages in Hyperion Performance Suite, we have decided to start by identifying the main JSP pages for the user interface of the following four most common user tasks:

■ Viewing Documents

■ Modifying File Properties

■ Creating Events

■ Scheduling Jobs

The following information is provided for each user task:

■ Flow chart – Shows the user interface pages used for the most common way to complete this task.

■ Figure – A complete graphic of each page from the flow chart showing which JSP pages control the page.

■ Table – List of the main JSP pages and their paths for the graphic shown.

The JSP pages for the user interface pages for the following user task flows are detailed in this chapter:

Viewing DocumentsThis task involves logging onto the Hyperion Performance Suite system and browsing the repository for the item to be viewed.

Figure 6-1 shows which user interface pages are involved in this user task.

F igure 6-1 Viewing a Document Task Flow

Login Page

AdvancedLogin Page

BrowseListing Page

Page 99: Hyperion 8.3 Developers Guide

Viewing Documents 6-5

The pages are described in the following topics:

■ Login Page

■ Advanced Login Page

■ Browse Listing Page

Login PageFigure 6-2 shows the login page with its associated JSP pages.

F igure 6-2 Login Page

Table 6-1 JSP Pages for Login and Advanced Login Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/shared/login.jsp

/jsp/shared/helpMenu.inc

/jsp/shared/exitMenu.inc

/jsp/shared/helpMenu.inc

/login.jsp

helpMenu.inc

Page 100: Hyperion 8.3 Developers Guide

6-6 Java Server Pages

The login page contains scriptlets to determine what login configuration is set for the Hyperion Performance Suite installation, i.e., $CUSTOM_USER$, $CUSTOM_PASSWORD$ etc.

The help link is context sensitive. The login help URL is passed to the help.inc file.

Advanced Login PageFigure 6-3 and Table 6-1 show JSP page details for the advanced login page.

F igure 6-3 Advanced Login Page

Browse Listing PageFigure 6-4 and Table 6-2 show JSP page details for the Browse listing page.

Page 101: Hyperion 8.3 Developers Guide

Viewing Documents 6-7

F igure 6-4 Browse Listing Page

The browse, search, and preference tabs are implemented in browseTop.jsp. Scriptlets are used to check if a tab is selected or not.

Help and Exit URLs are formed using generic user interface components which uses specific URLs passed into the help and exit include files. Each servlet application within Hyperion Performance Suite has a distinct URL associated with Help.

Table 6-2 Browse Listing Page

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/browseTop.jsp /jsp/browser/launchApp.jsp

/jsp/shared/helpExitMenu.inc

/jsp/browser/extBrowseNav.jsp

/jsp/browser/extBrowseNavContent.jsp

/jsp/browser/browseListMenu.jsp

/jsp/browser/displayPreferences.jsp

displayPreferences.jspbrowseListMenu.jspbrowseList.htm

item.imp

browseTop.jsp

extBrowseNav.jspextBrowseNavContent.jsp

browseNav.htm

launchApp.jsp

Page 102: Hyperion 8.3 Developers Guide

6-8 Java Server Pages

The standard navigation frame uses template files. The template uses tokens, which are parsed by the foundation and replaced with the values in the response stream to the Web browser. Most of the customization is based on ws.conf setting, which is set by Servlet Configurator

Modifying File PropertiesThis task involves logging onto the Hyperion Performance Suite system, browsing the repository for the item in which the properties need to be modified, and modifying the properties.

Figure 6-5 shows which user interface pages are involved in this user task.

F igure 6-5 Modify File Properties Task Flow

The pages are described in the following topics:

■ Login Page

■ Advanced Login Page

■ Browse Listing Page

■ Modify File Properties Page

■ Modify BQY Document Properties Page (for BQY documents only)

Login Page

AdvancedLogin Page

BrowseListing Page

Modify FileProperties

Page

Modify BQYDocumentProperties

Page

Page 103: Hyperion 8.3 Developers Guide

Modifying File Properties 6-9

Modify File Properties PageThe modify file properties page is composed of the four widgets which are described in the following topics:

■ General Widget

■ Advanced Options Widget

■ Access Control Widget

■ Version Widget

General WidgetFigure 6-6 and Table 6-3 show JSP page details for the general widget.

F igure 6-6 General Widget JSP Pages

Table 6-3 General Widget JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/fileGeneralWidget.jsp

/jsp/browser/setName.jsp

/jsp/browser/setDescription.jsp

/jsp/browser/owner.jsp

/jsp/browser/size.jsp

/jsp/browser/smartcut.jsp

fileGeneralWidget.jsp

setName.jsp

setDescription.jsp

owner.jsp

size.jsp

smartcut.jsp

Page 104: Hyperion 8.3 Developers Guide

6-10 Java Server Pages

Advanced Options WidgetFigure 6-7 and Table 6-4 show JSP page details for the advanced options widget.

F igure 6-7 Advanced Options Widget JSP Pages

/ Table 6-4 Advanced Options Widget JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/fileAdvOptionsWidget.jsp

/jsp/browser/mimeTypes.jsp

/jsp/browser/filePriority.jsp

/jsp/browser/charEncoding.jsp

/jsp/browser/setViewManager.jsp

/jsp/browser/hiddenItem.jsp

/jsp/browser/autoDelete.jsp

/jsp/browser/allowExceptions.jsp

/jsp/browser/setAutoKeywords.jsp

/jsp/browser/assignKeywords.jsp

mimetypes.jsp

fileAdvOptionsWidget.jsp

charEncoding.jspsetViewManager.jsp

hiddenItem.jspautoDelete.jsp

allowExceptions.jspsetAutoGenKeywords.jsp

assignKeywords.jsp

Page 105: Hyperion 8.3 Developers Guide

Modifying File Properties 6-11

File priority is displayed on this widget when turned on by the administrator.

Access Control WidgetFigure 6-8 and Table 6-5 show JSP page details for the access control widget.

F igure 6-8 Access Control Widget JSP Pages

Table 6-5 Access Control Widget JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/shared/accessControlWidget.jsp

/jsp/shared/accessControlJobWidget.jsp

/jsp/shared/accessControlGeneralWidget.jsp

/jsp/shared/accessControlACLWidget.jsp

/jsp/shared/chooseAccessors.jsp

/jsp/shared/chooseAccessorsWidget.jsp

accessControlWidget.jsp

Page 106: Hyperion 8.3 Developers Guide

6-12 Java Server Pages

Version WidgetFigure 6-9 and Table 6-6 show JSP page details for the version widget.

F igure 6-9 Version Widget JSP Pages

Table 6-6 Version Widget JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/fileVersionsWidget.jsp

/jsp/browser/fileAddVersion.jsp

/jsp/browser/version.jsp

/jsp/browser/fileEditVersion.jsp

/jsp/browser/version.jsp

fileEditVersion.jsp

fileAddVersion.jsp

fileVersionsWidget.jsp

Page 107: Hyperion 8.3 Developers Guide

Modifying File Properties 6-13

OCE File WidgetsFigure 6-10 and Table 6-7 show JSP page details for OCE file widgets.

F igure 6-10 OCE File Widget JSP Pages

Table 6-7 OCE File Widget JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/fileOCEOptionsWidget.jsp

/jsp/browser/passThrough.jsp

/jsp/browser/fileMetaOCELinkWidget.jsp

fileOCEOptionsWidget.jsp

passThrough.jsp

FileMetaOCELinkWidget.jsp

Page 108: Hyperion 8.3 Developers Guide

6-14 Java Server Pages

Modify BQY Document Properties PageBQY documents use the basic property widgets and an additional BQY properties page, as shown in Figure 6-11.

Figure 6-11 and Table 6-8 show JSP page details for the additional BQY document properties page.

F igure 6-11 Modifying BQY Document Properties Page

Creating EventsThis task involves navigating to the manage events page in the Job Manager and going through either the recurring events wizard or the triggered events wizard to create a new event.

Figure 6-12 shows which user interface pages are involved in this user task:

Table 6-8 BQY Document Properties JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/browser/editFileBQY.jsp

/jsp/browser/BQYQueryWidget.jsp

/jsp/browser/fileThinClientWidget.jsp

Page 109: Hyperion 8.3 Developers Guide

Creating Events 6-15

F igure 6-12 Create an Event Task Flow

The pages are described in the following topics:

■ Manage Jobs Page

■ Manage Events Page

■ Create Recurring Event Page

■ Create Externally Triggered Event Page

ManageEvents Page

CreateExternallyTriggered

Event Page

CreateRecurring

Event Page

ManageJobs Page

Page 110: Hyperion 8.3 Developers Guide

6-16 Java Server Pages

Manage Jobs PageFigure 6-13 shows the Login Page with its associated JSP pages. Table 6-9 details the JSP pages for the manage jobs page.

F igure 6-13 Manager Jobs Page

Table 6-9 Manage Jobs Page JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/scheduler/sched-Nav.jsp

/jsp/sched-uler/listSchedules.jsp

/jsp/scheduler/listScheduledJobs.jsp

/jsp/scheduler/sched-Top.jsp

schedNav.jsp

listSchedulerJobs.jsp

schedTop.jsp

Page 111: Hyperion 8.3 Developers Guide

Creating Events 6-17

Manage Events PageFigure 6-14 shows the Mange Events Page with its associated JSP pages. Table 6-10 details the JSP pages for the manage events page.

F igure 6-14 Manage Events Page

The filters related part of this page is provided by the include file, /jsp/scheduler/events/eventFilter.inc. This include file is called by listEvents.jsp.

Table 6-10 Manage Events Page JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/sched-uler/events/listEvent-Header.jsp

/jsp/scheduler/events/listEvents.jsp

listEvents.jsp

listEventHeader.jsp

Page 112: Hyperion 8.3 Developers Guide

6-18 Java Server Pages

Create Recurring Event PageFigure 6-15 shows the Create Recurring Event Page with its associated JSP pages. Table 6-11 details the JSP pages for the this page.

F igure 6-15 Create Recurring Event Page

Table 6-11 Create Recurring Event Page JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/sched-uler/events/createPubli-cRTE.jsp

/jsp/scheduler/events/editEventGener-alWidget.jsp

/jsp/scheduler/events/editDaysToRunWidget.jsp

/jsp/scheduler/events/editTimeToRun.jsp

/jsp/scheduler/events/editDatesWidget.jsp

editEventGeneralWidget.jsp

editDaysToRunWidget.jsp

editTimeToRun.jsp

editDatesWidget.jsp

Page 113: Hyperion 8.3 Developers Guide

Creating Events 6-19

Days To RunThe Days to Run widget also uses the following JSP pages located in /jsp/scheduler/events/runsched:

■ By Day – day.jsp

■ By Week – week.jsp

■ By Period – period.jsp

■ By Quarter – quarter.jsp

■ By Year – year.jsp

■ Every – every.jsp

■ Advanced Days of Periods – advancedDaysOfPeriod.jsp

■ Advanced Days of Week – advancedDaysOfWeek.jsp

Time To RunThe Time to Run widget also uses the following JSP pages located in /jsp/scheduler/events/timetorun:

■ Once Per Day – once.jsp

■ More Than Once Per Day – every.jsp

■ After External Event – external.jsp

Page 114: Hyperion 8.3 Developers Guide

6-20 Java Server Pages

Create Externally Triggered Event PageFigure 6-16 shows the create Externally Triggered Event Page with its associated JSP pages. Table 6-12 details the JSP pages for the this page.

F igure 6-16 Externally Triggered Event Page

Scheduling JobsThis task involves navigating to the Job Manager module and creating a new schedule by using the scheduling wizard. All the pages listed in this task flow are in the scheduling wizard except the first page, the Scheduling Information page. BQY, SQR, and generic jobs require different pages for parameters (set values).

Figure 6-17 shows the user interface pages involved in this user task.

Table 6-12 Externally Triggered Event Page JSP Pages

Primary JSP Pages Associated Jsp Pages

/jsp/sched-uler/events/editXTE.jsp

/jsp/scheduler/events/editEventGener-alWidget.jsp

editXTE.jsp

editEventGeneralWidget.jsp

Page 115: Hyperion 8.3 Developers Guide

Scheduling Jobs 6-21

F igure 6-17 Scheduling a Job Task Flow

The pages are described in the following topics:

■ Scheduling Information Page

■ General Properties Page

■ Select Job Parameters (use Set Values page when using new parameters)

■ Set Values Page

■ When to Run Page

■ Notification Page

GeneralProperties

Page

Set ValuesPage

Select JobParameters

Page

NotificationPage

When toRun Page

SchedulingInformation

Page

Page 116: Hyperion 8.3 Developers Guide

6-22 Java Server Pages

Scheduling Information PageFigure 6-18 and Table 6-13 show JSP details for the scheduling information page.

F igure 6-18 Schedule Information Page

General Properties PageFigure 6-19 and Table 6-14 show JSP page details for the general properties page which includes the database connect string widget.

Table 6-13 Schedule Information JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/scheduler/listJobData.jsp

jsp/scheduler/listJobSchedule-Data.jsp

jsp/scheduler/listJobParameter-Data.jsp

listJobData.jsplistJobScheduleData.jsp

listJobParameterData.jsp

Page 117: Hyperion 8.3 Developers Guide

Scheduling Jobs 6-23

F igure 6-19 General Properties Page

Select Job ParametersFigure 6-20 and Table 6-15 show JSP page details for the select job parameters page.

Table 6-14 General Properties JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/scheduler/schedJobGeneral.jsp

/jsp/scheduler/wizardHeading.jsp

/jsp/scheduler/schedJobGeneralWidget.jsp

/jsp/scheduler/schedBQYDatabaseWidget.jsp

/jsp/scheduler/schedSQRDatabaseWidget.jsp

schedJobGeneral.jsp

schedJobGeneralWidget.jsp

schedBQYDatabaseWidget.jsp

schedSQRDatabaseWidget.jsp

wizardHeading.jsp

Page 118: Hyperion 8.3 Developers Guide

6-24 Java Server Pages

F igure 6-20 Select Parameters Page

Set Values PageThe user interface to set values for BQY, SQR, and generic jobs is specific to the type of job. For BQY jobs, see “BQY Jobs” on page 6-24, for SQR jobs, see “SQR Jobs” on page 6-28, and for generic jobs, see “Generic Jobs” on page 6-28.

BQY JobsThe BQY job parameter wizard contains the following widgets:

■ Cycles

■ Define Cycle Widget

■ Set Values Page

■ Process Options

■ Actions

CyclesFigure 6-16 and Table 6-17 show JSP page details for the cycles widget.

Table 6-15 Select Parameters JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/scheduler/schedJobSelParam.jsp

/jsp/scheduler/schedJobSelParam-Widget.jsp

Page 119: Hyperion 8.3 Developers Guide

Scheduling Jobs 6-25

Table 6-16 Cycles Widget

Multiple cycle and single cycle BQY jobs use different JSP.

Define Cycle WidgetFigure 6-21 and Table 6-18 show JSP page details for the define cycles widget.

Table 6-17 Cycles JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/scheduler/BQYJobParameterGeneral.jsp

/jsp/scheduler/BQYMultiCycleJobParameterGeneral.jsp

/jsp/scheduler/BQYSingleCycleJobParameterGeneral.jsp

Page 120: Hyperion 8.3 Developers Guide

6-26 Java Server Pages

F igure 6-21 Define Cycles Widget

Set ValuesFigure 6-22 and Table 6-19 show JSP page details for the set values widget.

Table 6-18 Define Cycles JSP Pages

Primary JSP Pages Associated JSP Pages and Include Files

/jsp/scheduler/editBQYCycleGeneral.jsp

/jsp/shared/BQYDefineCycleWid-get.jsp

/jsp/shared/bqylimits/job-Params.jsp

/jsp/shared/BQYProcessOptions-Widget

/jsp/shared/BQYActionWidget.jsp

/jsp/shared/accessControlWid-get.jsp

BQYDefineCycleWidget.jsp

BQYProcessOptionsWidget.jsp

BQYActionWidget.jsp

actionControlWidget.jsp

Page 121: Hyperion 8.3 Developers Guide

Scheduling Jobs 6-27

F igure 6-22 Set Values Widget

ActionsFigure 6-23 and Table 6-20 show JSP page details for the action widget.

Table 6-19 Set Values Page JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/shared/bqylimits/job-Params.jsp

jsp/shared/bqylimits/relation-alJobParams.jsp

/jsp/shared/bqylimits/mddJob-Params.jsp

Page 122: Hyperion 8.3 Developers Guide

6-28 Java Server Pages

F igure 6-23 Action Widget

The following JSP pages are called in editBQYActionWidget.jsp and are used by one of the five specific action pages: export, save document, print document, e-mail section, and e-mail document:

■ /jsp/shared/editBQYActionExportWidget.jsp

■ /jsp/shared/editBQYActionSaveWidget.jsp

■ /jsp/shared/editBQYActionPrintWidget.jsp

■ /jsp/shared/editBQYActionEmailWidget.jsp

■ /jsp/shared/editBQYActionEmailSectionWidget.jsp

SQR JobsTable 6-21 show JSP page details for the SQR job parameters wizard.

Generic Jobs Table 6-22 shows JSP page details for the generic job parameters wizard.

Table 6-20 Action Widget JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/scheduler/editBQYAc-tionGeneral.jsp

/jsp/shared/editBQYActionWid-get.jsp

Table 6-21 SQR Job Parameters Wizard JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/shared/SQRJobParameter-General.jsp

/jsp/shared/SQRJobParameters-Widget.jsp

/jsp/shared/saveJobParam.jsp

Page 123: Hyperion 8.3 Developers Guide

Scheduling Jobs 6-29

When to Run PageFigure 6-24 and Table 6-23 show JSP page details for when to run widget.

For the pages following the When To Run page, see “Creating Events” on page 6-14.

F igure 6-24 When To Run Page

Notification PageFigure 6-25 and Table 6-24 show JSP page details for the notification page.

Table 6-22 Generic Job Parameters Wizard JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/shared/GenericJobParame-terGeneral.jsp

/jsp/shared/SQRJobParameters-Widget.jsp

/jsp/shared/saveJobParam.jsp

Table 6-23 When To Run Jsp Pages

Primary JSP Pages Associated JSP Pages

/jsp/scheduler/schedJobSelEv-ent.jsp

/jsp/scheduler/schedJobSelEv-entWidget.jsp

/jsp/scheduler/schedJobNew-Event.jsp

/jsp/scheduler/schedJobNew-EventWidget.jsp

schedJobNewEvent.jsp

schedJobSelEvent.jsp

Page 124: Hyperion 8.3 Developers Guide

6-30 Java Server Pages

F igure 6-25 Notification Page

Table 6-24 Notification JSP Pages

Primary JSP Pages Associated JSP Pages

/jsp/scheduler/schedJob-Notify.jsp

/jsp/scheduler/schedJobNotifyBrioOne-Widget.jsp

/jsp/scheduler/schedJobNotifyEmail-Widget.jsp

/jsp/scheduler/schedSQRNotifyStore-Widget.jsp

schedJobNotifyEmailWidget.jsp

schedJobNotify.jsp

Page 125: Hyperion 8.3 Developers Guide

7 Customizing E-mail Notifications

This chapter shows how to configure and customize e-mail notifications. The Event Service is responsible for notifications to alert users of events that occur within the context of Hyperion Performance Suite.

Note You need the administrator role to configure properties in the Administration module.

In This Chapter Configuring E-mail Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2

Notification Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2

Template File Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3

Choosing HTML or Text Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4

Template File Replacement Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4

Properties in the notification.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-7

Images in HTML-Formatted E-mail Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-11

Page 126: Hyperion 8.3 Developers Guide

7-2 Customizing E-mail Notifications

Configuring E-mail NotificationsYou can configure the following e-mail properties using the system tab of the Administration module:

■ The outgoing e-mail server

■ The from e-mail account

■ Whether e-mail attachments are enabled; and if so, the maximum number of bytes allowed in an attachment

■ The duration to keep scheduled jobs and background jobs in the notification logs

Template files define the formats of e-mail notification messages. Each notification type has its own template file. Therefore, you can customize the e-mail notifications for each notification type.

During installation, default template files are installed. If you are satisfied with the default files, then there is no need to customize the e-mail notifications and you can skip this section.

Notification TypesHyperion Performance Suite supports the following types of e-mail notifications:

■ Item Notifications – End users use the Browse module to subscribe to a file (or item) in the Repository. Browse allows you to specify the e-mail address that is sent an e-mail notification when the item is modified.

Item e-mail notifications are sent when the item in the Repository is modified. For example, if a user stores a new version of a file in the Repository, an e-mail notification is sent to all the users who subscribed to the file.

■ Folder Notifications – End users use Browse to subscribe to Repository folders and optionally subfolders. Browse allows users to specify the e-mail address that will be sent an e-mail notification when an item has been added to or modified in a given folder or subfolder.

Page 127: Hyperion 8.3 Developers Guide

Template File Directory 7-3

■ Job Output Notifications – End users use Browse to subscribe to a program’s output. When the program is executed by the Job Service, an e-mail notification is sent to all users who have subscribed to the program’s output.

■ Scheduled Job Notifications – End users use Browse to subscribe to scheduled job notifications, which may announce any of the following:

❑ Scheduled job completed successfully

❑ Scheduled job failed

❑ Scheduled job is being retried

You can turn off scheduled job retry notifications for all users by setting the sched_retry_notifications Java property to false on the Event Service.

❑ FTP delivery of scheduled job’s output succeeded

❑ FTP delivery of scheduled job’s output failed

Template File DirectoryThe template files are located in the following directory of each server host:

Install_Home/BrioPlatform/lib/notification

The templates must be changed on the host of the Event Service. If you modify templates for job notifications, copy the modified templates to the same directory (Install_Home/BrioPlatform/lib/notification) on every machine hosting a Job Service.

Page 128: Hyperion 8.3 Developers Guide

7-4 Customizing E-mail Notifications

Choosing HTML or Text FormatThe notification.properties file (located inInstall_Home/lib/msgs) contains properties that specify the template file to use for each notification type. For example, here are the lines from notification.properties that specify the template files to be used for item notifications:

itemEmailFileHTML.string=item_email.htmlitemEmailFileText.string=item_email.txt

The setting of the -Ddisable_htmlemail property chooses between the HTML and text versions of the template. If -Ddisable_htmlemail is set to false, the Event Service uses item_email.html when it sends an item notification. This property is set in the startCommonServices.bat. For information on setting this property, see the Foundation Administrator’s Guide.

Template File Replacement TokensTemplate files define the format and content of e-mail notification messages. The template files can contain tokens that are replaced with runtime values, as well as other data. For example, HTML tags are typically placed in the HTML template files.

Replacement tokens are enclosed in less than (<) and greater than (>) signs and start with the string BRIO_TAG. Their values are dynamically replaced in e-mail notifications.

Table 7-1 lists the replacement tokens:

Table 7-1 Replacement Tokens

Token Description

<BRIO_TAG_USER> Specifies the name of the user who triggered the e-mail notification. This applies to item and folder e-mail notifications.

The notificationOriginator property in the notification.properties file provides a parameterized message that you can use to add text around the user name in the e-mail notification message.

Page 129: Hyperion 8.3 Developers Guide

Template File Replacement Tokens 7-5

<BRIO_TAG_DESC> Specifies the description that users specified when they created an item in the Repository. Users can also specify a description when they add a new version of a file in the Repository. When this occurs, this tag is replaced by the user’s description.

The notificationDescription property in the notification.properties file provides a parameterized message that you can use to add text around the users description in the e-mail notification message.

<BRIO_OBJECT_LINK> Specifies the SmartCut to the item that is the target of the e-mail notification.

For an item subscription, it would be the SmartCut to the file that was the target (for example, the file that had a new version created). For a program output subscription, it specifies the SmartCut to the program output.

<BRIO_OBJECT_FULLPATH> Specifies the full path of the item that triggered the e-mail notification.

This is useful within a template HTML file as a target rather than the SmartCut.

<BRIO_TAG_MODIFY_LINK> Specifies the SmartCut to the link to modify the subscription to the item that triggered the e-mail.

This is useful to allow a user to discontinue or modify the subscription.

<BRIO_TAG_MODIFY_MSG> Specifies text associated with changing a subscription. The notification.properties file specifies properties that are substituted for this replacement token. These properties are:

■ cancelItemSubscriptionSmartcut – Specifies text for changing an item subscription.

■ cancelCategorySubscriptionSmartcut – Specifies text for changing a folder subscription.

■ cancelProgramOutputSubscriptionSmartcut – Specifies text for changing a program output subscription.

Table 7-1 Replacement Tokens (Continued)

Token Description

Page 130: Hyperion 8.3 Developers Guide

7-6 Customizing E-mail Notifications

<BRIO_TAG_EXCEPTION_TITLE> Specifies a string to be used as the title for an exception message.

This replacement token is replaced with the exceptionMessage value in the notification.properties file.

<BRIO_TAG_EXCEPTION_MSG> This replacement token is replaced with the exception messages that are the result of a job’s execution in the Job Service.

<BRIO_TAG_RETRY_MSG> Specifies why a scheduled job is being retried.

The notification.properties file specifies properties that are substituted for this replacement token. This property is as follows:

■ scheduledJobRetry – An error has occurred and the job is being retried.

<BRIO_TAG_USER_DEFINED> Specifies the body component for e-mail notifications about the scheduled job.

<BRIO_TAG_NO_ATTACHMENT> Specifies why no attachment was attached to the e-mail notification. Typically, this is not put into the e-mail notification.

If an attachment was requested in the subscription and yet no attachment is attached, then this replacement token is used to let the user know why no attachment was applied.

The notification.properties file specifies properties that are substituted for this replacement token. These properties are as follows:

■ attachmentErrorUnknown – An unknown error has occurred.

■ attachmentTooBig – The size of the e-mail attachment is larger than the maximum set by the administrator.

■ attachmentNotAllowed – There was a permission violation and the attachment could not be attached.

■ attachmentsDisabled – The administrator has disabled e-mail attachments.

Table 7-1 Replacement Tokens (Continued)

Token Description

Page 131: Hyperion 8.3 Developers Guide

Properties in the notification.properties File 7-7

Properties in the notification.properties FileWhen Event Service starts, it reads the contents of the notification.properties file. This file contains messages that go into e-mail notifications, as well as other properties. Never delete a record from this file. The notification.properties file is located in:

Install_Home\BrioPlatform\lib\msgs

Each line in the notification.properties file is formatted as:

name=value

The name ends in either .string or .text. If the property name ends in .string, then the value is constant. Conversely, if the value contains a variable, then the property name ends with .text. Variables start with a left curly brace ‘{‘ and end with a right curly brace ‘}’. Variables have a number that starts with zero.

When the Event Service creates e-mail notification messages, it frequently replaces a replacement token (see Table 7-1) with the property value from the notification.properties file. Consider the following variable property value assignment in the notification.properties file:

NotificationOriginator.text={0} triggered email notification

With this definition, the <BRIO_TAG_USER> replacement token in an e-mail notification template file is replaced with the name of the user who triggered the e-mail notification, followed by the text triggered e-mail notification. If a user named bob triggers the e-mail notification, then the string reads: bob triggered e-mail notification.

Table 7-2 describes many of the properties in the notifications.properties file.

Page 132: Hyperion 8.3 Developers Guide

7-8 Customizing E-mail Notifications

Table 7-2 Notification.Properties

Property Description

attachmentsDisabled Specifies the text to insert into the e-mail notification when the attachment cannot be added because attachments are disabled for the domain. Editing the system properties using Administration module can enable e-mail attachments.

attachmentErrorUnknown Specifies the text to insert into the e-mail notification when adding an attachment to the e-mail fails for some unknown reason.

attachmentNotAllowed Specifies the text to insert into the e-mail notification when the attachment cannot be added due to an access violation. If you receive an access violation, check the item permissions.

attachmentTooBig Specifies the text to insert the e-mail notification when the attachment cannot be added because it is too big. Editing the system properties in the Administration module can set the maximum size of the e-mail attachment.

cancelCategorySubscriptionSmartcut Specifies the text to insert in the e-mail notification when specifying a smartcut to the folder subscription. The location of the {0} identifies when the smartcut to the subscription is placed.

CancelItemSubscriptionSmartcut Specifies the text to insert in the e-mail notification when specifying a smartcut to the item subscription. The location of the {0} identifies when the smartcut to the subscription is placed.

cancelProgramOutputSubscriptionSmartcut Specifies the text to insert in the e-mail notification when specifying a smartcut to a job output subscription. The location of the {0} identifies when the smartcut to the subscription is placed.

categorySubscriptionSubject Specifies the e-mail subject field when a folder subscription notification e-mail is sent. The string “{0}” is replaced with the item name.

Folder subscription e-mails are sent to users who have subscribed to a folder when a file or other interesting item is added to the folder.

To include a single quotation mark in the subject, enter two single quotation marks. For example, to produce the subject Information You’ve Subscribed To, enter as the value of this field: Information You’’ve Subscribed To.

charset Defines the character set used to encode the subject field for e-mail notifications.

exceptionMessage Defines the heading for exception information reported in the e-mail notification. This property is only used when sending e-mail notifications for items that have associated exception information.

Page 133: Hyperion 8.3 Developers Guide

Properties in the notification.properties File 7-9

htmlEmail Specifies whether e-mail notifications are in HTML or text format. If this property has a value of true, then e-mail notifications are in HTML.

itemSubscriptionSubject Specifies the e-mail subject field when an item subscription notification e-mail is sent. The string “{0}” is replaced with the item name.

Item subscription e-mails are sent to users who have subscribed to a Hyperion Foundation item when a new version of the file is published or its properties are changed.

To include a single quotation mark in the subject, enter two single quotation marks. For example, to produce the subject Information You’ve Subscribed To, enter as the value of this field: Information You’’ve Subscribed To.

notificationDescription Item subscription e-mail notifications contain the description that end users provided when they created a new version of a file. The string “{0}” is replaced with the file description associated with the new version.

notificationOriginator Specifies the user who triggered the e-mail notification. The string “{0}” is replaced with the user name.

Item and folder subscription e-mail notifications contain the user who triggered the e-mail notification in the e-mail body. The notificationOriginator property allows customized formatting. For example, the customer could change this value to:

notificationOriginator.text={0} triggered this email notification

With the above definition, the e-mail notification body will contain:

“bob triggered this e-mail notification”

if the Hyperion Performance Suite user “bob” triggered the notification.

jobOutputSubscriptionSubject Specifies the e-mail subject field when a job output subscription notification e-mail is sent. The string “{0}” is replaced with the job name.

Job output subscription e-mails are sent to users who have subscribed to a job, when new output of that job is published.

To include a single quotation mark in the subject, enter two single quotation marks. For example, to produce the subject Information You’ve Subscribed To, enter as the value of this field: Information You’’ve Subscribed To.

Table 7-2 Notification.Properties (Continued)

Property Description

Page 134: Hyperion 8.3 Developers Guide

7-10 Customizing E-mail Notifications

scheduledJobFailed Specifies the text to be placed in the e-mail notification when a scheduled job fails to run. The string {0} is replaced by the reason for the failure. The reason can be the text defined in scheduledJobFailedJobKilled or scheduledJobFailedUnknown properties, or it can be the text returned from the external program that was unsuccessfully executed.

scheduledJobFailedJobKilled When a scheduled job is killed and the user has requested e-mail notification, this text is used as the reason why the job failed.

scheduledJobFailedUnknown When a scheduled job fails for unknown reasons and e-mail notification was requested, this text is used as the reason why the job failed.

scheduledJobRetry Specifies the text of the e-mail message sent by the scheduler when it couldn't run the job for some reason and is attempting to retry the job again. This is sent when notifications were requested.

scheduledJobSubject Specifies the e-mail subject field when a scheduled job e-mail notification is sent. The string {0} is replaced with the schedule name and the string {1} is replaced with the job name.

This type of e-mail notification is sent when a scheduled job is executed and the person who scheduled the job checked the box for e-mail notification.

To include a single quotation mark in the subject, enter two single quotation marks. For example, to produce the subject Information You’ve Subscribed To, enter as the value of this field: Information You’’ve Subscribed To.

scheduledJobUnableToSched Specifies the text of the e-mail message that is sent by the scheduler when it couldn't run the job for some reason. This is sent if notifications were requested and all retries have been exhausted.

smartcut Allows additional text to be added with the SmartCut to the item. The {0} must be present in the string and identifies the location where the smartcut is placed.

unknownSmartcut String used when the smartcut cannot be determined.

viewScheduleSmartcut Specifies the text to be placed in the e-mail notification when a scheduled job is run. The user must request e-mail notification when scheduling the job to get this information. The location of the {0} identifies where the SmartCut to the schedule is placed.

Table 7-2 Notification.Properties (Continued)

Property Description

Page 135: Hyperion 8.3 Developers Guide

7-11

Images in HTML-Formatted E-mail NotificationsYou can place images, such as GIF or JPEG files, into HTML-formatted e-mail messages.

To place an image into an HTML-based e-mail message:

1 Add an HTML IMG tag to the desired HTML template file.

2 Put the image file into the image directory that corresponds to the given e-mail notification type.

The image files are placed in a subdirectory of:

Install_Home/BrioPlatform/lib/notification/images

Each notification type has its own subdirectory under the images directory.

As an example, assume you want to place an image called logo.gif into item e-mail notifications. To do this you would add the string:

<IMG SRC=logo.gif>

to the file:

Install_Home/BrioPlatform/lib/notification/item_email.html

and then store logo.gif in:

Install_Home/BrioPlatform/lib/notification/images/item

Page 136: Hyperion 8.3 Developers Guide

7-12 Customizing E-mail Notifications

Page 137: Hyperion 8.3 Developers Guide

8 SmartCuts

SmartCuts enable you to integrate Hyperion Performance Suite with your intranet and other web-based applications. This chapter provides information on the SmartCut commands as well as a few SmartCut examples.

In This Chapter About SmartCuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2

The get Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

The run Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-8

The list Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-10

The listNav Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-10

The listIndex Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-10

The listAll Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-11

SmartCut Variables for BQY Documents and Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-12

SmartCut Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-18

Page 138: Hyperion 8.3 Developers Guide

8-2 SmartCuts

About SmartCutsBy embedding SmartCuts in your applications, you enable users to view Hyperion Performance Suite content or run jobs from those applications.

■ Used within Hyperion Foundation items, SmartCuts enable report surfing, or hyperlinking directly between content of any type. For example, a white paper can link to a glossary document, or a sample code listing can link to a job that runs the code and returns output.

■ SmartCuts enable more complex output structures, such as drill-down reports, where users can choose down through levels of detail.

■ SmartCuts enable a user to send live links to documents to other users. When the recipient selects the URL, the SmartCut takes the user directly to the document, the job run form, or the report output. To use a URL this way, write it with the path to the document, form, or job and with any parameters the job requires.

■ SmartCuts can automatically log users into the Web modules. The optional fields user, pass, and server are used to pass the login information. For more information about this and other ways users can be automatically logged in, see the Foundation Administrator’s Guide.

Note You can close a Hyperion Foundation session opened with a SmartCut (without closing the browser) by appending /login to the end of the Browse module URL: http://database/Hyperion/browse.

For example, if the SmartCut in the address line is http://venice/Hyperion/browse/withnav_get/sales/Hyperion, replace everything after browse, with login. This URL, http://venice/Hyperion/browse/login, ends your current session and opens the Hyperion Performance Suite login screen.

Note When writing SmartCuts, keep in mind that Hyperion Performance Suite’s URLs are case sensitive and do not accept space characters. In place of a space, insert %20. Some example SmartCuts in this section illustrate this with the report name Sales Charts referenced as Sales%20Charts.

Page 139: Hyperion 8.3 Developers Guide

The get Command 8-3

Note Hyperion recommends that UTF-8 encoding be used for double-byte characters (DBCS) contained in Smartcuts. In order to use UTF-8 encoding you need to set the Encoding for URL system property on the SmartCut properties page to UTF-8.

Available SmartCuts:

■ get

■ run

■ list

■ listNav

■ listIndex

■ listAll

Review the following sections for information on each of the SmartCuts. SmartCuts for BQY documents and jobs are supported with additional optional variables. For more information on these variables see “SmartCut Variables for BQY Documents and Jobs” on page 8-12.

The get CommandUse the get command to retrieve and view a document, report, or form, or to retrieve job output, and to retrieve a single report output object.

Page 140: Hyperion 8.3 Developers Guide

8-4 SmartCuts

These uses of the get command are discussed in the following topics:

■ Getting and Viewing a Document, Report, or Form

■ Getting Report Output

■ Getting a Single Report Output Object

Getting and Viewing a Document, Report, or FormTo view a report, a document, or a form stored in the Repository, use the get SmartCut, which has the following syntax:

http://servletsHost:servletsPort/Hyperion/browse/get/folderPath/ item [?version=versionNumber][?mimetype=mimeType][?latest=true]

where:

servletsHost is the name of the host machine on which the servlets run

servletsPort is the port number of the Web server on which the servlets run (you can omit :servletsPort if port number is 80)

Brio/browse is the default Web application deployment name. If you have named this directory differently in your Web server software, substitute the correct name.

folderPath can be a single folder name, or it can be a folder path. (For example: folder/subfolder/subfolder/….) The folder name should match the folder names stored in Hyperion Performance Suite.

item is the name of the item you want to view. Word documents, spreadsheets, HTML forms, and reports are examples of the types of items you can specify. The item name must exactly match the name given to the item when it was published in Hyperion Performance Suite.

versionNumber, part of the optional ?version argument, is the version number of the item. If you do not supply the version number, the SmartCut retrieves the latest version.

mimeType is the MIME type of the item.

The SmartCut examples that follow invoke Browse and retrieve the target document, report, or form stored in the system. If the user is not already logged into a Hyperion Foundation servlet, the login page displays prior to processing the URL and retrieving the item.

Page 141: Hyperion 8.3 Developers Guide

The get Command 8-5

Example 1 shows a SmartCut that retrieves an e-mail address list stored in a folder called Sales, which is a subfolder of SampleContent. This document is an HTML file, so the document is returned to the browser for viewing.

Example 1 http://apollo/Hyperion/browse/get/SampleContent /Sales/Email_Address_list

The SmartCut in Example 2 retrieves a report that was generated from a previously-run SQR job. You can also run the report instantly, if desired. See “The run Command” on page 8-8 for more information.

Example 2 http://apollo/Hyperion/browse/get/SampleContent /Sales/sales.htm

Note sales.htm is the name associated with the report when it was published in Hyperion Foundation after the SQR job ran.

Getting Report OutputThe SmartCut get can be used to return job output, like other Hyperion Foundation items. It works differently for SQR or non-SQR jobs as shown by the following examples.

SQR ReportsFor an SQR program, specify the SQRProgramOutput item, as follows:

http://hostname:port/Hyperion/browse/get/folderPath/Job-Name?jobOutput=true

This SmartCut returns the latest output for the job. Specifically, for SQR programs, it returns the HTML output file generated by the most recent run of the SQR program.

For the Sales Charts job, located in the in the Sales folder under SampleContent, the SmartCut would be:

Page 142: Hyperion 8.3 Developers Guide

8-6 SmartCuts

Example 3 http://apollo/Hyperion/browse/get/SampleContent/Sales /Output%20from%20Sales%20Charts

Note Remember to use %20 in place of a space character. Also keep in mind that SmartCuts are case sensitive.

Example 3 returns the following:

F igure 8-1 Result of SmartCut Getting Report Output

Page 143: Hyperion 8.3 Developers Guide

The get Command 8-7

Non-SQR ReportsFor a non-SQR report, the SmartCut get should specify the OutputCollection item, as follows:

http://hostname:port/Hyperion/browse/get/folderPath/JobName?mimetype=mimeType

This SmartCut returns the latest output for the job.

To look up the exact MIME type, use Browse module. Select an item of the type you want to get, choose the Modify properties icon, and look at the Advanced Options section.

For a report named Expenses, located in the Finance folder, and run by an application called ReportGenerator, the SmartCut to get the output would be:

Example 4 http://apollo/Hyperion/browse/get/Finance/Expenses ?mimetype=ReportGenerator%20Job%20Output

Note that the ?mimetype=type parameter is necessary, since the job itself is called Expenses. Without the mimetype parameter, the SmartCut would run the job. By specifying the MIME type, you can return only the output objects.

Page 144: Hyperion 8.3 Developers Guide

8-8 SmartCuts

Getting a Single Report Output ObjectIf a report has been run multiple times and you want to get only the latest output, use the latest=true query parameter. This parameter distinguishes between output objects of the same name with different dates. If the latest=true parameter is present, only the most recent output is returned.

Suppose you have an SQR program that generates reports in various formats, including PDF. To retrieve the PDF output file from the most recent run of the job, you would use a get SmartCut resembling the following:

Example 5http://hostname:port/Hyperion/browse/get/folderPath/JobName.pdf?latest=true

Without the latest=true parameter, if the job had been run more than once, the SmartCut would return a listing of all the PDF output files.

The latest=true parameter is used where there are multiple items of the same name. If there are multiple versions of a versioned item, the SmartCut get returns only the latest version by default. If you want a another version, specify it by number in the ?version=versionNumber parameter.

The run CommandYou can direct the Browse module to run a job stored in Hyperion Foundation by simply invoking a URL and passing the input parameters as part of the SmartCut run.

Note Passing parameters in the SmartCut works for SQR and generic jobs, but not for BQY jobs. For BQY jobs, see “Limits and LimitValues” on page 8-16.

To run the report or job, use the run SmartCut, which has the following syntax:

http://hostname:portNumber/Hyperion/browse/run/folderPath/JobName[?dbuser=dbUser&dbpass=dbPassword][&Param_1=param_1&Param_2=param_2][&AskParam_1=askparam1]...

Page 145: Hyperion 8.3 Developers Guide

The run Command 8-9

Optionally, you can include the following variables in the SmartCut run:

■ dbuser, dbpass

These variables are used to establish the database connection for running a report. They are optional in the SmartCut because they can alternatively be configured when publishing a job.

■ Param_1, Param_2, ... (or ASKparam_1, ... for ASK parameters)

Note the initial capital letters.

These parameters are used to execute the report or job. If a report does not require parameters, the SmartCut need not contain any parameters. If the report or job requires parameters, and some or all the required parameters are omitted in the SmartCut or POST operation, the parameter form displays.

Example 6 is a SmartCut that specifies a report to be run but includes no parameters. Since no parameters have been specified, the input parameter form will be retrieved and presented for the user to provide the necessary input parameters prior to running the job.

Example 6 http://apollo/Hyperion/browse/run/SampleContent/Sales/ Sales%20Charts

Example 7 shows a URL that specifies a report to be run. Input parameters are specified as part of the SmartCut run. This example will directly invoke the job and return the report output.

Example 7 http://apollo/Hyperion/browse/run/SampleContent/Production/Inventory_Information/Supplier_Exception_Re-port?Param_1=ALL

Example 8 shows a SmartCut that fills in all the required parameters. Using this URL results in Browse running the report using the parameters entered. Browse then displays the report output.

Page 146: Hyperion 8.3 Developers Guide

8-10 SmartCuts

Example 8 http://apollo/Hyperion/browse/run/SampleContent/ Sales/Sales%20Charts?user=sanderson&pass=sa357sf607&ser-ver=mercury&Param_1=SouthEastern&Param_2=4&Param_3= LINE&Param_4=YES

Note To determine what input parameters are needed for the report, view the Job properties in the Browse module.

The list CommandTo display the contents of a folder (excluding any subfolders of the folder), use list, which has the following syntax:

http://hostname:portNumber/Hyperion/browse/list/folderPath

This is equivalent to what is displayed in the main frame on the Browse tab.

Example 9 http://apollo/Hyperion/browse/list/SampleContent/Sales

The listNav CommandTo display just the parent folders and subfolders for the given folder, use listNav, which has the following syntax:

http://hostname:portNumber/Hyperion/browse/listNav/folderPath

This is equivalent to what displays in the navigation (lefthand side) frame on the Browse tab. The listNav SmartCut is not intended to be used directly, but rather, it is part of the listIndex SmartCut.

Example 10 http://apollo/Hyperion/browse/listNav/SampleContent/Sales

The listIndex CommandTo display both the listNav and the list pages in a frameset, use listIndex, which has the following syntax:

Page 147: Hyperion 8.3 Developers Guide

The listAll Command 8-11

http://hostname:portNumber/Hyperion/browse/listIndex

This is equivalent to displaying both the navigation and main frames on the Browse tab in a frameset.

This example does not take any arguments.

The listAll CommandTo display both the contents and the parent folders and subfolders in one HTML page, use listAll, which has the following syntax:

http://hostname:portNumber/Hyperion/browse/listAll/folderPath

Page 148: Hyperion 8.3 Developers Guide

8-12 SmartCuts

SmartCut Variables for BQY Documents and JobsThe SmartCut variables for BQY documents, jobs, and job output allow fuller access to BQY documents through other applications. You can use these variables to produce URLs with specific access to Hyperion Performance Suite applications, documents, jobs, and job output.

The table below shows which variables can be used with either the get or run command, which variables work with the Intelligence iServer only(bqtype=ihtml), and which variables work with BQY jobs only. For more information on each variable see the following section on that specific variable.

Note All the variables are case sensitive.

Table 8-1 SmartCut Variables

Variable Get RunIntelligence iServer only BQY Jobs Only

bqtype ✓ ✓

mimetype ✓ ✓

filename ✓ ✓

dest ✓ ✓

version ✓

jobOutput ✓ ✓

SectionName ✓ ✓ ✓

Toolbar ✓ ✓ ✓

BoundRect ✓ ✓ ✓

ShowForm ✓ ✓

Limit/LimitValue ✓ ✓

Page 149: Hyperion 8.3 Developers Guide

SmartCut Variables for BQY Documents and Jobs 8-13

bqtypeUse bqtype to specify which application to use to display the BQY document or job output. If bqtype is specified, the filename and mimetype variables are not necessary and will be ignored.

If bqtype equals plugin, the system checks that the user has permission to use the Hyperion Intelligence Client. If the user has permission, the BQY document or job output is opened using the Hyperion Intelligence Client. If the user does not have permission, an error message displays.

If the bqtype equals ihtml, the system checks that the user has permission to use the Intelligence iServer. If the user has permission, the BQY document or job output is opened using the Intelligence iServer. If the user does not have permission, an error message displays.

If bqtype is not set, the system checks if the user has permission to use the Intelligence iServer first. If the user does not have permission, the system checks to see if the user has permission to use the The Hyperion Intelligence Client. If the user does not have permission to use either application, an error message displays.

bqtype has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=<plugin/ihtml>

mimetype or filenameUse mimetype to specify the BQY job output type to open. If multiple objects of a mimetype exists a job listing is displayed. Use filename to specify a specific file. If filename is specified, the mimetype is not necessary and will be ignored. The default mimetype is BQY.

mimetype has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?mimetype=text/html&jobOutput=true

http://hostname:portNumber/Hyperion/browse/run/folderPath?mimetype=text/html&ShowForm=false

filename has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?filename= filename&jobOutput=true

Page 150: Hyperion 8.3 Developers Guide

8-14 SmartCuts

http://hostname:portNumber/Hyperion/browse/run/folderPath?filename=filename&ShowForm=false

Tip The filename can be accessed by mousing over the job output icon or BQY icons. The mimetype can be accessed by mousing over the link of the job output or the BQY file.

destUse the dest variable instead of folderpath to specify the UUID of an item when there are multiple documents with the same name.

Instead of this syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath/

use this syntax:

http://hostname:portNumber/Hyperion/browse/get?dest=UUID

versionUse version to specify the version number. If this is not specified the latest version is used.

version has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=<plugin/ihtml>?version=versionNumber

SectionNameUse to reference a specific section from a BQY document. If SectionName is not specified, the default section specified in the BQY document displays.

SectionName has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=ihtml&SectionName=<name>

ToolbarUse to specify whether the toolbar will display or not. If a toolbar setting is not specified, no toolbar displays.

Page 151: Hyperion 8.3 Developers Guide

SmartCut Variables for BQY Documents and Jobs 8-15

If Toolbar equals “Standard”, the full toolbar displays which includes access to help. If Toolbar equals “Navigation”, only the bar for paging displays.

Toolbar has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=ihtml&SectionName=<name>&Toolbar=Standard

BoundRectUse to provide the height and width for the Web browser.

BoundRect has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=ihtml&SectionName=<name>&ToolBar=”Navigation”&BoundRect=<w,h>(w is width, h is height in pixels)

JobOutputUse this variable to display job output after a job has been run.

jobOutput has the following syntax:

http://hostname:portNumber/Hyperion/browse/get/folderPath?bqtype=ihtml&jobOutput=true

ShowFormUse this variable to give the user access to the browse run screen to set or change limits. The default is true. ShowForm must be false when passing parameters via the URL.

ShowForm has the following syntax:

http://hostname:portNumber/Hyperion/browse/run/folderPath?bqtype=plugin&ShowForm=true

http://hostname:portNumber/Hyperion/browse/run/folderPath?bqtype=plugin&ShowForm=false&Limit1=q1\state&LimitValue1=CA&LimitValue1=MI

Page 152: Hyperion 8.3 Developers Guide

8-16 SmartCuts

Limits and LimitValuesMultiple variable limits can be passed using the Limit and LimitValue parameters when ShowForm equals false. Each Limit can have multiple LimitValues.

limit and limitValue have the following syntax:

http://hostname:portNumber/Hyperion/browse/run/folderPath?bqtype=ihtml&ShowForm=false&Limit1=q1\state&LimitValue1=CA&LimitValue1=MI&Limit2=q2\Product&LimitValue2=A001

In order to pass date limits you have to define the day, month, year, time, and time zone as the following syntax shows:

http://hostname:portNumber/Hyperion/browse/run/folderPath?bqtype=ihtml&jobOutput=true&ShowForm=false&Limit1=q1/SaleDate&LimitValue1=dd=12,mm=12,yyyy=2004,time=13:30:00,tz=America/Los_Angeles

where

dd is day

mm is month

yyyy is year

hh is hour

mm is minute

ss is second

tz is the time zone

The default hour, minute, second is midnight. The default time zone is the time zone of the server’s location. This field uses recognized Java time zones.

It is also possible to use constants for dates. The following table defines the supported constants.

Page 153: Hyperion 8.3 Developers Guide

SmartCut Variables for BQY Documents and Jobs 8-17

The syntax when using a date constant is:

http://hostname:portNumber/Hyperion/browse/run/folderPath?bqtype=ihtml&ShowForm=false&Limit1=q1\SaleDate&LimitValue1=FirstOfMonth, tz=America/Los_Angeles

Note The Ignore and Don’t Prompt flag defaults apply when a job is run. When limit values are passed using a SmartCut and the Ignore flag is set to true the new values will be ignored. To change these flags, modify the properties of the job through the browse module before running the job.

Table 8-2 Date Constants

Name Value

First of Month FirstOfMonth

First of Previous Month FirstOfPreviousMonth

First of Quarter FirstOfQuarter

First of Week FirstOfWeek

First of Year FirstOfYear

Friday Friday

Last of Month LastOfMonth

Last of Previous Month LastOfPreviousMonth

Last of Quarter LastOfQuarter

Last of Week LastOfWeek

Last of Year LastOfYear

Monday Monday

Previous Business Day PreviousBusinessDay

Today Today

Yesterday Yesterday

Page 154: Hyperion 8.3 Developers Guide

8-18 SmartCuts

SmartCut ExamplesTwo examples for using SmartCuts are provided here.

Example: Accessing Hyperion Performance Suite Content from a Web Application Using SmartCuts, you can integrate Hyperion Performance Suite into your intranet, your home page, or any web-based application, as the example in this section illustrates. A single click from your intranet (or home page) takes you to Hyperion Performance Suite information.

This example creates a “dashboard” or “kiosk” with several buttons that access both Web and Hyperion Performance Suite content. The example shows how you can create a central starting point for accessing all one’s electronically available information. The buttons of the example “kiosk” page go to:

■ Your company's intranet

■ Your company’s Web site

■ Your partners’ extranets

■ Hyperion Performance Suite content

F igure 8-2 Kiosk for Access to Hyperion Performance Suite Content, Intranet, and Extranets

Page 155: Hyperion 8.3 Developers Guide

SmartCut Examples 8-19

The three lower buttons all access Hyperion Performance Suite content, but in different ways, each using a different SmartCut:

■ Listing all the folders (like the navigation pane in Browse)-- using the SmartCut listIndex.

■ Displaying report output--using the SmartCut get.

■ Running a report--using the SmartCut run.

To create the example, follow these steps:

1 Find or create the graphics you want to use for the kiosk buttons, and save the graphics files in the wsmedia/personalize subdirectory of your Web application deployment directory (servlets/deployment by default).

2 In Notepad (or any editor that does not change the code), enter the code below.

If you are viewing this documentation in Adobe Acrobat Reader 4.0 or above, you can copy the text using the Text Select Tool, and paste it into your editor.

The code shown is kiosk0.htm, with the SmartCut names shown in boldface. What you need to replace (in the next Step) is shown in bold italics:

<HTML><HEAD><TITLE>KIOSK</TITLE></HEAD><BODY>

<TABLE>

<TR><TD> <A HREF="http://intranet" > <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/personalize/graphic1"></A></TD><TD>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp</TD>

<TD> <A HREF="http://website" > <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/personalize/graphic2"></A></TD><TD>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp</TD>

<TD> <A HREF="http://extranetsListURL" > <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/personalize/graphic3"></A></TD><TD>&nbsp</TD></TR>

Page 156: Hyperion 8.3 Developers Guide

8-20 SmartCuts

<TR VALIGN="TOP"><TD ALIGN="CENTER"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>Our Company<BR>Intranet </B></FONT></TD><TD>&nbsp</TD>

<TD ALIGN="CENTER"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>Our Company<BR>Website</B></FONT></TD><TD>&nbsp</TD>

<TD ALIGN="center"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>Our Partners'<BR>Extranets</B></FONT></TD></TR>

<TR><TD>&nbsp<BR>&nbsp</TD><TD>&nbsp</TD><TD>&nbsp</TD></TR>

<TR><TD> <A HREF="http://servletsHost:servletsPort/root/browse/listIndex?user=username&pass=password&server=GSMhost:GSMport"> <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/ personalize/graphic4"></A></TD><TD>&nbsp</TD>

<TD> <A HREF="http://servletsHost:servletsPort/root/browse/get/SampleContent/Production/Inventory_Information/Central_Facility_Report?user=username&pass=password&server=GSMhost:GSMport"> <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/personalize/graphic5"></A></TD><TD>&nbsp</TD>

<TD> <A HREF="http://servletsHost:servletsPort/root/browse/run/SampleContent/Sales/Sales%20Charts?user=username&pass=password&server=GSMhost:GSMport"> <IMG border=0 src="Install_Home/servlets/deployment/wsmedia/personalize/graphic6"></A></TD></TR>

<TR VALIGN="TOP"><TD ALIGN="center"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>Browse All<BR>Folders</B></FONT></TD><TD>&nbsp</TD>

<TD ALIGN="center"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>View<BR>Sales Report</B></FONT></TD><TD>&nbsp</TD>

<TD ALIGN="center"> <FONT FACE="Arial" COLOR="saddlebrown" SIZE=+0><B>Run "Sales <BR>Chart" Report</B></FONT></TD></TR>

Page 157: Hyperion 8.3 Developers Guide

SmartCut Examples 8-21

</TABLE>

</BODY></HTML>

3 Make the following substitutions in the code:

■ Replace intranet with the URL for your company’s intranet.

■ Replace Install_Home with the name of your installation directory, which is the directory containing the servlets directory.

■ Replace root/browse with the Web application deployment directory name or alias, if it is set differently in your Web server software.

■ Replace graphic1, graphic2, etc. with filenames of your button images.

■ Replace website with the URL for your company’s public Web site.

■ Replace extranetsList.htm with the URL for a page containing links to your partners’ extranets.

■ Replace servletsHost with the name of the host on which the servlets are installed.

■ Replace servletsPort with the port number for the Browse servlet.

■ Replace the path of the example “Central Facility Report” with that of your report output object.

■ Replace the path of the example “Sales Charts” SQR program with that of your report program.

■ Replace username with appropriate user name.

■ Replace password with appropriate password.

Note Supplying the user name and password in SmartCuts is not necessary if you have implemented transparent login. See the Foundation Administrator’s Guide for more information.

■ Replace GSMhost with the name of the host running the Global Service Manager.

■ Replace GSMport with the port number for the Global Service Manager. (The default is 1800.)

4 Save the file as kiosk.htm.

Page 158: Hyperion 8.3 Developers Guide

8-22 SmartCuts

5 Incorporate kiosk.htm into your web-based application or make it the home page in your browser.

Example: Using SmartCuts Via HTML FormsSmartCut variables can be used as part of HTML forms. This example shows the code for a simple form (Figure 8-3) produced using HTML and SmartCut variables.

Note HTML form METHOD=POST is UTF-8 compatible for double byte character encoding.

<HTML></BODY>Please choose values for the BQY job input parameters:

<FORM name=myJobForm METHOD=POST ACTION="http://servletsHost:servletsPort/Hyperion/browse/run/myFolder/myBQYJob" ><input type=text name=Limit1 value="q1\State"></input><select name=LimitValue1 multiple><option value="CA">California</option><option value="NY">New York</option><option value="NJ">New Jersey</option><option value="FL">Florida</option><option value="HI">Hawaii</option></select><input type=hidden name=ShowForm value=false><input type=hidden name=user value=username><input type=hidden name=pass value=password><input type=hidden name=server value=servletsHost:servletsPort>

<input type=submit name=submitbutton value="Submit Job"></FORM></BODY></HTML>

Page 159: Hyperion 8.3 Developers Guide

SmartCut Examples 8-23

F igure 8-3 HTML Form Using SmartCut Variables

Page 160: Hyperion 8.3 Developers Guide

8-24 SmartCuts

Page 161: Hyperion 8.3 Developers Guide

9 Extended Services

This chapter describes how to integrate an extended service with the Hyperion Foundation servlets. After an extended service is integrated, end-users have seamless access to it through the servlets in the context of a regular session.

In This Chapter Integrating Extended Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2

Displaying Extended Service Content on Personal Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-7

Page 162: Hyperion 8.3 Developers Guide

9-2 Extended Services

Integrating Extended ServicesTo extend or supplement the system’s functionality, you may want to use services beyond those provided by Hyperion Performance Suite. Such “extended services” may be developed by your organization or a third party. They may augment the functionality of an existing Hyperion Performance Suite feature—for example, extending notifications into a workflow feature.

Note For an extended service to be integrated with the Hyperion Foundation servlets, the resources (files or programs) specified by the extended service must exist in the same Web server context as the Hyperion Foundation servlets.

The following topics provide information about using extended services:

■ Configuration File for Extended Services

■ URL to Access Extended Services

■ Examples Entries and URLs for Service Properties

■ Aggregation of Query Parameters

■ Relative Links in Extended Service HTML Output

■ Local Resource Management

Configuration File for Extended ServicesConfiguration information for extended services is stored in the services.properties file, located in the Install_Home/servlets/deployment/config directory.

To help avoid name collisions with internal Hyperion Foundation commands or commands of different services, every extended service has a URL prefix. It is not necessary to specify a prefix in a services.properties entry, however. If an entry lacks a prefix, the default prefix ext is assigned to it.

Each extended service must have two entries in services.properties: one for each of the two properties, resource and resource type. The resource is the file or program that handles requests for the extended service. The resource

Page 163: Hyperion 8.3 Developers Guide

Integrating Extended Services 9-3

may be, for example, an HTML or JSP file or a servlet. The resource type indicates whether the resource is represented by a path ($PATH$) or a name ($NAMED$).

If the resource is identified by a file or program path, the resource value should be the path. A path is typically an absolute path from the Web server context root, starting with the “/” (forward slash) character. If the resource is identified by a named resource such as a servlet, the resource value should be the name of the servlet (as known to theWeb server).

You can add query parameters to the resource value if the resource is of the type $PATH$. This lets you pass parameters with static values to the resource.

Entries in services.properties should use the following format:

[urlPrefix.]serviceCommandName.resource=PathOrName[?param1=value1&param2=value2][urlPrefix.]serviceCommandName.type=$PATH$|$NAMED$

Examples of services.properties entries are shown in “Examples Entries and URLs for Service Properties” on page 9-4.

Note Command names are case sensitive.

URL to Access Extended ServicesYou can access extended services via the Hyperion Foundation servlets by specifying a URL in the following format:

protocol://host:port/Hyperion/servlet/servicePrefix/ serviceCommand[?queryParameters]

where:

protocol is HTTP or HTTPS

host is the name or IP address of the host machine on which the Hyperion Foundation servlets are running

port is the port number of the Web server on which the servlets are running

servlet is the name of a Hyperion Foundation servlet; it is one of the following case-sensitive literal strings: browse, personalpages, jobmanager, viewmanager, or administration

Page 164: Hyperion 8.3 Developers Guide

9-4 Extended Services

servicePrefix is the name of the prefix for the extended service. Prefixes help avoid name collisions with internal Hyperion Foundation commands or commands of other services. The default service prefix is ext

serviceCommand is the required command name to invoke the extended service

queryParameters are one or more optional parameters that the extended service takes as input

For example:

http://apollo:11122/Hyperion/jobmanager/ext/myExtendedService

Examples Entries and URLs for Service PropertiesThe following examples of service.properties entries and URLs illustrate different service configurations. The examples involve a dinner menu service for late-working employees, whose command name is dinnerMenu.

Note In this section, the protocol://host:port portion of each example URL is omitted for readability and to emphasize the portion specific to extended services. In actual usage, the full URL is necessary to access the extended service.

Example 1 For a named resource where the dinnerMenu service is handled by a servletknown to the Web server as DinnerMenuServlet, and where no prefix is specified,the service.properties entries are as follows:

dinnerMenu.resource=DinnerMenuServletdinnerMenu.type=$NAMED$

The type is specified as $NAMED$ because this is a named resource rather than afile path.

Because no URL prefix was specified, the default prefix is used. The URL to accessthis extended service is:

Page 165: Hyperion 8.3 Developers Guide

Integrating Extended Services 9-5

/Hyperion/servlet/ext/dinnerMenu

If the service takes query parameters at runtime, the parameters are specified atthe end of the URL. Assuming that the dinnerMenu service takes two parameters,dayOfWeek and month, the URL would be:/Hyperion/servlet/ext/dinnerMenu?dayOfWeek=Tuesday&month=Sep-tember

Example 2 Same as Example 1, except that the URL prefix is specified as brio. Theservice.properties entries are:hyperion.dinnerMenu.resource=DinnerMenuServlethyperion.dinnerMenu.type=$NAMED$

The URL to access this extended service is:/Hyperion/servlet/hyperion/dinnerMenu

Example 3 For a resource expressed as a path, where the dinner menu service is handled by aservlet, the service.properties entries are:dinnerMenu.resource=/servlet/DinnerMenuServletdinnerMenu.type=$PATH$

Because no URL prefix was specified, the default prefix is used. The URL to accessthis extended service is:/Hyperion/servlet/ext/dinnerMenu

Example 4 For a file resource, where requests for the dinnerMenu service are handled by aJSP with the path /scripts/dinnerMenu.jsp, the service.propertiesentries are:dinnerMenu.resource=/scripts/dinnerMenu.jspdinnerMenu.type=$PATH$

Because no URL prefix was specified, the default prefix is used. The URL to accessthis extended service is:/Hyperion/servlet/ext/dinnerMenu

Example 5 Same as Example 4, except that requests for the dinner menu service are handledby an HTML file, whose path is /wsmedia/docs/dinnerMenu.html. Theservice.properties entries are:dinnerMenu.resource=/wsmedia/docs/dinnerMenu.htmldinnerMenu.type=$PATH$

Example 6 Same as Example 3, but passing static query arguments via the resource entry. Thequery arguments are named startTime and location, with values 19:00 and CA,respectively. The service.properties entries are as follows. (Differencesfrom Example 3 are represented in bold.)

Page 166: Hyperion 8.3 Developers Guide

9-6 Extended Services

dinnerMenu.resource=/servlet/DinnerMenuServlet?startTime=19:00&location=CAdinnerMenu.type=$PATH$

The URL to access this extended service is the same as that in Example 3:/Hyperion/servlet/ext/dinnerMenu

Aggregation of Query ParametersIf query parameters are specified both in the URL and in the definition of a $PATH$-type resource in services.properties, then the query string will contain the aggregate of the two sets of query parameters.

Example 7 Suppose the services.properties file contains the following:

dinnerMenu.resource=/servlet/DinnerMenuServlet?param1=1&param2=2dinnerMenu.type = $PATH$

and the URL to access this service is:

/servlet/WebClient/ext/dinnerMenu?param3=3&param4=4

The query string then contains ?param1=1&param2=2&param3=3&param4=4

Relative Links in Extended Service HTML OutputIf there are any relative links in HTML content returned by an extended service, these links are relative to the URL. To specify another path for relative links, precede the content with an HTML <BASE> tag that specifies the desired base URL.

Local Resource ManagementBecause requests for extended services come via the Hyperion Foundation servlets, Hyperion Performance Suite performs user authentication and session creation and management for an extended service. The extended service does not need to re-authenticate the user. However, the extended service may require information about the user’s session to manage local resources associated with the session.

When forwarding a request to an extended service, a Hyperion Foundation servlet also passes a serialized session token object containing secure information about the user’s session. The string from the session token may be

Page 167: Hyperion 8.3 Developers Guide

Displaying Extended Service Content on Personal Pages 9-7

retrieved from the com.brio.one.client.SessionToken attribute of the javax.servlet.http.HttpSession object. After the session token is obtained in its string format, it can be used to join the session through Hyperion Performance Suite’s API.

Displaying Extended Service Content on Personal PagesYou can display content from an extended service on a Personal Page by publishing an external link to the extended service.

In cases where the system has multiple installations of the servlets and it is not known in advance which one will be used to display the extended-service content, you should omit the protocol, host, and port information from the URL for the external link. Thus, the published URL would have the following format:

/Hyperion/servlet/serviceURLPrefix/serviceCommandName

Page 168: Hyperion 8.3 Developers Guide

9-8 Extended Services

Page 169: Hyperion 8.3 Developers Guide

A How to Use the API Sample Programs for Non-Java Programmers

This appendix is for non-Java programmers who want to learn how to compile and run the sample API programs which are included in the Hyperion Performance Suite SDK. This appendix includes instructions for Windows users on preparing to use the sample programs, how to compile and run sample programs, and a tutorial on how to add a user using the Batch Driver sample program.

UNIX users replace the batch (BAT) files with shell (SH) files and reverse the slash marks in the pathnames, for example, Install_Home\SDK\lib\rmapi.jar is Install_Home/SDK/lib/rmapi.jar in UNIX. Other differences are noted in the text.

For complete syntax for all the sample programs, see “Samples” on page 4-4. For more information on the control file and control statements for the batch driver program, see Chapter 3, “Batch Driver Sample Program Control File.”

In This Chapter Preparing to Use the Sample Java Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-2

Running the Login Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-6

Batch Driver Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-7

Page 170: Hyperion 8.3 Developers Guide

A-2 How to Use the API Sample Programs for Non-Java Programmers

Preparing to Use the Sample Java ProgramsThe sample Java programs are located in Install_home\SDK\samples\java. To run these programs you need to compile them and then run them using execapi.bat from the command prompt passing the necessary arguments.

The Batch Driver sample program can be run without compiling as a compiled version of the program is included in Install_Home\SDK\lib\rmapi.jar with the other API class files.

The following topics describe the setup procedures you must perform before using the samples:

■ Installing Hyperion Performance Suite SDK

■ Validating the Hyperion Performance Suite Connection

■ Compiling the Sample Programs

Installing Hyperion Performance Suite SDKYou use the Hyperion Performance Suite Software Development Kit (SDK) to develop Java-based code for Hyperion Performance Suite.

To install the Hyperion Performance Suite SDK:

1 Double-click on setupWinPlatform.exe located on the Servers CD Disk 1.

For UNIX, run the appropriate setup file from the Servers CD for your system.

2 When asked, provide a license key.

3 On the installation type screen, select Custom Install.

■ On the components screen:

❑ - Select Clear all check marks for all components.

❑ - Scroll down and select the SDK component.

4 Follow the on-screen instructions to complete the installation.

Validating the Hyperion Performance Suite ConnectionTest that the server you are using has Hyperion Performance Suite running.

Page 171: Hyperion 8.3 Developers Guide

Preparing to Use the Sample Java Programs A-3

To validate the Hyperion Performance Suite connection:

1 Enter URL in web browser: http://< host>:<port>/<path>

For example: http://venice:8100/Hyperion/browse/Main

2 Enter a valid username and password.

You should see the following page:

Compiling the Sample ProgramsAll of the sample programs, except the batch driver sample program, must be compiled before you can run them. In order to compile the sample programs you need to install the Java compiler and set up the environment which includes letting the system know where the Java compiler is installed.

The execapi.bat file which is generated by the installer contains the environment information that you need to compile as well as run the sample programs. An easy way to compile the sample programs is to create a batch file that you can use to compile the sample programs.

The following topics describe steps and information for compiling the sample programs:

■ “Installing the Java Compiler” on page A-4

■ “About execapi.bat” on page A-4

■ “Creating a Batch File to Compile the Sample Programs” on page A-5

■ “Compiling the Login Sample Program” on page A-6

Page 172: Hyperion 8.3 Developers Guide

A-4 How to Use the API Sample Programs for Non-Java Programmers

Installing the Java CompilerYou need to install the Java Compiler to compile all the sample programs.

You do not need to install a Java compiler if you are using the Hyperion provided compiled batch driver class, com.squibe.rm.BatchDriver, located in Install_Home\SDK\lib\rmapi.jar.

To install the Java compiler:

1 Download Java 2 Standard Edition (J2SE) for compiling and running Java code from http://java.sun.com/j2se/1.4.2/download.html.

J2SE contains the Software Development Kit (SDK) and the JAVA Runtime Environment (JRE).

2 Select J2SE v1.4.2_04 SDK to download.

For compiler installation documentation, see http://java.sun.com/j2se/1.4.2/docs/index.html#notes.

About execapi.batThis file sets up the environment and runs the sample files. The execapi.bat file is generated by the installer and is located in Install_Home\SDK\bin.

The following is an example execapi.bat file:

@echo OFFREM execapi.bat -- this file was generated by the Hyperion installation programsetlocalset briohome=C:\Program Files\Brio\Hyperionset SYSPROPS=-Ddirectory=”%briohome%\SDK”set classpath=.;%briohome%\SDK;%briohome%\SDK\lib\rmapi.jar;%briohome%\lib;%briohome%\SDK\etc\log4j;%briohome%\lib\log4j.jar;%briohome%\lib\foundation.jar;%briohome%\lib\iona61.jar;%briohome%\lib\comutil1_01.jar;%briohome%\lib\logi.crypto1.1.2.jar;%briohome%\lib\xercesImpl.jar;%briohome%\lib\xmlParserAPIs.jar;%briohome%\lib\spf82.jar;%briohome%\lib\commons_collections.jar;%briohome%\BrioPlatform\lib\bqservice.jar

pushd %briohome%\SDK\samples\java"%briohome%\jre\jre141\bin\java" %SYSPROPS% -mx64m -cp "%classpath%" %*popdendlocal

Page 173: Hyperion 8.3 Developers Guide

Preparing to Use the Sample Java Programs A-5

Creating a Batch File to Compile the Sample Programs

An easy way to compile the sample programs is to create a batch file to compile the sample programs. You can use the execapi.bat to create a batch file, jc.bat, to compile the sample programs.

To create jc.bat:

1 Copy and save execapi.bat as jc.bat in Install_Home\SDK\sample\java.

Do not move or change the original execapi.bat file.

2 Add a line after SYSPROPS to set JAVA_HOME to the location of your Java compiler .

For example:set SYSPROPS=-Ddirectory=”%briohome%\SDK”set JAVA_HOME=C:\j2sdk1.4.1_03\bin\javac

3 Replace the last line of the file:

"%briohome%\jre\jre141\bin\java" -mx64m -cp "%classpath%" %*

with the command to run the compiler:

%JAVA_HOME% -classpath "%classpath%" %*

The jc.bat file should look like the following:

@echo OFFREM execapi.bat -- this file was generated by the Hyperion installation programsetlocalset briohome=C:\Program Files\Brio\Hyperionset SYSPROPS=-Ddirectory=”%briohome%\SDK”set JAVA_HOME=C:\j2sdk1.4.2_04\bin\javacset classpath=.;%briohome%\SDK;%briohome%\SDK\lib\rmapi.jar;%briohome%\lib;%briohome%\SDK\etc\log4j;%briohome%\lib\log4j.jar;%briohome%\lib\foundation.jar;%briohome%\lib\iona61.jar;%briohome%\lib\comutil1_01.jar;%briohome%\lib\logi.crypto1.1.2.jar;%briohome%\lib\xercesImpl.jar;%briohome%\lib\xmlParserAPIs.jar;%briohome%\lib\spf82.jar;%briohome%\lib\commons_collections.jar;%briohome%\BrioPlatform\lib\bqservice.jar

pushd %briohome%\SDK\samples\java%JAVA_HOME% -classpath "%classpath%" %*popdendlocal

Page 174: Hyperion 8.3 Developers Guide

A-6 How to Use the API Sample Programs for Non-Java Programmers

Compiling the Login Sample ProgramYou compile all of the sample programs in the same way. This procedure uses the login sample program.

To compile the Login sample program:

1 Open the Command Prompt window.

2 Go to the directory where jc.bat is located.

C:\Documents and Settings\ksmith>cd Install_Home\SDK\samples\java

3 Enter jc Login.java to compile the program.

Install_Home\SDK\samples\java>jc Login.java

4 Check that Login.class is in the Install_Home\SDK\samples\java folder.

Running the Login Sample ProgramYou should run the login sample program before you run any of the other sample programs to check your Hyperion Performance Suite connection.

To run the login sample program:

1 Open the Command Prompt window.

2 Go to the directory where execapi.bat is located.

For example:

C:\Documents and Settings\ksmith>cd Install_Home\SDK\bin

3 Enter the following syntax in the command prompt window:

execapi Login <username> <password> <host> <port>

For example:

Install_Home\SDK\bin>execapi Login administrator administrator qastar 1800

If the login worked you will see the following messages in the command prompt window:

connection establishedconnection closed

Page 175: Hyperion 8.3 Developers Guide

Batch Driver Tutorial A-7

Batch Driver TutorialThe batch driver sample program uses the following files:

■ execapi.bat – This file sets the environment, passes arguments to the program, and runs the program including using the control file, batch_driver.cf. This file is located in <Install_Home>\SDK\bin.

■ batch_driver.cf – This is the control file that contains control statements that describe objects that will be created in the database by the batch driver program. It is located in the <Install_Home>\SDK\Samples\java directory. For more information on the control file, see Chapter 3, “Batch Driver Sample Program Control File.”

In this tutorial the batch_driver.cf file contains data to add one user. The batch_driver.cf looks like the following:

user uid=testUser^pwd=testUser^name=Test User^desc=A Test User^defcat=/batchFolder^[email protected]^authensystem=default_system^group=testGroup1^group=testGroup3^role=CONTENT PUBLISHER^role=USER^perm=accessor2^perm=accessor4

To run the batch driver sample:

1 Open the Command Prompt window.

2 Go to the directory where execapi.bat is located.

For example:

C:\Documents and Settings\ksmith>cd C:\Program Files\Hyperion\SDK\bin

3 Run the batch driver sample program from the command prompt window.

If you are using the installed BatchDriver.class use the following syntax:

execapi com.sqribe.rm.BatchDriver <username> <password> <host> <port> <control filename>

For example:

C:\Program Files\Hyperion\SDK\bin>execapi com.sqribe.rm.BatchDriver administrator administrator venice 1800 batch_driver.cf

If you compiled the batch driver program use the following syntax:

execapi BatchDriver <username> <password> <host> <port> <control filename>

Page 176: Hyperion 8.3 Developers Guide

A-8 How to Use the API Sample Programs for Non-Java Programmers

For example:

C:\Program Files\Hyperion\SDK\bin>execapi BatchDriver administrator administrator venice 1800 batch_driver.cf

4 Open Hyperion Performance Suite and check that the user in the batch_driver.cf is in the user list.

You should see Test User in the list of users.

5 Create a batch file to run this class again by copying and saving the following line from the command prompt window into a batch file, batch_driver.bat, in Install_Home\SDK\sample\java:

execapi com.sqribe.rm.BatchDriver administrator administrator venice 1800 batch_driver.cf

or

execapi BatchDriver administrator administrator venice 1800 batch_driver.cf

Now you can run the batch driver sample program by simply clicking the batch file. Change the batch_driver.cf file to add other objects. For more information on the batch driver control file, see Chapter 3, “Batch Driver Sample Program Control File.”

Page 177: Hyperion 8.3 Developers Guide

Glossary

access control A security mechanism that

manages a user’s privileges—such as viewing,

modifying, publishing—to a system’s resources.

access privileges The level of access—for

example, view, modify, run, full control—that

the publisher of an item grants to others; also, at

what level other users or groups can access a

user or group as well as what a user and

members of a group can do.

actions Execution of a BQY job is defined in

terms of a series of actions. Actions define the

job output format.

active group A group that is currently entitled to

access the system.

active service A service whose Run Type is set to

Start rather than Hold.

active user A user who is currently entitled to

access the system.

adaptive states BQY level of permission. There

are six levels of permission: view only, view and

process. analyze, analyze and process, query and

process, and datamodel and analyze.

administrator A predefined user who generally

is granted roles that grant administrative

capabilities, but is not exempt from access

privilege checking.

appender Log4j term for destination.

application A program running within a system,

such as SQR.

Authentication Service A Core service that

manages one authentication system.

Authentication Service repository (ASR) A

Database that contains a complete model of

users/groups in external system.

authentication system A security measure

designed to validate and manage users and

groups.

bookmark A link to a Hyperion Performance

Suite item or a web site, displayed on a Personal

Page of a user. The two types of bookmarks are

My Bookmarks and image bookmarks.

bounding rectangle The perimeter that

encapsulates the BQY content when embedding

BQY sections in a Personal Page. It is required

by the Intelligence iServer to generate HTML

and is specified in pixels for height and width or

row per page.

Page 178: Hyperion 8.3 Developers Guide

2 Glossary

BQY files or jobs Files created by the Hyperion’s

Intelligence products and published into the

Repository as files or as jobs. Files and jobs have

different capabilities.

BQY sections Divisions of a BQY file used to

display and analyze information in different

formats (such as Chart Section and Pivot

Section).

BrioPlatform Server A Windows service that

starts all the active Foundation services of

Hyperion Performance Suite. Its default name

is:

BrioPlatform_LocalHost_GSMHost_GSM

Port.

connection file See Open Catalog Extension Files

(OCE) Files

content Information stored in the Hyperion

Foundation Repository. It includes report

programs (jobs), report output, documents

such as spreadsheets or word processing

documents, images, HTML pages, files of any

type, multiple versions of files, or URLs.

cookie A small piece of information placed on

your computer by a web site.

custom calendar Any calendar created by an

administrator.

cycle Used when scheduled BQY jobs need to

process and produce different job output with

one job run. Cycles are among the BQY job

parameters.

default folder A user’s home folder.

embedded section Sections from the Hyperion

Intelligence Products (Results, Tables, Pivots,

Charts, and OLAP Results) can be embedded

into a Personal Page. All embedded sections

maintain live data content and formatting from

the original section.

exception A condition or result (such as a

threshold being reached) generated by an

automated process, which requires some

intervention or oversight. It can cause (a) the

corresponding indicator on a subscribing user’s

Exceptions Dashboard to change, or (b) a

notification to be sent to a user who has

subscribed to it.

Exceptions Dashboard An optional content

window used to monitor exceptions on

Personal Pages. Add exception indicators to this

dashboard. Each indicator represents one

exception-capable report.

external authentication system An authentication

system that uses an external driver to access an

external system, from which it retrieves user and

group information.

externally triggered events Non-time-based

events that are used to schedule job runs.

folders Items are organized into folders. Folders

are similar to the directories or folders of your

operating system, and are arranged in a

hierarchical structure. A folder can contain

subfolders, items, or both.

generic jobs Jobs that are neither SQR nor BQY

jobs.

Page 179: Hyperion 8.3 Developers Guide

Glossary 3

global administrator A predefined user who has

control of all Hyperion Performance Suite

resources and is not subject to access privilege

checking by the system.

group A construct that allows the assignment of

users that have similar system access

requirements.

host A server on which a Hyperion

Performance Suite service is installed.

host properties Properties pertaining to a host,

or if the host has multiple Install_Homes, to a

Install_Home. The host properties are

configured from the LSC.

Hypertext Markup Language (HTML) A

programming language used to create World

Wide Web pages, with hyperlinks and tags that

explain to a browser how to format the

information on the screen.

image bookmarks Graphic links to web pages or

Hyperion Performance Suite items.

inactive group A group that cannot access the

system because an administrator has inactivated

it. Only in the authentication system that

manages a group can a particular group be

deleted.

inactive service A service that has been placed on

hold or excluded from the list of services to be

started.

inactive user A user who cannot access the

system because an administrator has inactivated

the user account. Only in the authentication

system that manages a user can a particular user

be deleted.

Intelligence iServer A thin-client product used to

interactively view BQY documents with a

browser.

Intelligence Products A fully integrated business

intelligence solution that provides powerful

query, analysis, and reporting functionality

across both client/server and web

environments.

Install_Home The directory under which a

Hyperion Performance Suite client or server is

installed. Install_Home is a variable; its path and

name were specified during installation. See also

next definition.

Install_Home A single set of Hyperion

Performance Suite servlets or services, which

run in a single process space and are installed in

the same Install_Home directory (see definition

above). The term “Install_Home” is used in this

way to indicate a single client or server even

when n clients or servers, in n Install_Home

directories, are installed on the same machine.

item A piece of content. An item can be a report

program (job), report output, a document

created in a spreadsheet or word processing

application, an image, an HTML page, a file of

any type, a set of versions of a file, or a URL.

Every item possesses properties, which store

extra information about the item.

JSP Java Server Pages.

jobs Executable objects; typically reports,

programs, or scripts.

job output Files or reports produced from

running a job.

Page 180: Hyperion 8.3 Developers Guide

4 Glossary

job parameters The compile time and run time

values necessary to run a job.

logger Log4j term for where the logging

message originates. The class or component of

the system in which a log message originated.

LSC services The services that are configured

with the Local Service Configurator. They

include: Global Services Manager (GSM), Local

Services Manager (LSM), Session Manager,

Authentication Service, Authorization Service,

and Publisher Service, Super Service, Logging

Service, Usage Service, and in some contexts,

Data Access Service (DAS) and Intelligence

Service.

metadata Data about data; properties and

options pertaining to particular content items

or other resources (such as users).

MIME Type Multipurpose Internet Mail

Extension. Describes the format of data in an

item (for example, an Excel spreadsheet or an

SQR program) so that the system knows which

application to launch to open the object.

native authentication server An authentication

server for which Hyperion Performance Suite

manages all the user and group information in

its own database, the Authentication Service

repository (ASR). It does not use an

authentication driver.

null value A value that is absent of data.

OCE See Open Catalog Extension Files (OCE)

Files

Open Catalog Extension Files (OCE) Files Files

that encapsulate and store connection

information used to connect Hyperion

Intelligence applications to a database. OCE

files specify the database API (ODBC, SQL*Net,

etc.), database software, the network address of

the database server, and your database user

name. Administrators create and publish OCE

files.

personal job parameters Reusable, named job

parameters that are accessible only to the user

who created them.

Personal Pages Your personal window to

information in Hyperion Performance Suite.

You select what information to display, as well

as its layout and colors.

personal recurring time events Reusable time

events that are accessible only to the user who

created them.

properties Information about a file or other

resource. For example, the Name or MIME

Type of a file, or the User ID and Password of a

user. (Also called metadata.)

proxy server A server that acts as an

intermediary between a workstation user and

the Internet to ensure security.

public job parameters Reusable, named job

parameters created by a Hyperion Foundation

administrator and accessible to users who have

the requisite access privileges.

public recurring time events Reusable time events

created by an administrator and accessible

through the access control system.

Page 181: Hyperion 8.3 Developers Guide

Glossary 5

publish To enter a file into the Hyperion

Foundation Repository. The publisher uploads

the file and sets its access control and other

properties.

RSC services The services that are configured

with the Remote Service Configurator. They

include: Repository Service, Service Broker,

Name Service, Event Service, and Job Service.

reconfigure URL URL to enter new servlet

settings when one is logged in.

recurring time event An event that specifies a

starting point and the frequency to run a job.

register See publish

Repository The file system and database where

Hyperion Performance Suite content and

metadata are stored.

resources Objects or services that the system

manages. Examples of a resource include a role,

user, group, file, job, Publisher Service, and so

on.

role A construct that defines the access

privileges granted in order to perform a

business function; for example, the job

publisher role grants the privilege to run or

publish a job.

schedules Specify the job you want to run, as

well as the event schedule and job parameter list

for running the job.

security platform A framework providing the

ability for Hyperion applications to use external

authentication and single sign-on using the

security platform driver.

services Resources that provides the ability to

retrieve, modify, add, or delete business items.

Some Hyperion Foundation services are:

Authorization, Authentication, Global Service

Manager (GSM).

servlet A piece of compiled code executable by a

web server. In Hyperion Foundation, the

servlets are Browse, Personal Pages, Job

Manager, View Manager, Administration, Data

Access, and iHTML.

Servlet Configurator A software utility for

configuring all the locally installed servlets.

shortcut A link to an item elsewhere in

Hyperion Foundation. Create a shortcut when,

for example, you want to display an item in

folder A, though it is stored in folder B.

single sign-on The ability of an externally

authenticated user to access multiple, linked

Hyperion applications after logging on only to

the first application.

SmartCut A link to an item in Hyperion

Foundation, in the form of a special URL.

SPF files Printer-independent files created by

the SQR server that contains a representation of

the actual formatted report output, including

fonts, spacing, headers, footers, and so on.

SQR A specialized programming language for

data access, data manipulation, and reporting.

subscribe To register an interest in an item or

folder, in order to receive automatic

notification whenever the item or folder is

updated.

Page 182: Hyperion 8.3 Developers Guide

6 Glossary

super service A special service used by the

startCommonServices script to start the RSC

services.

time events Triggers for execution of jobs.

token An encrypted identification of one valid

user or group existig on an external

authentication system.

transparent login A mechanism that allows users

who have been previously authenticated by

external security criteria to log in to Hyperion

Performance Suite, bypassing the login screen.

trusted password A password that allows users

who have been previously authenticated in

another system to have access to other

applications without entering a password.

trusted user A user authenticated by some

mechanism in the environment.

URL An address used by a web browser to find

web pages.

user A Hyperion Performance Suite account

owner identified by a user ID, user name, and

password. A user is created in, and managed by,

an authentication system.

variable A value that can be modified when you

run a report.

web client Intelligence plug-in product that

enables users to create queries, analyze data, and

create reports through a browser.

web server Software or hardware hosting

intranet or Internet web pages or web

applications. In the Foundation User’s Guide,

this term often refers to the Hyperion

Performance Suite servlets’ host, because in

many installations, the servlets and the web

server software reside on a common host. This

configuration is not required, however; the

servlets and the web server software may reside

on different hosts.

ws.conf A configuration file for Windows

platforms.

wsconf_platform A configuration file for UNIX

platforms.

Zero Administration A software tool that

identifies the version number of the most up-to-

date plug-in on the server.

Page 183: Hyperion 8.3 Developers Guide

Index

A

AbsoluteTimeEvent Interface, 2-2

Accessor Control Statement, 3-4

AddGroup.java sample, 4-7

AddLink.java sample, 4-8

AddObjectType.java sample, 4-8

AddOCEDocument.java sample, 4-8

AddRole.java sample, 4-9

AddSPF.java sample, 4-9

AddSubscription.java sample, 4-10

AddUser.java sample, 4-10

AddVersions.java sample, 4-11

APIs, session management, 9-7

audience for this guide, xi

Authentication Interface, 2-2

Authorization Interface, 2-2

AutoZip.java sample, 4-11

B

BaseObject Interface, 2-2

batch driver program

control statement attibutes, 3-3

Batch Driver sample program

accessor control statement, 3-4

BQY control statement, 3-11

category control statement, 3-6

control statements, 3-2

date control statement, 3-8

group control statement, 3-5

OCE control statement, 3-9

user control statement, 3-7

Batch Driver Tutorial, A-7

batch file

to compile sample programs, A-5

to run sample programs, A-4

BatchDriver.java sample, 4-12

BQY Control Statement, 3-11

BQYDocument Interface, 2-3

BQYJob Interface, 2-3

C

case-sensitivity of URLs, 8-2

categories. See folders

Category Control Statement, 3-6

Category Interface, 2-4

CategoryDelete.java sample, 4-12

Classes, 2-11

Collection Interface, 2-4

compiling

Login sample program, A-6

sample programs, A-3

use batch file to, A-5

conditional elements in templates, 5-6

configuring extended services, 9-2

consulting services, xviii

Control Statement

Accessor, 3-4

Page 184: Hyperion 8.3 Developers Guide

2 Index

BQY, 3-11

Category, 3-6

Data, 3-8

defined, 3-2

Group, 3-5

OCE, 3-9

User, 3-7

control statements

attribute, 3-3

Custom Calendar Interface, 2-4

D

dashboards

example, 8-18

example code, 8-19

from web applications, 8-18 – 8-22

Data Control Statement, 3-8

database, connectivity, 8-9

DataObject Interface, 2-4

“dbuser” variable, 8-9

DHTML templates, list of, 5-6

disabling template caching, 5-2

documents

conventions used, xvii

feedback, xix

ordering print documents, xvii

structure of, xi

documents, accessing

Hyperion Download Center, xvi

Hyperion Solutions Web site, xvi

Information Map, xvi

online help, xvi

drill-down reports, 8-2

E

editing templates, 5-14

education services, xviii

elements

templates, 5-4 – 5-6

e-mail. See notifications

example code for integration, 8-19

exceptions, Java, 1-4

execapi.bat, A-4

ExecuteBQYDocument.java sample, 4-14

ExecuteBQYJob.java sample, 4-14

ExecuteSQRJob.java sample, 4-15

ExpirationDate.java sample, 4-15

extended services

aggregating parameters, 9-6

configuration file, 9-2

configuring, 9-2

displaying output on Personal Pages, 9-7

local resource management by, 9-6

session token used by, 9-6

URLs for, 9-3, 9-6

ExternallyTriggered Event Interface, 2-5

F

FetchCategory.java sample, 4-15

FetchDocument.java sample, 4-16

file size, templates, 5-5

folders

listing contents, 8-10

listing folders and subfolders, 8-10

framesets in HTML files, 8-10

G

Group Control Statement, 3-5

Group Interface, 2-5

H

home page access to Hyperion Performance Suite, 8-18 – 8-22

HTML editors, for templates, 5-4

Hyperion Consulting Services, xviii

Hyperion Download Center

Page 185: Hyperion 8.3 Developers Guide

Index 3

accessing documents, xvi

Hyperion Education Services, xviii

Hyperion Performance Suite connection, validating, A-2

Hyperion product information, xviii

Hyperion Solutions Web Site

accessing documents, xvi

Hyperion support, xviii

Hyperion Technical Support, xix

I

images

in e-mail notifications, 7-11

where stored, 8-19

.imp files, 5-4

importing template contents, 5-4

importing the SDK package, 1-2

INPUT parameters

in SmartCuts, 8-9 – 8-10

installation directory, 8-21

installation, installed servlets, 9-7

installing Hyperion Performance Suite SDK, A-2

installing the Java Compiler, A-4

InstancePermission Interface, 2-5

integrating intranets or web with, 8-18

Interfaces, 2-2

intranet access to Hyperion Performance Suite, 8-18 – 8-22

invoking Hyperion Performance Suite Services, 1-3

J

Java compiler, installing, A-4

Java exceptions, 1-4

JavaScript, servlet templates, listed, 5-6

job execution, run SmartCut, 8-8

Job Interface, 2-6

JobOutput Interface, 2-6

JobParameter Class, 2-11

jobs

executing, 8-8

run URL SmartCut, 8-8

JSP, 6-4

JSP Directory, 6-2

JSP Pages

Access Control Widget, 6-11

Actions, 6-27

Advanced Login Page, 6-6

Advanced Options Widget, 6-10

BQY Jobs, 6-24

Browse Listing Page, 6-6

Create Externally Triggered Event Page, 6-20

Create Recurring Event Page, 6-18

Creating Events, 6-14

Cycles, 6-24

Days To Run, 6-19

Define Cycle Widget, 6-25

General Properties Page, 6-22

General Widget, 6-9

Generic Jobs, 6-28

Login Page, 6-5

Manage Events Page, 6-17

Manage Jobs Page, 6-16

Modify BQY Document Properties Page, 6-14

Modify File Properties Page, 6-9

Notification Page, 6-29

OCE File Widgets, 6-13

Scheduling Information Page, 6-22

Select Job Parameters, 6-23

Set Values, 6-26

Set Values Page, 6-24

SQR Jobs, 6-28

Time To Run, 6-19

Version Widget, 6-12

Viewing Documents, 6-4

When to Run Page, 6-29

Page 186: Hyperion 8.3 Developers Guide

4 Index

K

kiosk example code, 8-19

kiosk-like access, 8-18 – 8-22

L

linking

extranet, 8-18 – 8-22

with SmartCuts, 8-2

list URL, 8-10

listAll URL, 8-11

ListEvents.java sample, 4-16

ListGroups.java sample, 4-16

listIndex URL, 8-10

listNav URL, 8-10

ListUsers.java sample, 4-17

Logger Class, 2-11

Login.java sample, 4-17

looping elements, in template elements, 5-6

M

memory, templates and, 5-6

Modifying, 6-8

N

NestedGroups.java sample, 4-17

notification.properties file, 7-7

notifications

e-mail

customizing, 7-2

images in, 7-11

notification.properties file, 7-7

properties in Administration module, 7-2

templates for, 7-3

templates’ replacement tokens, 7-4

types of, 7-2

O

ObjectDump.java sample, 4-18

ObjectDumpById.java sample, 4-18

ObjectID Interface, 2-6

ObjectType Class Interface, 2-12

Obtaining a Session Interface, 1-3

OCE Control Statement, 3-9

OCEDocument Interface, 2-7

P

ParameterList Interface, 2-7

parent folders, 8-10

pass variable, 8-2 – 8-3

PhysicalResource Interface, 2-7

prerequisites for using this guide, xi

PublishEvent.java sample, 4-18

PublishOutputDirectory.java sample, 4-19

PublishPrinterResource.java sample, 4-19

Q

Query Interface, 2-8

QueryGroup.java sample, 4-19

QueryUser.java sample, 4-20

QueryVector Interface, 2-8

R

RecurringTimeEvent Interface, 2-8

ReplaceObject.java sample, 4-20

report surfing, 8-2

ReportMartEntity Interface, 2-9

ReportMartException Class, 2-13

reports. See jobs, SQR jobs

Respository Interface, 2-9

run URL, 8-8

S

Sample, 4-1

Page 187: Hyperion 8.3 Developers Guide

Index 5

Samples, 4-4

AddBQYDocument, 4-5

AddBQYJob, 4-5

AddCategory, 4-5

AddDocument, 4-6

AddExternalLink., 4-7

AddFavorites, 4-7

AddGroup, 4-7

AddLink, 4-8

AddObjectType, 4-8

AddOCEDocument, 4-8

AddRole, 4-9

AddSPF, 4-9

AddSubscription, 4-10

AddUser, 4-10

AddVersions, 4-11

AutoZip, 4-11

BatchDriver, 4-12

CategoryDelete, 4-12

ExecuteBQYDocument, 4-14

ExecuteBQYJob, 4-14

ExecuteSQRJob, 4-15

ExpirationDate, 4-15

FetchCategory, 4-15

FetchDocument, 4-16

ListEvents, 4-16

ListGroups, 4-16

ListUsers, 4-17

Login, 4-17

NestedGroups, 4-17

ObjectDump, 4-18

ObjectDumpById, 4-18

PublishEvent, 4-18

PublishOutputDirectory, 4-19

PublishPrinterResource, 4-19

QueryGroup, 4-19

QueryUser, 4-20

ReplaceObject, 4-20

SQRParms, 4-20

table listing all, 4-4

ScheduledTask Interface, 2-9

Scheduler Interface, 2-10

Scheduling, 6-20

SDK

importing the package, 1-2

installing Hyperion Performance Suite, A-2

steps to deploy, 1-2

server variable, 8-2 – 8-3

services.properties file, 9-2

Servlet Configurator, disabling template caching, 5-2

servlets

customizing templates, 5-2

and memory, 5-6

templates

elements of, 5-4 – 5-6

importing contents, 5-4

Session Interface, 2-10

session interface, obtaining, 1-3

session management API, 9-6

session token. See extended services

SessionFactory Class, 2-13

SmartCuts

See also URLs

accessing the system from web applications, 8-18 –8-22

list, 8-10

listAll, 8-11

listIndex, 8-10

listNav, 8-10

run, 8-8

uses for, 8-2

variables for BQY documents and jobs, 8-12

SPFSet Interface, 2-10

SQR jobs

retrieving output, 8-5 – 8-7

SQRJob Interface, 2-10

SQRJobOutput Interface, 2-11

SQRParms.java sample, 4-20

Page 188: Hyperion 8.3 Developers Guide

6 Index

start, 5-5

Supporting Classes, 4-21

T

technical support, xix

templates

caching of, disabling, 5-2

customizing, 5-2 – 5-6

editing, 5-14

elements of, 5-4 – 5-6

for e-mail notification, 7-2

end tags, 5-5

HTML templates in servlets, 5-2

importing contents, 5-4

JavaScript, 5-6

listed, 5-6

modifying, 5-4

start tags, 5-5

start-end tags, 5-5

testing, 5-3 – 5-4

testing

modified templates, 5-4

templates, 5-3

to compile sample programs, A-5

troubleshooting memory consumption, 5-6

U

UnknownReportMartException Class, 2-13

URLs

See also SmartCuts

case-sensitivity, 8-2

SmartCuts, 8-2

User Control Statement, 3-7

User Interface, 2-11

user variable, 8-2 – 8-3

UserValidationException Class, 2-14

V

validating the Hyperion Performance Suite connection, A-2

W

web, integrating the system with, 8-18

wsmedia/personalize directory, 8-19