weblink dm guide to adaptors

Hyperion® System™ 9 Financial Data Quality Management™

Guide to Adaptors

Hyperion FDM 9.2.0

© 2000 – 2006 - Hyperion Solutions Corporation. All rights reserved. “Hyperion,” the Hyperion logo and Hyperion’s product names are trademarks of Hyperion. No portion hereof may be reproduced or distributed 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 licensee’s personal use, without the express written permission of Hyperion. This software is licensed according to the conditions set forth in your Hyperion software license agreement.

Hyperion, LedgerLink, Hyperion Enterprise, and Essbase are registered trademarks of Hyperion Solutions Corporation.

Hyperion Solutions, Hyperion Planning, and Hyperion Financial Management are trademarks of Hyperion Solutions Corporation.

Citrix is a registered trademark of Citrix Systems Inc.

Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

i

Table of Contents

Module 1 - AdAptors overview

About AdAptors ............................................................................................................................................... 1-1AdAptor CoMponents ....................................................................................................................................... 1-1

AdAptor dLL/EXE .......................................................................................................................................................... 1-1AdAptor XML ................................................................................................................................................................. 1-1

integrAtion with the tArget AppliCAtion ........................................................................................................... 1-2

Module 2 - integrAting with the tArget AppliCAtion

integrAtion overview ....................................................................................................................................... 2-1integrAtion proCedure ..................................................................................................................................... 2-1

1. Log into thE hypErion FdM AppLicAtion viA thE WorkbEnch ........................................................................................ 2-22. iMport thE tArgEt SyStEM AdAptor ............................................................................................................................ 2-33. rEgiStEr thE AdAptor ................................................................................................................................................ 2-54. Add MAchinE proFiLE .................................................................................................................................................. 2-65. UpdAtE dcoM SEttingS ............................................................................................................................................. 2-76. MAp hypErion FdM diMEnSionS to tArgEt diMEnSionS ................................................................................................ 2-97. Log onto thE hypErion FdM AppLicAtion viA WEb cLiEnt .......................................................................................... 2-128. vEriFy AppLicAtion SEttingS...................................................................................................................................... 2-139. UpdAtE intEgrAtion SEttingS .................................................................................................................................... 2-1410. tESt thE intEgrAtion SEttingS ................................................................................................................................. 2-16

Module 3 - Current integrAtion AdAptors

hyperion hFM AdAptors .................................................................................................................................. 3-1F3d-1 ............................................................................................................................................................................ 3-1F3E ................................................................................................................................................................................ 3-1F3F ................................................................................................................................................................................ 3-1F3g ............................................................................................................................................................................... 3-1F3h ................................................................................................................................................................................ 3-2F3J ................................................................................................................................................................................ 3-2F3i ................................................................................................................................................................................. 3-2F3i-1 .............................................................................................................................................................................. 3-2F3k-1 ............................................................................................................................................................................. 3-2F3J-2 ............................................................................................................................................................................. 3-3hFM4X-A ....................................................................................................................................................................... 3-3hFM4X-A1 ..................................................................................................................................................................... 3-4hFM4X-b ....................................................................................................................................................................... 3-5hFM4X-bg2................................................................................................................................................................... 3-6hFM4X-cg2 .................................................................................................................................................................. 3-7hFM4X-dg2 .................................................................................................................................................................. 3-9hFM4X-E1g2 ................................................................................................................................................................ 3-9hFM4X-Fg2 ................................................................................................................................................................. 3-10hFM4X-gg3 ................................................................................................................................................................ 3-10

Current hyperion essbAse/plAnning AdAptors............................................................................................... 3-11E65A .............................................................................................................................................................................3-11

ii

ESS6X-F .......................................................................................................................................................................3-11ESS6X-h .......................................................................................................................................................................3-11ESS7X-A .......................................................................................................................................................................3-11ESS7X-A1 .................................................................................................................................................................... 3-12ESS7X-A4 .................................................................................................................................................................... 3-12ESS7X-b ...................................................................................................................................................................... 3-12ESS7X-d ...................................................................................................................................................................... 3-12ESS7X-E ...................................................................................................................................................................... 3-13ESS7X-F1 .................................................................................................................................................................... 3-14ESS7X-gg3 ................................................................................................................................................................. 3-16SEtUp itEMS to conSidEr ............................................................................................................................................... 3-16

Current hyperion enterprise AdAptors ......................................................................................................... 3-17hEt6X-A ...................................................................................................................................................................... 3-17hEt6X-b ...................................................................................................................................................................... 3-17hEt6X-c ...................................................................................................................................................................... 3-17hEt6X-d ...................................................................................................................................................................... 3-18hEt6X-E ...................................................................................................................................................................... 3-18hEt6X-F ...................................................................................................................................................................... 3-19hEt6X-gg3 ................................................................................................................................................................. 3-19SEtUp itEMS to conSidEr ............................................................................................................................................... 3-20diMEnSion cAchE ........................................................................................................................................................... 3-20

Module 1 - AdAptors overview

1-1

Module 1 — Adaptors Overview

About AdaptorsAdaptors are predefined software codes that understand how to communicate with various source/target applications. Each adaptor has been programmed to integrate with a specific source (SAP, SQL, etc) or target system (Essbase, HFM, etc). These adaptors compromised of a two components the DLL/EXE and XML metadata. The DLL/EXE contains the system specific instructions for interacting with the target or source system. The XML contains all data relating to the Hyperion FDM application that is being integrated.

Adaptor ComponentsAdaptor DLL/EXEThe Adaptor DLL/EXE acts as a buffer between the Hyperion System 9 Financial Data Quality Management (Hyperion FDM) program and the target application. The DLL/EXE contains all of the instructions for Hyperion FDM to communicate with the specified target or source application such as connecting to the database, loading data, extracting data, etc. Each Adaptor DLL contains the API calls for the specific target or source application. This allows Hyperion FDM to be flexible to integrate with many target systems and not have to maintain large amounts of application specific calls within the program itself.

Adaptor XMLThe Adaptor XML acts as a second layer between the Hyperion FDM program and the target application. The XML stores application setup parameters/options, pre-defined scripts to call API functions and return the desired data/results from the target application.

DimensionsThe Dimensions section contains all of the available dimension lists for the target application. Each item under the main Dimension section represents one available dimension and contains a script that retrieves a list of all members in the selected dimension from the target application. These member lists are provided to Hyperion FDM. Dimensions are only included in Target Adaptors not in Source Adaptors.

