hfm api deep dive – making a better financial management client

HFM API Deep Dive Making a Better Financial Management Client

Charles Beyer

Build a “complete” .NET App for HFM API● “Brief” HFM API Overview● Prepare a Development Environment● Coding your own HFM Client App● Improving on Client App● Tips, Tricks, and Warnings

3rd Party Tools / Projects Q & A

Session Objectives / TOC

Code Samples will be made available To expedite certain areas, we will utilize screen

shots while doing live demos in others Slides / Demos should be sufficient to do work

offline in case we bump into time issues Please leave feedback!

Additional Notes

Computer & Technology ‘Nerd’ – Started with a Apple II and TRS-80. Haven’t looked back.

16+ years professional software experience, created and sold commercial software.

7 years working with Hyperion products.

Love to help out, feel free to ask and I’ll help if time permits!

About the Speaker

“Brief” HFM API Overview

Three Main APIs● COM [Primary Focus for Session]

● Updated for 11.1.2.2 for expanded dimensionality● Extended Analytics HTTP Listener

● Web Object Model [ADF Webinar – TBD]● 11.1.2.1 and prior : Components Utilized via ASP pages● 11.1.2.2+ : Java/J2EE implemented with Oracle ADF

Framework

● FM Web Service [TBD]● Optional, now required, component first utilized by

Financial Close Management● Behind the scenes is really the COM library.

Brief HFM API Overview

Brief HFM API Overview [COM]Web 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

Brief HFM API Overview [COM]

Type File Functionality

HfmSliceCOM Support for Configurable Dimensionality

HsxClient Logon/Logoff, Open/Create/Delete Applications

HsxClientUI User Interface for Logon/off, Open/Create/Delete Applications

HsxServer App Server info : Application Names, DSNs

HsvSession Parent Obect to Metadata & Data, Session Related Info

HsvMetadata Metadata Related Functions

HsvData Sets and Gets data in cells

HsvCalculate Executes consolidations, translations, and calculations

HsvJournals Manage periods, create journals and templates, process journals

HsvSecurityAccess Get/Set Application’s users, roles, and security class access.

Brief HFM API Overview [COM]

Type Library Functionality

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

HsvDQI “Intelligent” Data Retrieval

HsvStarSchemaACM Extended Analytics

HsvSecurityLoadACV Security Loading and Extracting

HsvMetadataLoadACV Metadata Loading and Extracting

HsvRulesLoadACV Rules Load and Extracting

Brief HFM API Overview [COM]

Type Library Functionality

HsvcDataLoad Data Loading and Extracting

HsvJournalACV Journal Loading and Extract, Journal Template loading

HsvPOVSelection ActiveX display option for selecting POV

HsvResourceManager Manages Error Messages

HFMConstants Constants used by API calls throughout

Brief HFM API Overview [HTTP Listener]

URL: http://<web server>/hfm/EIE/EIEListener.asp?

app_name=<HFMAppName>&action=launch_EA_extract Include following data in header

● SSO Token● Content Type : text/xml

HTTP Request Stream Parameters● Application Name● Extract Type● Push Options

Brief HFM API Overview [HTTP Listener]

HTTP Request Stream Parameters (cont)● DSN● Prefix● ExcludeDynamicAccounts● Scenario(s)● Year(s)● Period(s)● View(s)● Entity(ies)

Brief HFM API Overview [HTTP Listener]

HTTP Request Stream Parameters (cont)● Entity(ies)● Value(s)● Account(s)● ICP(s)● Custom1(s)● Custom2(s)● Custom3(s)● Custom4(s)

XML Response Message returned

Prepare a Development Environment

Requirements [COM]● HFM Client Installed● Server Files Available

● Copied Locally● Read only access to files on remote location (i.e. server)

● Microsoft Visual Studio● Deployment / Installer Notes

Prepare a Development Environment

Create Installer (Required Assemblies, 11.1.2.x)● commonComponents● productCommonComponents● hfm_client● hfm_common

Launchtool.cmd to start installation process Select choose individual components

● Financial Management: Client, ADM Configure Cluster / Services / DCOM Start Client and perform test connection

Install HFM Client (11.1.2.x)

Server Files Default Location● <EPM_HOME>\products\FinancialManagement\

Server● <EPM_HOME> = C:\Oracle\Middleware\EPMSystem11R1\

System11R1

Copy them local or Reference them direct from server.● If referencing, be sure to include in your app’s

installer so that they copy!

Locate (and Copy) Server Files

Express 2012 for Windows Desktops● http://www.microsoft.com/visualstudio/eng#products/

visual-studio-express-for-windows-desktop+product-express-desktop

