#Kscope

APIs Getting Added Value From HFM, Workspace, FDM, Smartview, and Shared Services

Charles Beyer

Troubleshooting steps for diagnosing HFM, Workspace, and FDM

#Kscope

About the Speaker

● 15+ years professional development experience in various languages/technologies (6 years w/ Hyperion products)

● Independently released commercial software products

● Loves to help others solve problems● Posts under beyerch2 on OTN Discussion

Boards

#Kscope

Before we Begin…..

● Code Samples for all examples are at end of powerpoint (Download latest version!)

● To expedite session, we will use both screen caps and live demos

● ‘All-in-one’ Virtual Machine created for session, available upon request*

● If we hit time limit, there is enough shared information that most should be able to perform remainder of samples

#Kscope

Session Goals

● Gain High Level Exposure to Select EPM API Libraries

● Recognize Added Value of APIs● DO NOT FEAR APIs, They Are Your Friend!

#Kscope

Development Challenges

● Out Of The Box (OOTB) product functionality is rarely a perfect fit● Custom Workflow Requirements from Client● Missing/Incomplete Product Functionality

● Limited Development Resources● Tight Deadlines● Limited Budgets for Custom Development

● Steep Learning Curves● Difficult to Master Continually Evolving Software● Introduces Software Defects

#Kscope

APIs to the Rescue!

● Enables Extensibility of Product● Alleviates Development Pressures

● Lessens Development Time and Cost● Simplifies Learning Curve● Minimizes Defects

● ‘Future’ Proofs Your Work● Grows Hair Back*● Solves Economy Problems● Extends Lifespan (yours)*

*Not evaluated by FDA

● Minimizes Development of Out Of The Box (OOTB) functionality isn’t an exact fit● Custom Requirements at Client● Missing Functionality from Product

● Limited Resources (Time / Money)● Why Reinvent the Wheel?

● Backwards / Forwards Compatibility

#Kscope

What exactly is an API?

What● Set of standard function

calls / procedures with well defined inputs and outputs that abstract complex logic from developers (i.e. Black Box)

#Kscope

What APIs are available?● Virtually all EPM products have an API available, though we will focus on:● HFM● FDM● Smart View● Workspace● Shared Services

#Kscope

HFM API

#Kscope

API Overview - HFM● Two Major API Libraries● Web Object Model – Web Server Components used

by ASP web pages● COM Components – Primarily Used to talk to

Application Server Tier. Typically interfaced in VB6, .NET application, though any language that supports COM can make use.

● Offer similar functionality with few exceptions such as Consolidations (COM), Document Library (Web)

#Kscope

API Overview – HFM (cont.)

● Pre-Requisites ● Web Object Model

● Execute Code on HFM App Web Server

● COM Object Model● HFM Client Installed on Computer● Install FM App Server Files to Local Machine –or- have

read only access to files

● HFM API TIP● Get the SDK!