ActionsPre-defined scripts that interact with the target application and use the Integration Adaptor DLL’s API calls to perform such functions as: Connect, Load, ValueGet, Export, etc.

Machine ProfileThe machine profile contains all of the information to allow Hyperion FDM to determine on what computers/servers the source & target databases are located. The machine profile also stores global logon information for connecting to the target application.

Note: When the Global Login option is selected, Hyperion FDM will always use this username and password to logon to the target application server / target application. This means that this user account must have access to the target application server and must have the appropriate security privileges in the target application for Hyperion FDM to load and retrieve values to and from the target application, regardless of the user who is logged into Hyperion FDM.

A machine profile must be setup for every computer that has the Hyperion FDM Application Server or the Hyperion FDM Task Manager installed. However the only fields that must be filled out are: Target Machine, Source Machine, & Domain (Domain may be entered as NA if you are not using the global login ID).

Hyperion FDM Guide to Adaptors

1-2

OptionsThe options section of the XML file contains the default options for the integration settings and application settings within Hyperion FDM for the specific target application that you are integrating with. When options are changed from within Hyperion FDM they are stored in the options section.

Integration with the Target ApplicationIntegration settings are used to point a Hyperion FDM application to the target application. The target application is the application to which you want to load data. Hyperion Enterprise®, Hyperion Essbase ® and Hyperion Planning® and Hyperion Financial Management® (HFM) are examples of valid target applications. Detailed procedures for setting up integration adaptors are included in subsequent modules in this guide.

Module 2 - integrAting with the tArget ApplicAtion

2-1

Module 2 — Integrating with the Target Application

Integration OverviewIntegration settings are used to point a Hyperion FDM application to the target application. The target application is the application to which you want to load data. Hyperion Enterprise, Hyperion Financial Management (HFM), and Hyperion Essbase are examples of valid target applications.

Integration ProcedureThe process of integrating with the target application is competed from within the Hyperion FDM Workbench client.

Procedure – IntegratIng new aPPlIcatIon wIth target aPPlIcatIon

1. Log into the Hyperion FDM application via the Hyperion FDM Workbench

2. Import the target system adaptor

3. Register the adaptor

4. Add machine profile

5. Update DCOM launching user rights (Enterprise and Essbase only)

6. Map Hyperion FDM dimensions to Target dimensions (Enterprise and Essbase only)

7. Log into the Hyperion FDM application via Hyperion FDM Web Client

8. Verify application settings

9. Update integration settings

10. Test integration settings

Note: A new Hyperion FDM application must have been created before proceeding with the procedure outlined in this module. Refer to the WebLink 8.3 Installation Guide or WebLink 8.3 Administrator Training Guide for detailed procedures for creating a new Hyperion FDM application.


2-2

1. Log into the Hyperion FDM application via the WorkbenchLaunch the Workbench Client located in the Hyperion System 9-->Financial Data Quality Management program group.

Log onto the new application using the same user name and password used to create the new application.

Figure 2-2: Workbench Logon Screen

2-3


2. Import the Target System AdaptorFrom the Workbench desktop activate the Adaptors page by clicking on the Adaptors tab (bottom of the left pane).

Select File-->Import. This will prompt the Open Import File dialog (Figure 2-3).

Figure 2-3: Open File Import dialog. Locate and select the target system adaptor file from here.

From within the Open Import File dialog, locate and select the target system adaptor file then click on to display the Import window (Figure 2-4).

Note: HETxx.xml files are Enterprise adaptors, ESSxx.xml files are Essbase adaptors. HFMxx.xml files are HFM adaptors. The filename of the current release of the adaptor and location of the adaptor may vary. The most recent adaptors can be downloaded from Support section of the Hyperion web site.

Refer to the Administrator Guide or the Hyperion Web site for more information about adaptors.


2-4

From within the Import popup screen (General tab), check the items to import (Figure 2-4).

Click the Options tab. This tab contains the following options:

Save existing machine profile — if this box is not checked, all existing machine profiles will be deleted.

Remove all report groups before updating reports — this option deletes existing report groups before updating the application with new reports.

Figure 2-4: Import File Dialog. Import of adaptor General Tab (HFM left, Enterprise and Essbase center) and Options tab (right).

Select/deselect the options to be used and click . The selections will be imported and displayed on the desktop under Target System Adaptors (Figure 2-5).

Figure 2-5: After importing the target system adaptor it is displayed on the Workbench desktop under Target System Adaptors - Enterprise (left), Essbase (center) and HFM (right).

2-5


3. Register the AdaptorNote: Adding the adaptor and setting up machine profiles needs to be completed once for every Hyperion

FDM application that is created. Registering the adaptor needs only to be once. Skip this step if a Hyperion FDM application using the same adaptor that has already been registered. The file will be registered for any future applications.

From the Workbench desktop, select File-->Register Adaptor to display the Register Adaptor dialog (Figure 2-6).

-->

Figure 2-6: Select File-->Register Adaptor to prompt the Register Adaptor dialog. Register the adaptor using the .exe file for Enterprise and Essbase or the .dll for HFM.

Select the file from the list (upsENxxx.exe for Enterprise, upsFMxxx.dll for HFM) and click (Figure 2-6).


2-6

4. AddMachineProfileA Machine Profile must be created for every computer that has the Hyperion FDM Web Server Components, the Hyperion FDM Application Server, or the Hyperion FDM Task Manager installed. Working from the Adaptor tab in the Workbench desktop, expand the directory Target System Adaptors directory by clicking to expand the Adaptors directory, then clicking next to the adaptor listed to open the adaptor subdirectory.

Right-click on the Machine Profiles folder and select Add Machine Profile from the flyout menu (Figure 2-7). The Add Machine Profile dialog box will be displayed (Figure 2-8).

Figure 2-7: Right-click on the Machine Profiles folder to add a machine profile (example for HFM).

Complete the Source Machine and Target Machine information in the Add Machine Profile dialog box.

Source Machine Name — enter the Hyperion FDM Application server name here.

Target Machine Name — enter the computer name or IP address of the application server or application cluster here.