Requirements● O/S : Win7 SP1, Win 8, Server 2008, Server 2012● Hardware : 1Ghz CPU, 1GB RAM, 5GB Disk, DX9

NOTES: ● Links change semi-frequently so Google Visual

Studio Express and you won’t go wrong.● As new versions are released old versions are

retired.

Visual Studio (2012)

Installation● Click the Download button on website● Use default settings for file locations, etc.● When it comes to installing option components, I

generally install them.● MSDN Document Library is up to you.

If you don’t meet requirements for 2012● 2010 ISO :

http://download.microsoft.com/download/1/E/5/1E5F1C0A-0D5B-426A-A603-1798B951DDAE/VS2010Express1.iso

● 2008 ISO : Retired, though on torrents*

Visual Studio (2012)

HFM Client App

Open / Close Applications, Logoff Explore Data, User Preferences, Database

Management Setup / Process Journals Define App Profile, Create/Delete App, Manage

Metadata Load Security, Metadata, Member Lists, Rules,

Data, Journals

HFM Client App Functionality

Coding Your Own Client App

Visual Studio Project Creation Adding References to Files Recreate Existing Functionality

● Authentication [Demo]● Opening / Closing Apps [Demo]● Extracting Metadata, Rules, Data [Demo]

Coding Your Own Client App

Create Visual Studio Project

Adding References

Shared Objects

Authentication [Demo]

Opening Application [Demo]

Logoff [Demo]

Extract Metadata [Demo]

Add References Create Standalone Form Wire up Buttons : File Browser, View (Notepad),

Check All, Uncheck All, Extract Implement API Extract Logic for Metadata

Extract Metadata - References

Extract Metadata – Create Form

Extract Metadata – Wire Buttons

Extract Metadata – Wire Buttons

Extract Metadata – Wire Buttons

Extract Metadata – API Logic

Extract Metadata – API Logic

Extract Metadata – API Logic

Extract Metadata – API Logic

Improving on the Client App

App Title / Statusbar Updates [Demo] Dynamic Menu [Demo] Admin / System Info [Demo] Smarter Metadata / Rules Extracting/Loading

[Demo]

Improving on the Client App

App Title / Statusbar Updates [Demo]

App Title / Statusbar Updates [Demo]

Menu Control [Demo]

Menu Control [Demo]

Menu Control [Demo]

System Info [Demo]

System Info [Demo]

Tips, Tricks, and Warnings

Be sure to work in Dev first! ● Some API calls could cause trouble if used

incorrectly!● Easier to Debug ● Can Run Additional Debug/Performance Tools

Start small and test frequently Use Debug functionality to step through code Trap exceptions to handle errors gracefully! Create Installer for your finished product

Tips, Tricks, and Warnings

COM API Doc & Samples● http://docs.oracle.com/cd/E17236_01/epm.1112/hfm

_developer_11.1.2.2.300.pdf● SDK via e-delivery for additional code samples

Web API Doc & Samples● Web API

● Pre-11.1.2.2 : http://docs.oracle.com/cd/E17236_01/epm.1112/hfm_websdk.pdf

● 11.1.2.2+ : http://docs.oracle.com/cd/E17236_01/epm.1112/hfm_custom_pages_development.pdf

Tips, Tricks, and Warnings

Web Service● No Docs Yet!● Access ASMX pages in browser to view information!

[http://<your web server>/hfmapplicationservice/] Utilize existing resources for help!

● Oracle Forum (http://forums.oracle.com)● Blogs

● Mine (new) : http://www.charlescbeyer.com● Finnish Hyperion Guy : http://hyperionfinn.blogspot.com/● SlideShare / Google : Tons of Info is out there.

Tips, Tricks, and Warnings

Web Service isn’t officially published● May go away at any time?

Great Training Material for Learning .NET● http://www.microsoftvirtualacademy.com/● http://msdn.microsoft.com/en-US/vstudio/cc136611

Tips, Tricks, and Warnings

3rd Party Tools / Projects

HFM Batch & hfmCMD by Adam Gardiner● C# Command Line Implementations of API

functionality. ● Batch : https://github.com/agardiner/hfm-batch● hfmCMD : https://github.com/agardiner/hfmcmd

EPM Maestro : http://epmmaestro.com/ Accelatis : http://www.accelatis.com/ Star Analytics :

http://staranalytics.com/products/

3rd Party Tools / Projects

Charles Beyercharles@charlescbeyer.com

Glenview, IL

USA

+1.847.275.6317

Questions?

Bloghttp://www.charlescbeyer.com

LinkedInhttp://www.linkedin.com/in/charlesbeyer

Twitter

https://twitter.com/beyerch

Oracle Forums

beyerch2

Source Codehttp://www.charlescbeyer.com/Kscope/HFM_Client_V2.zip