(http://www.oracle.com/technetwork/middleware/financial-management/overview/index.html)

#Kscope

API Overview – HFM (cont.)

● Sample Programs● HFM Client Utility Improvement – Multi Data Export ● Command Line / Scheduled Task (VBS) ● HFM-Batch

● C# Command Line Implementation of common API features by Adam Gardiner

● https://github.com/agardiner/hfm-batch

Note : If you do not own Visual Studio, there are free versions available. (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express)

#Kscope

HFM API DEMO

HFM CLIENT IMPROVEMENT

#Kscope

HFM CLIENT IMPROVEMENT

#Kscope

HFM CLIENT IMPROVEMENT (cont)

#Kscope

HFM CLIENT IMPROVEMENT (cont)

#Kscope

HFM CLIENT IMPROVEMENT (cont)

=

#Kscope

HFM CLIENT IMPROVEMENT (cont)

=

#Kscope

HFM CLIENT IMPROVEMENT (cont)

=

#Kscope

FDM API

#Kscope

API Overview - FDM● One Object Model (COM), Multiple Ways to Access● FDM Scripts – Primary (Import, Custom, Event)● External Program (Client or Server) in any language

supporting COM

#Kscope

API Overview – FDM (cont.)● Pre-Requisites● Execute Code from FDM Server

-OR-● Install FDM Workbench on Computer● Either Install FDM Application Server Files or Have

Read Access to File System With Files

#Kscope

API Overview – FDM (cont.)

● Samples● Export All Dimension Maps to

Excel by Location● Show Children Locations for

Selected Location

● Tip● Don’t forget about Accelerators!

#Kscope

FDM API DEMO

Export All Dimension Maps to Excel by Location

#Kscope

FDM Map Export

#Kscope

FDM Map Export (cont)

#Kscope

FDM Map Export (cont)

#Kscope

FDM Map Export (cont)

#Kscope

FDM Map Export (cont)

#Kscope

FDM Map Export (cont)

#Kscope

FDM Map Export (cont)

#Kscope

Smart View API

#Kscope

API Overview – Smart View● API Functions Available From Inside of Smart View Documents● COM libraries used behind the scenes● Smartview.BAS in <HYPERION_HOME>\SmartView\

Bin has definitions of all calls, constants, etc.● Theoretically could utilize libraries outside of Excel,

but have not attempted

#Kscope

API Overview – Smart View (cont.)● COM Object Model● Object Model Libraries

● HsAddin.dll – Kitchen Sink Library

● Pre-Requisites● Smart View Installed

● Samples● Auto Create Connection String in Connection

Manager

#Kscope

Smart View API DEMO

Auto Create Connection String

#Kscope

Smart View Auto Create Connection

While Shared Connections – Minimize this, not all Smart View versions have functionality or is it being implemented everywhere.

Would be nice to have everything to make your SV file work, in the file …..

#Kscope

Smart View Auto Create Connection (cont)

#Kscope

Smart View Auto Create Connection (cont)

#Kscope

Smart View Auto Create Connection (cont)

Declare References

Check To See If Connection Exists Already

Create Connection

#Kscope

Workspace API

#Kscope

API Overview – Workspace● API Consists of Java Classes/Interfaces Used Either on Command Line or in JSP Pages

● Significant amount of functionality exposed to developers (see table in Appendix)

#Kscope

API Overview – Workspace (cont.)

● Pre-Requisites● SDK Installed● Java Compiler and Runtime Environment Installed● GSM Host Name and Port Number● Access to Core Services Using a URL (i.e.

http://localhost:45000/workspace)● Valid Username and Password with Administrator

Access

#Kscope

API Overview – Workspace (cont.)● Samples● Authenticate to Workspace● NOTE: Samples can be found as part of the SDK

● Sys 11 - <MIDDLEWARE HOME>\EPMSYSTEM11R1\PRODUCTS\BIPLUS\SDK\SAMPLES\JAVA

#Kscope

API Overview – Workspace (cont.)● Gotchas….● ‘Out of the Box’ Scripts do not work per

documentation!● Execapi.bat / JC.bat need tweak

● Files Location : %EPM_ORACLE_HOME%\products\biplus\SDK\bin

● Copy .template versions to .bat● Replace line

● set SET_SDK_ENV = “%INSTANCE…● set SET_SDK_ENV = “set_sdk_env.bat”

#Kscope

API Overview – Workspace (cont.)

#Kscope

API Overview – Workspace (cont.)

#Kscope

API Overview – Workspace (cont.)● Gotchas….● Verify / Add Environment Variables

● EPM_ORACLE_HOME – i.e. C:\ORACLE\MIDDLEWARE\EPMSystem11R1

● EPM_INSTANCE_HOME – i.e. C:\ORACLE\MIDDLEWARE\USER_PROJECTS\EPMSYSTEM1

● JAVA_HOME – i.e. C:\ORACLE\MIDDLEWARE\JDK160_21

#Kscope

API Overview – Workspace (cont.)

#Kscope

Workspace API DEMO

AUTHENTICATE

#Kscope

Workspace API Demo - AuthenticateStep 1 - Compile the program

Step 2 – Execute program

NOTE: Java is case sensitive!

#Kscope

Shared Services (Security) API

#Kscope

API Overview – Shared Services

● Java API Allows for Access to Users, Groups, and Security Access

● Pre-Requisites● Foundation Services are running● Execute program from machine with at least one

EPM System Product● Epm_j2se.jar is added to the CLASSPATH

(EPM_ORACLE_HOME\common\jlib\11.1.2.0\epm_j2se.jar)

#Kscope

API Overview – Shared Services (cont)

● Pre-Requisites● EPM_ORACLE_INSTANCE environment variable is

set (or specified at run-time)● reg.properties file exists. Most likely :

EPM_ORACLE_INSTACE\config\foundation\11.1.2.0● For SAMPLE.java / authenticateSample.java replace

hardcoded placeholders for login / password. (admin/G00gl3)

#Kscope

Shared Services (Security) API DEMO

AUTHENTICATE

#Kscope

Shared Services Demo - AuthenticateStep 1 – Create a Batch File to Compile

Step 2 – Create a Batch File to Execute

#Kscope

Shared Services Demo - AuthenticateStep 1 – Compile Sample.java

Step 2 – Compile AuthenticateSample.java

#Kscope

Shared Services Demo - AuthenticateStep 1 – Execute AuthenticateSample

#Kscope

Shared Services Demo - AuthenticateStep 1 – Execute AuthenticateSample (cont)

#Kscope

Tips and Tricks● Experiment in Development!● If things go wrong, no worries● Easier to debug as you are only user● Can run additional debugging / monitoring tools which

would degrade production performance

● Leverage Existing Code!● HFM Web (ASP), FDM Adapters/Scripts (VBScript),

Shared Services Web (JSP), and Workspace (JSP)

#Kscope

Questions?● If you have any questions with the sample code or presentation, feel free to ask/contact me● charles@charlescbeyer.com

#Kscope

Supplemental Information

#Kscope

API Technology Summary

Figure 1 - Select Hyperion Product API Technology Overview

Product DescriptionUnderlying Technology

Interface Technology

HFM Web Hyperion Financial Management - Web C/C++ ASP

HFM ClientHyperion Financial Management - Client/Server C/C++ VB6 / .NET

FDM Financial Data Quality Management C# VBScript / .NET

Smart ViewSmart View Excel Add-In [Foundation Services] C/C++ VBA

Workspace Hyperion Workspace [Foundation Services] Java .JSP / JAVA

Shared Services

Hyperion Shared Services [Foundation Services] Java .JSP / JAVA

#Kscope

HFM API FeaturesWeb Object Model Features COM Object Model FeaturesLog On / Log Off Log On / Log OffOpen FM Applications Open FM ApplicationsRegister / Unregister Clusters/App Servers Register / Unregister Clusters/App ServersGetting Dimension Attributes Get Metadata AttributesGet / Set Line Item Details Get / Set Line Item DetailsProcess Management Interaction Process Management InteractionOpen / Close Periods Open / Close PeriodsJournals (Create, Delete, Submit, Post, etc.) Process JournalsUser Security (Rights / User Lists) User Security (Rights / User Lists)Document Management (Forms / Grids) Get / Set data for arrays of cells

POV SettingsExecuting consolidations, translations, calculations

Audit Information (Task, Data, etc.)

Load/Extract member lists, metadata, rules, data,and journals

Server Information/Control (Logoff Users, Enable/Disable Connections) Extended Analytics

ActiveX control for dimension members selection

#Kscope

HFM Object Model Summary

Figure 1 - Select Hyperion Product API Technology Overview

Library File FunctionalityHFMwApplications Application and User FunctionsHFMwSession User Connection to ApplicationHFMwMetadata Functions for working with Metadata

HFMwDimension Functions for working with DimensionsHFMwData Data Related Functions

HFMwManageProcess Process Management FunctionsHFMwMbrSel Point of View Functions

HFMwMbrSelDim POV - Member SelectionHFMwDataGrid Data Grid Interfacing FunctionsHFMwDocuments Document Functions

HFMwManageDocuments Managing Document FunctionsHFMwWorkspace Tasklist Related Functions

HFMwSecurity Security Related FunctionsHFMwJournals Journal FunctionalityHFMwSystemInfo System Information and ControlHFMwUtilities Common Utilities (i.e. Strings / Files)HFMwResourceManager Localized strings (i.e. Errors)HFMwConstants Library of CONSTANT values

#Kscope

HFM Object Model Summary

Figure 1 - Select Hyperion Product API Technology Overview

Library File Functionality

HsvMetadata Metadata functions

HsvData Get / Set Data in Application

HsvCalculate Calculations, Consolidations, Translations

HsvJournals Journal functions

HsvSecurityAccess App Security Features

HsvSystemInfo System Items (Get/Set App Name, Server Name)

HsvProcessFlow Process Management

HsvReports System Reports

HsvICM Intercompany

HsvMDArrays Statutory / IC Transactions Data

HsvDataCubes Data Access @ Sub Cube Level

#Kscope

FDM API Features

Features

Log On / Log Off

Open FDM Applications

Create / Delete Application

Register / Unregister Application

Get / Set Application POV

Get / Set Workflow Status

Execute Data Loads, Calc Logic, Mapping Rules

Process Multi-load / Journal Templates

Manage Application Security

Execute Actions (Export, Load, Consolidate, Validate)

Request Member Lists

#Kscope

FDM Object Model SummaryLibrary File FunctionalityupsAppServerDM Container for all API components

upsOBJDMw Primary Business Logic / Data Processing

upsDataWindowDM Data Access, Manipulation, Security

upsWObjEventHandlerDM Event Handling

upsWebScriptDM VB Script Engine / FDM Scripts

upsWBlockProcessorDM Integration Script Execution

upsMPLDMw Multi-load / Journal Processing

upsWStructureMgrDM Hierarchy Management Services

upsMapConverter Specialized Map Conversion

upsWBatchLoaderDM “Lights Out” Processing for Custom Scripts / Task Management Service

upsWDialogsDM Dialog Forms for POV and Global Options

upsWMetaMgr Classified / Undocumented

UpStreamAppMgrW App Config / Authentication

LoadBalanceMgr Load Balancing

upsWReportingDM Active Reports Processing Services

ZipMgrW File Compression

upsEventLog Event Log Writing

#Kscope

Smart View API FeaturesFeatures

General Functions - (As seen on Smart View Ribbon)

Connection Functions - Manage Connections

Ad Hoc - Zooming, Retrieving, Submitting Data, Pivoting

Form Functions

Cell Functions

POV

Calculation Script / Business Rules

Calculation / Consolidation / Translation

Member Query - Generation, Level, Attributes for Members

Options - Global / Sheet Options, MRU Deletion

MDX Querying

Menu - Emulate Ribbon Menu Commands

Dynamic Link - Retrieve Data From Other Open Windows

#Kscope

Workspace API Class SummaryClass Description

Job Parameter Information About Data Parameters

Logger log4j Logging Architecture Methods

ObjectType Extract Built-In Object Types in Workspace

SessionFactory Session Interface for Workspace (Required)

UnknownReportMartException Exception Thrown When Connection Error Occurs

UserValidationException Exception Thrown When User Error Occurs

ReportMartException Exception Thrown During Invocations on Interactive Reporting SDK Package

#Kscope

Workspace API Interface SummaryInterface DescriptionAbsoluteTimeEvent Create Events That Trigger at a Given Time

Authorization Accessing Roles and Listings

Base Object Extends ReportMartEntity

BQYDocument Interactive Reporting Document Information

BQYJob Interactive Reporting Jobs

Category Copy Files/Directories to/from File System to Workspace

Collection Artifacts Associated With Job Output

CustomCalendar Define Calendars

DataObject Get/Set Keyword Lists for HTML, SQL, and CSV Documents

ExternallyTriggeredEvent Define Externally Triggered Event

Group Access Shared Services Group Information

InstancePermission Get/Set Object Permissions

Job Executes Jobs / Handles Output

JobOutput Job Output

ObjectID UUID Reference for Identifying Workspace Objects Uniquely

OCEDocument Interactive Reporting Database Connection

#Kscope

Workspace API Interface SummaryInterface DescriptionParameterList Job Attributes Used During Job Execution

PhysicalResource Printer / Physical Output Methods

Query Searching Workspace

QueryVector Search Results

RecurringTimeEvent Repetitive Event Triggering

ReportMartEntity Attribute Information for all Workspace Artifacts

Repository Used throughout SDK to Obtain Major Interfaces for SDK

Role Get/Set Role Information

ScheduledTask Associate Parameter List with Event

Scheduler Create, Retrieve, List, Delete Event Service Artifacts

Session Primary Interface for Accessing Workspace

SPFSet Output from Job Service Execution of SQR Production Reporting Documents

SQRJob Set/Get “ask” Parameters at Time of Job Execution

SQRJobOutput Job Output from Above

User Get/Set Shared Services User Information

#Kscope

Shared Services API Class Summary

Class Description

com.hyperion.css

Provides classes necessary to create and use security platform

com.hyperion.css.application Provides functionality that Hyperion based applications must implement to use security platform

com.hyperion.css.common Common information elements and information retrieved from directory stores

com.hyperion.css.common.configuration Access to application configuration information

#Kscope

Sample Files

#Kscope

Sample Files - HFM

Wscript HFM Sample.zip HFM Batch Sample Script.zip Advanced Data Export WIP.zip

#Kscope

Sample Files - FDM

ExportExcelAll.uss ShowChildren.uss

#Kscope

Sample Files – Smart View

RateSheet_smartview.zip

#Kscope

Sample Files - Workspace

Execapi.bat set_sdk_env.bat Jc.bat

Login.java SampleLogin.java

#Kscope

Sample Files – Shared Services

AuthenticateSample.zip