User Name — specify a user name, password, and domain for the local machine to override the logon method specified in the Integration Settings logon method. This computer will always use the specified user name and password to log onto the target application server and the application. The user account specified here must have access to the target application server and have appropriate security privileges, regardless of the user who is logged into Hyperion FDM. This option is generally not used, but rather the unified logon functionality in Hyperion FDM to that provides network authentication is the more preferred method. Figure 2-8: Add Machine Profile Dialog box.

Password — the Windows password for the target machine.

Domain — the domain for target machine.

Select when finished.

2-7


5. Update DCOM SettingsNote: This procedure is for integrating Hyperion FDM with Hyperion Enterprise and Hyperion Essbase only. If

integrating with Hyperion Financial Management proceed to step 7.

The upsIntBlockEB7XA.clsHypWindowEB object (Essbase) or the upsIntBlockHE6xG.clsHypWindow object (Enterprise) must be configured to allow access by the same UserID as is configured in the Application Servers. To do this first launch DCOM Config from the Run command.

Figure 2-9: Launch the DCOM Configuration from the Windows Run prompt.

Change DCOM Identity settings on the upsIntBlockEB7XA.clsHypWindowEB object or upsIntBlockHE6xG.clsHypWindow by right clicking on the object and selecting Properties (Figure 2-10).

Figure 2-10: Right-click on the object and select Properties (Enterprise object example shown).


2-8

From the Properties Window, select the security tab, then click .

Figure 2-11 (right): Properties Dialog - Security Tab

Change DCOM Security settings for Launch/Activation Permissions & Access permissions, to Custom. Click the Edit button and ensure that the User ID running the application servers is added to the Custom permissions. If any users will be running the workbench their User ID must also be configured in this manner.

Figure 2-12 (right): Launch Permissions Screen

2-9


6. Map Hyperion FDM Dimensions to Target DimensionsNote: This procedure only needs to be completed when integrating the Hyperion FDM application to

Hyperion Essbase or Hyperion Enterprise. If integrating to Hyperion Financial Management proceed to Step 7.

Enterprise - Map Hyperion FDM Dimensions to Enterprise DimensionsThe NameCat.txt file is used to hold the Hyperion Enterprise name and category that are used to determine if an Enterprise account is calculated. The name selected should represent a typical base name, and the category selected should represent a category used to store actual data.

Return to the Workbench Client and click on the scripts tab. The Script Editor directory will appear (Figure 2-13).

Figure 2-13: Script Editor Directory

Scripts Tab


2-10

Open the Custom\General folder and double-click on the HET_EditNameCat script. The script will be displayed in the right side window (Figure 2-14).

Figure 2-14: Script Editor

Click on the (run button). The Editor dialog box will be displayed (Figure 2-15).

Click and select a typical base name from the target application. Click and select a category that represents one that will be loaded by the Hyperion FDM application then click . A message box will appear confirming that the script has run.

Figure 2-15 (right): Editor Window

Note: The Default for the Dimension Cache Switch is set to off. When set to On the dimension list values are retrieved from Hyperion FDM cache tables and not from the target system. When set to On, then the HET_UpdateDimensionCache script must be run from the Workbench in order to update the tables with the current target application dimension list values.

2-11


Essbase – Map Hyperion FDM Dimension to Essbase DimensionOpen both the Essbase database and Hyperion FDM Workbench side-by-side.

Figure 2-16: Open both Essbase DB and Workbench to Map dimensions.

Right-click on the Hyperion FDM dimensions and update the Foreign Name and Alias to reflect the associated Essbase dimension name.

Figure 2-17: Update the Foreign Name and Alias in the Dimension Properties Screen for each dimension.


2-12

7. Log onto the Hyperion FDM Application via Web ClientLaunch the Web Client located in the Hyperion System 9-->Financial Data Quality Management program group.

Log onto the new application using the same user name and password used to create the new application.

Figure 2-19: Web Client Logon Screen

2-13


8. Verify Application SettingsFrom the Hyperion FDM desktop, open the Administration Menu by selecting the Administration Tab.

Figure 2-20: Administration Menu

From the Administration Menu click the Application Settings link to switch to the Application Settings screen.

Select System Code from the Options dropdown field. It should contain the name of the adaptor that was just added. If several adaptors currently exist in the application, they will be selectable in this field. Use the pull-down menu to select the correct system code key/adaptor for the target system and click .

Figure 2-21: Application Settings Screen

Application Settings


2-14

9. Update Integration SettingsFrom the Administration Menu select Integration Settings to display the Integration Settings Screen. Select Application Name from the Options field dropdown.

In the App Name field type in the name of the target application. Click to update the integration settings.

Figure 2-22 (right): Integration Settings Screen - Application Name Option

Logon MethodFrom the Integration Settings menu, click the dropdown in the Options Field and select Logon Method.

This option controls the method that Hyperion FDM uses to log onto the target system whenever Hyperion FDM makes a connection. There are two logon methods, Unified and Global.

Figure 2-23 (right): Integration Settings Screen - Logon Method Option

Unified — the Hyperion FDM username and password are used to log onto the target system. The username and password for users to log onto the target must be the same as the Hyperion FDM username and password in order to use this option. Global — the username and password specified in the Global Logon Information Option is passed to the target system. Using this option, all users connect to the target system using the same username and password.

If a machine-specific username and password is specified in the Workbench then it will override the logon method specified above for this specific machine.

Integration Settings

2-15


Global Logon InformationThis option is used in conjunction with the Logon Method option. If the Logon Method option is set to “Global” then use this option to set the user ID and password used to log onto the target system. Separate the user ID and password with a semicolon, i.e.. UserID;Password (Figure 35).

Figure 2-24: Integration Settings Screen - Global Logon Information Option


2-16

10. Test the Integration Settings

From the Hyperion FDM WorkbenchSelect the Metadata tab. Double-click Categories under the Control Tables directory and the Category Control Table will be displayed. In the Category table, click the Target Category and view the items in the dropdown menu. The categories from the target application will be displayed if the integration of the adaptor was successful (Figure 2-25).

Figure 2-25: The categories from the target application will be displayed if the integration of the adaptor was successful

From the Hyperion FDM Web ClientOpen the Activities Menu by clicking the Activities Link on the left desktop menu. Select Maps from the Activities Menu (Figure 2-26).

Figure 2-26: Activities Menu

On the Maps screen (Figure 2-27) click . A new row will be added to the grid.

Categories

Maps Link

2-17


Click Browse For Target Value… to display the list of target accounts. If another window is displayed with the list of accounts then the integration settings are configured correctly (Figure 2-28). Otherwise, an error will be displayed.

Figure 2-27: Maps Screen. Add a row then browse for a target value.

Figure 2-28: A list of target members appearing indicates the integration was successful.

Browse Link


2-18

Module 3 - current integrAtion AdAptors

3-1

Module 3 — Current Integration Adaptors

Hyperion HFM AdaptorsF3D-1Date Created: 1/23/2004

WebLink/Hyperion FDM Compatibility: Version 7.0.1 and Higher

HFM Compatibility: Version 3.4 and Higher

The Consolidation Action was modified to test for “Validation Entity Group” over-ride set in a BefConsolidate event script. If true the over-ride group value is used rather than the group assigned to the location.

For Periodic data loading the Export Action was placing the word “Per” in the export Dat file rather than the word “Periodic.” Conditional statement added to replace “Per” with “Periodic.”

F3EDate Created: 1/23/2004

WebLink/Hyperion FDM: Version 7.0.1 and Higher


Data Protection option values are executed within the “Export” action, rather than half in the “Export” action and half in the “Load” actions. This change was made to support “State less” web API Objects, and it provides a cleaner approach to data protection.

“Data Protection” and “Line Item Loading” will only function for single period loads. If either of these options are enabled and the data load is for a range of periods, the options will be ignored.

F3FDate Created: 2/12/2004



Alter Connection Method modified connection action to for changes in Hyperion Financial Management single sign on authentication.

Removed validation of DOMAIN value from connection action. SSO does not use Domain.

F3GDate Created: 2/12/2004



New System option switch to show enable period dimension enumeration to list all periods (Base and Parent).

Created new integration option named “Force Calculate before Consolidation.” When this option is activated, an explicit recalculation will be performed before a consolidation is run for each entity.

•

•

•

•

•

•

•

•


3-2

F3HDate Created: 4/22/2004



Resolved issue with running AftValidate script event to display invalid intersection report.

F3JDate Created: 4/22/2004



Added ability to load journals from Hyperion FDM into HFM as Journals in HFM.

F3IDate Created: 6/02/2004



Added logging of script errors, added ability to have target period user defined instead of derived by Hyperion FDM, set File encoding to ANSI for HFM extract.

F3I-1Date Created: 7/06/2004



Correct UNIFIED login failure.

F3K-1Date Created: 10/21/2004



Enhancement — Intersection Validation Report performance has been dramatically improved by using caching of HFM member name/Key value relationships.

Enhancement — Check Report performance has been dramatically improved by using caching of HFM member name / Key value relationships and caching HFM intersection values that may be used more than once in a Hyperion FDM validation rule.

Fix — HFM application server (HSXServer.Exe) and HFM data server (HSVData.exe) shut down prematurely cause “Remote Procedure Call Failed” and/or “Remote server Unavailable” runtime errors.

Note: this problem also surfaced as an empty message being returned after a data load, but not error being thrown.

•

•

•

•

•

•

•

3-3


F3J-2Date Created: 3/21/2005



Ability to load journals from Hyperion FDM into HFM as Journals in HFM.Enhancement — Now allows you to select which locations are to load Hyperion FDM journals as HFM journals as well as select which data values should be used. To use this, place a value of “1”, “2”, “3” or “4” in the Group Tag field in the Location screen for each location you want to active the journal loads. Each value represents a data value accordingly: 1 = <Entity Curr Adjs> 2 = <Parent Curr Adjs> 3 = [Contribution Adjs] 4 = [Parent Adjs])

Note: When loading to a journal based data value (i.e., Entity Curr Adjs or Parent Curr Adjs) you will need to update the data value in the Validation Rules. This is the last argument in the GetValue function. For example, if your base GL data is going to Entity Currency and your journals are going to Entity Curr Adjs, you will need to add the Total Entity data value to your validation rules to get the combined value. If GL data is going to Entity Currency and your journals are going to Parent Curr Adjs, you will need to add the Total Parent data value to your validation rules

Supports the loading of Hyperion FDM memo items as Cell Text into HFM (activate this function in the Integration Options screen).

HFM4x-ADate Created: 3/30/2005



Release Notes: This integration uses the upsFM40A.dll HFM integration COM wrapper

Enhancements: Added the function called: fIsMemberADescendentOf.Added the function called: fMetaDataLoad.STICKY SERVER - HFM Application Server Cache Delay. The integration Option STICK SERVER has been enhanced to use the direct server connection for consolidate and validate. The adaptor stores the HFM application server used during the LOAD action and then attempts to connect to that server specifically for the CONSOLIDATE and VALIDATE actions. This function requires that an HFM cluster be defined for each HFM application server.

Fix: Line Item Detail intersection checking. The enhanced intersection checking routine introduced in the HFM3x-K adaptor considered any intersection using LID to be read-only. This has been corrected by testing the HFM ACCOUNT and SCENARIO for LID activation prior to evaluating the status of the intersection.

••

-

•---

•-


3-4

HFM4x-A1Date Created: 4/27/2005



Release Notes: This integration uses the upsFM40A.dll HFM integration COM wrapper. This is the first adaptor that supports Oracle intersection checking.

EnhancementsAdded the function called: fIsMemberADescendentOf.Added the function called: fMetaDataLoad.STICKY SERVER: HFM Application Server Cache Delay. The integration Option STICK SERVER has been enhanced to use the direct server connection for consolidate and validate. The adaptor stores the HFM application server used during the LOAD action and then attempts to connect to that server specifically for the CONSOLIDATE and VALIDATE actions. This function requires that an HFM cluster be defined for each HFM application server.Added new mRemoveMultibyteNulls function to upsFM40A.dll that checks the specified file for the presence of char 0 and replaces with a VB Nullstring.

Fixes: Line Item Detail intersection checking. The enhanced intersection checking routine introduced in the HFM3x-K adaptor considered any intersection using LID to be read-only. This has been corrected by testing the HFM ACCOUNT and SCENARIO for LID activation prior to evaluating the status of the intersection.ValueGet action failed for when the “Test Rule” and “Test Display” functions were executed from the WorkBench rule builder with adaptor (HFM4x-A). This adaptor fixes the connection error from the WorkBench.Load Action was enhanced to handle file paths that include an IP address. Prior adaptors would parse the file path incorrectly as a result of multiple “.” characters contained in the string.

•---

-

•-

-

-

3-5


HFM4x-BDate Created: 5/20/2005



Release Notes: This integration uses the upsFM40B.dll HFM integration COM wrapper.

Enhancements: Support for “Replace By Security” added to DLL and XML. This functionality is accessed through the “Load Options Dialog” that is displayed prior to executing the load process.Support for “Translation” added prior to executing a consolidation and validation. This function is turned on/off by setting the integration option “Force Translate”.HFM Intersection validation has be improved to allow support for “ICP Restricted Accounts”. Any account that has the ICP Restricted attribute set to true is tested during the intersection validation process to make sure that it is not used with an Entity that has intercompany with itself.Enhanced Workbench Validation Rule builder support. The “Test Rule” and “Test Display” buttons now support rules that use “Period Math” values. These are rules that use a (-1 or +1) to get a period value relative to the current global period.Load action has been enhanced to handle load files that have a “.” character in the directory path. In prior adaptors a “.” in the path would generate an error during the process of archiving a load error log file.

•-

-

-

-

-


3-6

HFM4x-BG2Date Created: 5/20/2005



Release Notes: This integration uses the upsFM40B.dll HFM integration COM wrapper. This is a GENERATION 2 integration adaptor which makes use of some of the 8 new integration actions available with UpStream WebLink 8.0.7.

New Actions Used in the AdaptorIntersectionCheck (Replaces need to use AftValidate Event Script)ExportA & LoadA (Used to separate Journal Loads from regular DAT file loads)ExportB & LoadB (Used to separate CellText Loads from standard DAT file Loads)ControlsSubmit (Used to set process management in HFM)

Enhancement: Support for “Replace By Security” added to DLL and XML. This functionality is accessed through the “Load Options Dialog” that is displayed prior to executing the load process.Support for “Translation” added prior to executing a consolidation and validation. This function is turned on/off by setting the integration option “Force Translate”.Intersection checking can now be controlled by a global system option. The option titled “Enable Intersection Checking” is used to turn on/off HFM intersection validation.HFM Intersection validation has be improved to allow support for “ICP Restricted Accounts”. Any account that has the ICP Restricted attribute set to true is tested during the intersection validation process to make sure that it is not used with an Entity that has intercompany with itself.Support for Journal Entry loading has been added to the ExportA & LoadA actions of the integration adaptor. Journal entry loading is controlled by the “Enable Journal Loading” integration option. The behavior of the journal load is controlled by the following integration options:

Journal Status: Controls the posting status used during the load (Default = 4 - Posted)Journal Default Data Value: Controls the default “Value” dimension member used for loading the journal (Default value = <Entity Curr Adjs>).

Note: This value will only be used if a location does not have an optional Switch value set in the “Grouping Tag” field on the location setup screen. The Grouping Tag field is used to allow different locations to load journal for different “Value” dimension member values.

Location Grouping Tag values: 1 = <Entity Curr Adjs> 2 = <Parent Curr Adjs> 3 = [Contribution Adjs] 4 = [Parent Adjs]

Journal Balancing Attribute: Controls the required balance checking value for HFM. The default value for this option is “U-Unbalanced.”

Support for CellText loading has been added to the ExportB & LoadB actions of the integration adaptor. CellText loading is controlled by the “Enable CellText Loading” integration option. If this option is activated any Hyperion FDM Memo items for the intersections being loaded into HFM will be added to the HFM intersection as pre-formatted CellText.

•----

•-

-

-

-

-

--

-

-

3-7


Support for setting HFM Process Mgmt has been added to the SubmitControls action of the integration adaptor. Process Mgmt is controlled by the “Enable Process Mgmt” integration option. If this option is activated HFM’s process management will be started and promoted to the point of publishing each base entity that Hyperion FDM loaded. This process will be automatically fired when Hyperion FDM’s financial controls “Submit” process is fired. In addition, the same entities will be “Unpromoted / rejected” when Hyperion FDM’s financial controls “Unsubmit” process is fired.Workbench Validation Rule builder support has been enhanced in two ways.

Browsing custom dimension values when building a lookup formula now lists all members of a dimension (Parent and Child).The “Test Rule” and “Test Display” buttons now support rules that use “Period Math” values. These are rules that use a (-1 or +1) to get a period value relative to the current global period.

HFM4x-CG2Date Created: 8/22/2005



Release Notes: This integration uses the upsFM40C.dll HFM integration COM wrapper. This is a GENERATION 2 integration adaptor which makes use of some of the 8 new integration actions available with UpStream WebLink 8.0.7.

Bug Fixes: Inter-Company Intersection Checking now performs properly when the inter-company switch for accounts or entities in HFM is turned off. All HFM adaptor DLLs prior to upsFM40C.dll would not recognize accounts or entities with the inter-company flag turned off as invalid when used with an ICP Partner value other than [ICP None].

Enhancements: Connect Action has been streamlined in order to prevent connections to HFM for actions that are not active. The enhancements were added for the following actions:

Check Intersections - If “Enable Intersection Validation” option = Off then not HFM connection attempted.Chain Load: If “Enable Chain Load” option = Off then not HFM connection attempted.Controls Review: If “Enable Controls Review” option = Off then not HFM connection attempted.Controls Submit:: If “Enable Process Mgmt” option = Off then not HFM connection attempted.

Single Sign-On (SSO) support is now available for use with Release 8.1.0 and higher. To enable this feature a new system option “Use SSO” must be turned on and the following configuration steps must be followed:

The integration DLL upsFM40C.dll must be installed and registered on the Hyperion FDM Load Balance Manager Server.The proper single sign-on script must be activated through the Load Balance Server configuration utility. Hyperion FDM must be launched from within HFM 4.0 with the custom ASP pages contained in integration zip file.

Journal Entry loading has been modified to allow journal processing to be active/inactive on a location by location basis. Journal are now controlled by the combination of the “Enable Journal Load” global option and “Data Value” assigned to a location.

-

--

-

•-

•-

-

---

•

-

-

-

•


3-8

Examples:Enable Journal Load = TrueLocation’s Data Value = <Entity Currency>**************************************************************Journal Processing For the Location = Off

Enable Journal Load = TrueLocation’s Data Value = <Entity Currency>;<Entity Curr Adjs>**************************************************************Journal Processing For the Location = On

Enable Journal Load = FalseLocation’s Data Value = <Entity Currency>**************************************************************Journal Processing For the Location = Off

Enable Journal Load = FalseLocation’s Data Value = <Entity Currency>;<Entity Curr Adjs>**************************************************************Journal Processing For the Location = Off

General Rule:

If the “Enable Journal Loading” value is set to TRUE, and the Location’s “Data Value” contains two values delimited by a semi-colon then journal loading is ON for that location.

Note: Journal loading is NOT supported for text based multi-loads.Force Calculate and Force Translate were made to run independent of consolidate. However, these calculation still require a that the “Enable Consolidate” global option be set to true, and that a validation entity group be setup for each location. To run a Force Calculate or Force Translate without a consolidation, enable the required global options but leave the consolidate check box on the validation entity screen unchecked for each entity to be calculated/translated.

-

3-9


HFM4x-DG2Date Created: 10/14/2005



Release Notes: This integration uses the upsFM40C.dll HFM integration COM wrapper. This is a GENERATION 2 integration adaptor which makes use of some of the 8 new integration actions available with UpStream WebLink 8.0.7.

Enhancements:This adaptor has the same functionality as HFM4x-CG2. The adaptor has been enhanced to support WebLink 8.2.0 expanded dimensions only. The areas changed to handle the expanded dimension processing are list below:

Adaptor XML Script Value Get: Parameter array has been expanded and re-ordered to handle expanded dimensionsAdaptor XML Script Export: Text/Range based export has been modified to handle expanded dimensions.Adaptor DLL Code fIntersectionCheckEx: Intersection Array has been modified to handle expanded dimensions.

HFM4x-E1G2Date Created: 12/20/2005

WebLink/Hyperion FDM Compatibility: Version 8.0.7 and Higher (Including Release 8.3 With Expanded Dimensions)


Release Notes: This integration uses the upsFM40E.dll HFM integration COM wrapper. It has the same functionality as HFM4x-EG2. The adaptor has been enhanced to reduce connections to HFM during batch processing. The actions changed to reduce connections during batch loading are listed below.

Adaptor XML Script Changes:Connect: Connection action now recognizes when it is being used for batch processing and reuses an existing HFM Connection when it can.All Other Actions: When in batch mode these actions do not close connections to HFM when the action script completes. This allows actions to share HFM connections.

Note: For web processing separate HFM connections are still required. Web processing is stateless and connections to HFM cannot be maintained between page calls.

Fix:Fix Hyperion Single Sign On: Using the Hyperion SSO integration caused an error in previous blocks because the Hyperion FDM version was not correctly retrieved.

•-

-

-

-

•-

-

•-


3-10

HFM4x-FG2Date Created: 01/05/2006

WebLink/Hyperion FDM Compatibility: Version 8.0.7 and Higher (Including Release 8.3 With Expanded Dimensions)


Release Notes: This integration uses the upsFM40F.dll HFM integration COM wrapper. It has adaptor has the same functionality as HFM4x-EG2. It has been enhanced to reduce connections to HFM during batch processing. The actions changed to reduce connections during batch loading are listed below.

Adaptor XML Script Changes:Connect: Connection action now recognizes when it is being used for batch processing and reuses an existing HFM Connection when it can.All Other Actions: When in batch mode these actions do not close connections to HFM when the action script completes. This allows actions to share HFM connections.

Note: For web processing separate HFM connections are still required. Web processing is stateless and connections to HFM cannot be maintained between page calls.

HFM Member List call has been exposed in the upsFM40F.dll com wrapper. A new function “fListMemberlistIDs” has been added to expose this functionality. The arrays returned by this function can be passed to the Extract routine for the Entity, Account, and Period parameters.

HFM Extract Functionality has been enhanced in four ways:The performance of the Multi-Byte null file cleaning process has been greatly enhanced.The extract function now supports arrays of ID’s returned from new member list function called fListMemberlistIDs. New optional parameter was added “blnNoRemoveMultiByteNulls” allows mutli-byte clean null clean up to be switched off.New optional parameter “blnArraysContainIDs” is used as an indicator for that the extract member arrays for Entity, Account, and Period contain ID’s rather than labels. The parameter must be set to true when passing arrays from member lists.

Bug Fixes:Fix Hyperion Single Sign On : Using the Hyperion SSO integration caused an error in previous blocks because the Hyperion FDM version was not correctly retrieved.Fix Consolidate Action Return Value: The consolidate action would return a “Fail” when there was an entity listed in the validation entities table without the consolidate switch turned on or the ForceCalc / ForceTran switches turned on. This problem has been corrected.

HFM4x-GG3Date Created: 02/15/2006



Release Notes: This integration uses the upsFM40G.dll HFM integration COM wrapper.

This adaptor provides handling of “Lookup Function Errors” for check report notification.This adaptor has been enhanced to support use of the additional custom dimensions and attributes that were added in webLink 8.3.0

•-

-

•

•--

-

-

•-

-

••

3-11


Current Hyperion Essbase/Planning AdaptorsThe Essbase Adaptor is slightly different from the normal HFM Adaptor. The Essbase Adaptor consists of three components: Essbase API DLL, Adaptor DLL (An *.EXE file is used for this integration) & the Adaptor XML. Both the EXE and the Essbase API must be in the UpStream Shared Components installation directory.

E65ADate Created: 6/29/2004

WebLink/Hyperion FDM Compatibility: Version 6.0.1 --> 7x

Essbase Compatibility: Version 6.5 and Higher

ESS6x-FDate Created: 8/18/2005


Essbase Compatibility: Version 6.1.x / 6.5.x

Fixes:Load Action: Modified to fix the following problems:

Export file name was truncated to 4 characters to account for Essbase Object length limitation.Error Log is now created on the Hyperion FDM application server if the Load process fails. In prior releases the error log was created on the Essbase server and it could not be read by Hyperion FDM.

Consolidate Action: Modified to return true of the consolidate action is turned off.In prior releases if consolidate was not active an error message was returned stating “Consolidate Failed” because the process was not executed and it returned a false.

ESS6x-HDate Created: 8/31/2005


Essbase Compatibility: Version 6.1.x / 6.5.x

Consolidate Action - Returns OK if the active Location does not have a Validation Entity group. Prior adaptors used to return the message Consolidate failed.

ESS7x-ADate Created: 6/29/2004


Essbase Compatibility: Version 7.0.0 / 7.0.1

Standard Essbase Template revised to work with Essbase 7.0.1. No new functionality was added for this adaptor, all changes made centered around Essbase 7.0 API call changes.

•-

--

--

•

•


3-12

ESS7x-A1Date Created: 11/24/2004



Standard Essbase Template revised to work with Essbase 7.0.1. No new functionality was added for this adaptor, all changes made centered around Essbase 7.0 API call changes.

ESS7x-A4Date Created: 2/23/2005



Modified “Consolidate Action” to allow calculations to run on entities loaded if not Validation Entity Group was assigned to the location. Prior integration adaptors required that each location have a validation entity group in order to execute a calculation.

ESS7x-BDate Created: 8/15/2005



Fix:Load Action: Export file name was truncated to 4 characters to account for Essbase Object length limitation.Error Log is now created on the Hyperion FDM application server if the Load process fails. In prior releases the error log was created on the Essbase server and it could not be read by Hyperion FDM.

ESS7x-DDate Created: 8/31/2005



Fix:Consolidate Action: Returns OK if the active Location does not have a Validation Entity group. Prior adaptors used to return the message Consolidate failed.

•

•

•-

•-

3-13


ESS7x-EDate Created: 11/10/2005



Fixes:Multiload Text Export: Multiload text files processed on Oracle were not resolving the target period properly. The export text file would contain an empty value in the period column of the export file.Shared Member Suppression: Shared members are now automatically removed from dimension member lists for the mapping process.

Installation Steps1) LOAD XML INTEGRATION ADAPTOR

a) Open the Hyperion FDM WorkBench and Log into the desired application.b) Next select the File Menu, then select “Import” and select the file (ESS7X-E.XML). c) Check the “Target System” option in the tree and select OK.

2) REGISTER HYPERION FDM WRAPPER FOR HYPERION ESSBASE

The Hyperion FDM Integration Adaptor wrapper for Essbase 7x (UPSEB7XE.EXE) must be copied to and registered on each Hyperion FDM application server.a) Create a folder under “C:\Program Files\UpStream Software\” named “Integration Adaptors.”b) Copy the EXE file to that new directory location.c) Open the Hyperion FDM WorkBench on each server and select the File Menu, then select “Register

Integration Adaptor” and next select the file (UPSEB7XE.EXE).

3) INSTALL THE ESSBASE RUNTIME CLIENT

Essbase 7x “RunTime Client” must be installed on each Hyperion FDM application server. Installing the Essbase Runtime client ensures that all required Essbase API files exist on the Hyperion FDM Application Server.

•-

-


3-14

ESS7x-F1Date Created: 11/30/2005

WebLink/Hyperion FDM Compatibility: 8.0.0 and Higher


Release Notes:

Fixes:Oracle Text Multiload Export: Multiload text files processed on Oracle were not resolving the target period properly. The export text file would contain an empty value in the period column of the export file.Oracle Text Multiload Data Clear: Data Clear during Multiload Text file processing on Oracle were not resolving the target period properly. The Data Clear Calc script file would contain an empty value (Invalid Member) in the period (Time Dimension) in the calc script.Oracle Text Multiload Consolidate: Consolidate during Multiload Text file processing on Oracle were not resolving the target period properly. The Calculate Calc script file would contain an empty value (Invalid Member) in the period (Time Dimension) in the calc script.Shared Member Suppression: Shared members are now automatically removed from dimension member lists for the mapping process. Base Member List Reading: Essbase base member queries have been enhanced to deal with problems caused by the existence line-feed characters within a member name or member description in the Essbase outline.Check Rule Editor Lookup: The Check Rule editor now returns a value from Essbase from with the Hyperion FDM Workbench. Check rules would function properly in prior adaptors but they could not be tested from within the Workbench.Oracle/Essbase Case Sensitivity and Capability: Oracle is a case sensitive database and as a result Hyperion FDM converts all fields that will be query to upper case. This enables Hyperion FDM to query the Oracle database consistently. Essbase is also case sensitive with respect to member names and as a result upper case member names listed in Hyperion FDM mapping tables may be considered invalid members in Essbase if the member is not defined as upper case in Essbase. To solve this problem Hyperion FDM must perform an extra step when loading Essbase from Oracle. Hyperion FDM uses a lookup mechanism to resolve the Oracle Member Case to the Essbase specific for each member in the export file.Added Dimension Caching: A new system option was added titled “Dimension Cache Switch”. The option controls how Hyperion FDM gets the list of members when a member browsing screen is opened. If the switch is “On” then Hyperion FDM will query its own “tDimXXXX” to build the list of target system members.

Filling Dimension Cache: A custom script HEB_BuildDimensionCache is now included with the Essbase adaptor. This script can be run from the Web or the WorkBench and it will read all active Essbase dimension members and fill the appropriate cache tables.

Note: Dimension Caching may be used with very large member lists. In general Hyperion FDM will be able to perform the member look functions faster if they are run from its own table cache.

CalcBaseEntity Option - A new option was added to enable the calculation of all base entities that were loaded during the file load. If this option is turned on and the Hyperion FDM location that is loading data has NO VALIDATION ENTITY GROUP, then the standard calc script will execute for each entity that was loaded.

•-

-

-

-

-

-

-

-

-

•

3-15


Installation STEPS:1) LOAD XML INTEGRATION ADAPTOR

Open the Hyperion FDM WorkBench and Log into the desired application. Next select the File Menu, then select “Import” and select the file (ESS7X-F1.XML). Check the “Target System” option in the tree and select OK.


The Hyperion FDM Integration Adaptor wrapper for Essbase 7x (UPSEB7XF.EXE) must be copied to and registered on each Hyperion FDM application server.a) Create a folder under “C:\Program Files\UpStream Software\” called “Integration Adaptors”. b) Copy the EXE file to that new directory location.c) Open the Hyperion FDM WorkBench on each server and select the File Menu, then select “Register

Integration Adaptor” and next select the file (UPSEB7XF.EXE).




3-16

ESS7x-GG3Date Created: 02/15/2006



Release Notes: This integration uses the upsEB7XG.exe HFM integration COM wrapper. It provides handling of “Lookup Function Errors” for check report notification and it has been enhanced to support use of the additional custom dimensions and attributes that were added in webLink 8.3.0

Installation STEPS:

1) LOAD XML INTEGRATION ADAPTOR

Open the Hyperion FDM WorkBench and Log into the desired application. Next select the File Menu, then select “Import” and select the file (ESS7X-F1.XML). Check the “Target System” option in the tree and select OK.


The Hyperion FDM Integration Adaptor wrapper for Essbase 7x (UPSEB7XF.EXE) must be copied to and registered on each Hyperion FDM application server.

Create a folder under “C:\Program Files\UpStream Software\” called “Integration Adaptors”. Copy the EXE file to that new directory location.Open the Hyperion FDM WorkBench on each server and select the File Menu, then select “Register Integration Adaptor” and next select the file (UPSEB7XF.EXE).



Setup Items to ConsiderWhen running the Workbench from a local computer you will need to make a few system changes to ensure that all of the Enterprise Adaptor features work correctly.

Change DCOM Identity settings on the upsIntBlockEnt6x.clsHypWindow object from launching user to the “This User” field. The field should be then updated to contain the same service ID that is being used for Hyperion FDM Web and Application server setup.

Change DCOM Security settings for Launch/Activation & Access permissions to Custom. Ensure that the User ID of the user who will be running the local version of the Workbench is added to the Custom permissions.

Add a machine profile to the Hyperion FDM application with the name of the local computer that will be running Workbench. The Source & Target machine names both need to be set to the local computer name.

Ensure that Hyperion Essbase is installed on the local computer and can access the Essbase application on the application server.

---

•

•

•

•

3-17


Current Hyperion Enterprise AdaptorsThe Enterprise Adaptor is slightly different from the normal HFM Adaptor. The Enterprise Adaptor consists of two components: Adaptor DLL (An *.EXE file is used for this integration) & the Adaptor XML. The EXE file is registered instead of a DLL for this integration.

HET6x-ADate Created: 6/04/2004


Enterprise Compatibility: Version 5x/6x

The Hyperion Enterprise Integration Adaptor adds the ability to store Enterprise Account & Entity dimensions within the Hyperion FDM database.

HET6x-BDate Created: 11/30/2004



FixesUnified logon method: the Unified method was failing as a result of an invalid property reference.Calculate on Load Event: when a consolidation is NOT run.

HET6x-CDate Created: 4/25/2005



Fixes:Multi-Load load parameters for Hyperion Enterprise:

Default Scale was not set: Now set to value (255) NoneDefault View was not Set: Now Set to value (YTD)Hundred Thousands was set incorrectly: Now set to value (5)

Add short version of multi-load load parameters for Hyperion Enterprise. Adaptors HET6x-A and B required a full length value for each option but should allow an abbreviated value.

Example: “Replace” is required but “R” should be allowed. The short values were added in this adaptor and are documented in the 807 admin guide.

•

•--

•-

---

-


3-18

HET6x-DDate Created: 5/20/2005



Enhancements:Add “Period Math” capability to value get action. This will allow validation rules to be written using (+1 or -1) in the period position of the lookup formula in order to get a period number that is relative to the current global period.Workbench Validation Rule builder support has been enhanced. The “Test Rule” and “Test Display” buttons now support rules that use “Period Math” values. These are rules that use a (-1 or +1) to get a period value relative to the current global period.Load Action has been enhanced to handle load files that have a “.” character in the directory path. In prior adaptors a “.” in the path would generate an error during the process of archiving an load error log file. Connect Action has been enhanced to check for the existence of the Hyperion Enterprise INI file. If the INI file exists, then it is searched in order to determine if the application to be open can be found in the file. In the event of a failure of either of these tests, an error is raised with a detailed message.

HET6x-EDate Created: 8/18/2005



Enhancements:Now supports the full Enterprise account length and ability to have two levels of sub-accounts. Previously if an Enterprise application used the full 20 character account length, 17 (or more) characters in the first level sub account and used a second level sub-account the import account process would return an error.

•-

-

-

-

•-

3-19


HET6x-FDate Created: 8/18/2005



Release Notes:

Full Account Desc - Enhanced account description by allowing sub-accounts to contain a full account description (Main + Sub-Account1 + Sub-Account2).

This new functionality is controlled by the adaptor option value:

“Use Full Account Desc” (TRUE/FALSE)

If this switch is set to TRUE then the full account description will be used for account listing calls. If the switch is set to FALSE then only the most detail account description will be used for account listing calls.

Enhanced Error Logging for procedures that update data (Enterprise Error Codes added to Log).Lock/Unlock DataLoad DataConsolidate Data

HET6x-GG3Date Created: 02/15/2006



Release Notes:

This integration uses the upsEN6XG.EXE Enterprise integration COM wrapper.This adaptor provides handling of “Lookup Function Errors” for check report notification. Has been enhanced to support use of the additional custom dimensions and attributes that were added in webLink 8.3.0.

•

-

•---

•••


3-20

Setup Items to ConsiderWhen running the Workbench from a local computer you will need to make a few system changes to ensure that all of the Enterprise Adaptor features work correctly.

Change DCOM Identity settings on the upsIntBlockEnt6x.clsHypWindow object from launching user to the “This User” field. The field should be then updated to contain the same service ID that is being used for Hyperion FDM Web and Application server setup.

Change DCOM Security settings for Launch & Access permissions to Custom. Ensure that the User ID of the user who will be running the local version of the Workbench is added to the Custom permissions.

Add a machine profile to the Hyperion FDM application with the name of the local computer that will be running Workbench. The Source & Target machine names both need to be set to the local computer name.

Ensure that Hyperion Enterprise is installed on the local computer and can access the Enterprise application on the application server.

Dimension CacheThe Hyperion Enterprise Adaptor adds the ability to store Enterprise Account and Entity dimensions within the Hyperion FDM database. This enables Hyperion FDM to display the Account and Entity dimensions more quickly than connecting to the target system for every request. Enabling this option is done be turning on the Dimension Cache Switch in the Integration Options.

Once this switch is enabled two scripts must be run in order to populate the dimension tables (HET_EditNameCat & HET_UpdateDimensionCache). These scripts must be run from the Workbench.

Note: If this option is enabled then the HET_UpdateDimensionCache script must be run any time that the Dimensions are updated in Enterprise. It is recommended that Hyperion FDM Task Manager be setup to run this script on a regular basis to ensure the dimension lists are correct.

•

•

•

•

3-21



3-22

weblink dm guide to adaptors

Documents