Oracle® Hyperion Calculation Manager

New Features

Release 11.1.2.3.000


Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Authors: EPM Information Development Team

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS:

Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.


Table of Contents:

New Features

New Features

For new features relating to installation, architecture, and deployment changes in this release, see "New Features" in the Oracle Enterprise Performance Management System Installation and Configuration Readme.

For Oracle Hyperion Calculation Manager new features, see the following sections.

Documentation Now Certified on Apple Mobile Devices

Documentation files for Release 11.1.2.3 are now available in two mobile formats: MOBI files, available previously, and EPUB files. EPUB documentation files are supported on all Apple Mobile devices (iPad, iPhone, and iPod Touch). EPUB files are supported on many mobile devices; however, they are certified only on Apple Mobile devices. Additional devices will be certified over time. Reminder – please include this blurb in your New Features Guide or New Features section of the Readme for 11.1.2.3.

Features Introduced in Earlier Releases

If you are coming from Release 11.1.2.0, 11.1.2.1, or 11.1.2.2, use the Cumulative Feature Overview tool to review the list of new features added between those releases. This tool enables you to identify your current products, your current release version, and your target implementation release version. With a single click, the tool quickly produces a customized set of high-level descriptions of the product features developed between your current and target releases. This tool is available here:https://support.oracle.com/oip/faces/secure/km/DocumentDisplay.jspx?id=1092114.1

Searching for and Replacing Strings Globally Throughout Calculation Manager

From the System View, you can perform a global search and replace within a product that uses Calculation Manager (for example, Oracle Hyperion Financial Management, Oracle Hyperion Planning, or Oracle Essbase), within an application, within a plan, database or calculation type, within rulesets, within rules, within templates, within formula components, and within script components.

Note:

Calculation Manager searches the names, descriptions, comments, and captions of objects if you select Include Basic Properties. Calculation Manager searches the formulas, scripts, other components, variables and so on that are used in the object by default.

When you search, Calculation Manager searches through each object in the node of the System View in which you launched the search. (If you want to search in an individual object, you must open it, and then select Edit and Find.) For example, if you right-click the Rules node of a plan type within a Planning application, and select Find, Calculation Manager searches through all of the business rules in that Rules node for the text string you enter.

If Calculation Manager finds the text you are searching for, it opens a Find tab with a list of the objects containing the text and the scope of the objects in which you searched. For example, if you searched for text in the Scripts node of a plan type within a Planning application, Calculation Manager displays the number of objects in which the text is found and the application name and plan type within which the objects exist.

You can replace selected occurrences or all occurrences of a text string. If you replace selected occurrences, Calculation Manager replaces only the occurrences that you select in the Find tab. If you replace all occurrences, Calculation Manager replaces all instances of the text string in the Find tab simultaneously.

Note:

Replace All is only available when you search for a text string using the Contains or Matches option; it is not available when you use the Starts with or Ends with option.

Filtering Objects by Text String

In the List View, you can use the Filter dialog to filter the objects that display in the view according to criteria you specify. You can filter objects by a text string. You can search for text string that starts with, ends with, contains, or matches the text string you enter. You can also search for text in the case you entered (upper or lower) or search for text in either case.

Sorting in a Data Range Component (Financial Management Applications Only)

In Financial Management data range components, you can sort by dimension. After you select the dimension to sort on, you can sort the dimensions in ascending (A to Z) or descending (Z to A) order.

Suppressing System Key Words while Editing in Script Mode

In previous releases, when you edited a business rule in script mode, Calculation Manager displayed multiple lines of system generated key words as comment lines to use the key words to convert back to graphical mode. In this release, you can suppress the display of these key words to make the script more readable by selecting Hide Comments or display these key words by selecting Show Comments.

Note:

When you select Hide Comments, only comments generated by Calculation Manager are hidden; comments that you or other users enter in the script are not hidden.

Analyzing a Business Rule Script for Performance or Optimization Issues (for Planning and Essbase Block Storage Application Users Only)

When you are designing a business rule, you can run script diagnostics for it. To run script diagnostics, click on any component within a business rule, click on the Errors and Warnings tab, and then click the button to run script diagnostics. When you do this, Calculation Manager analyzes the business rule script, and displays either:

  • Validation errors, if the rule does not validate. You can right-click on each of the validation errors to see the source of the error in either the View Script or the View Designer tab.

    When you select Show in Script, the rule is displayed in script mode and the line with the error is highlighted. (If this is a graphical rule, you cannot edit the rule in script mode.) To edit the rule, select Designer.

    When you select Show in Designer, the component with the error is highlighted. Fix the error, then rerun script diagnostics, or click on another error to fix it.

  • A Summary and Warnings, if the rule validates. You can click on each of the summary and warning items to see the source of the script in either the View Script or the View Designer tab.

    When you select Show in Script, the rule is displayed in script mode and the line with the error is highlighted. (If this is a graphical rule, you cannot edit the rule in script mode.) To edit the rule, select Designer.

    When you select Show in Designer, the component with the error is highlighted. Fix the error, then rerun script diagnostics, or click on another error to fix it.

    Note:

    The warnings are based on best practices, but if required in your script, you can ignore the warnings.

    • The Summary lists such statistics as the number of data cells in the calculation, the number of passes through the data, the number of assignment mismatches, and the number of dimensions that are used incorrectly.

    • The Warnings lists such information as whether all sparse dimensions are specified for cell references, whether a cell references sparse members, and whether an assignment references sparse dimension members in different data blocks; each of these can affect performance.

Copying Variables Across Different Scopes

You can copy a variable across different scopes in Calculation Manager. Depending on the application type, you can copy a variable from one application, calculation type, plan type, or database, ruleset, or rule to another application, calculation type, plan type, or database, ruleset, or rule within the same application type. For example, you can copy a Planning. plan type variable to a Planning business rule, but you cannot copy it to a Oracle Hyperion Financial Management business rule.

If the variable you want to copy already exists (that is, a variable with the same name already exists in the location to which you want to copy it), you can give the copied variable a new name, skip copying it, or overwrite the contents of the existing variable with the contents of the copied variable.

Selecting Variables from within Member Block Components

For Essbase and Planning member block components, now you can insert a variable or a member into the member block.

Comparing the Scripts of Two Business Rules

You may want to view the scripts of two business rules to see how they are different from each other, to see changes you have made, or to see the scripts of graphical business rules. Now you can display the scripts of two business rules side-by-side in a window within the System View of Calculation Manager.

The components of the two calculation scripts are displayed in a new window, the Compare Scripts window, side-by-side. The Compare Scripts window displays the following information:

  • If an addition was made to either script, the line displays in a light gray background.

  • If a deletion was made from either script, the line displays in a dark gray background.

  • If either script was changed, the line displays in a yellow background.

  • The first column displays the line number of the script.

  • The second column displays one of three characters:

    • * indicates that the line in the script displayed in the left column is different from the line in the script displayed in the right column

    • + indicates a new line was added to the script displayed in the right column when compared to the script displayed in the left column

    • – indicates a line was deleted from the script displayed in the right column when compared to the script displayed in the left column.

  • The third and fourth columns display the two scripts. When you highlight one of the lines in the script that is different, the bottom pane displays the script in separate sections. The left script is shown in the first section with the right script below it.

Note:

You cannot compare more than two business rules at a time. Also, you cannot compare versions of a business rule (for example, you cannot compare a previous version of a business rule to the version that you just saved).

Opening a Rule from within a Ruleset by Double-Clicking

In previous releases, when you edited a business ruleset in the Ruleset Designer, to open one of the rules in the ruleset, you right-clicked the rule and selected Open. In this release, when you are working with a ruleset in the Ruleset Designer, you can double-click a business rule to open it.

Selecting the Variables to Display in the Variable Selector

You can open the Variable Selector from multiple components in Calculation Manager. By default, the Variable Selector shows all of the available variables, although some variables may not be relevant to the context in which you opened the Variable Selector. (For example, when you open the Variable Selector in a member block component, numeric variables are displayed, although they cannot be used in member block components.) In this release of Calculation Manager, only relevant variables are displayed by default, based on the context in which you open the variable selector. You can also show all of the variables in the Variable Selector, regardless of the context, by selecting Show All Variables.

Resetting Selections in the Filter Dialog

In the List View, you can use the Filter dialog to filter Calculation Manager objects according to criteria that you specify. The Filter dialog contains two tabs, a Filter Options tab and an Advanced Options tab. In this release, after you make your selections on each tab, you can click Reset to reset one tab with its default values, while leaving your selections on the other tab unchanged.

Selecting Planning Smart Lists from within the Condition Builder

In this release, when you are using the Condition Builder to create conditions for Planning business rules, you can use a smart list, in addition to a variable, member, or function, in the formula of the condition.

Searching and Replacing Text within Design Time Prompts

You can search for and replace a text string in a template's design time prompts. You can search for a whole word, part of a word, a word in the same case, or a word in either case. You can wrap the search so that all rows in the design time prompt grid are searched, starting with the row you selected and ending with the same row.

When you search, Calculation Manager searches through each design time prompt's name and text field, beginning with the row you selected in the design time prompt grid or the first row if no row is selected. If Calculation Manager finds a match, the match is highlighted in the design time prompt grid; if no match is found, a message is displayed.

You can replace one or all occurrences of a text string. If you replace one occurrence, Calculation Manager finds and replaces one instance of the text string at a time. If you replace all occurrences, Calculation Manager finds and replaces all instances of the text string simultaneously.

Printing Business Rules from the Deployment View

In addition to printing from the System View, now you can print a business rule from the Deployment View. You can print a business rule's properties, its flow chart, and the details of its components. For example, if you print a business rule that contains a formula component for allocation expenses, the print out shows the formula syntax, the functions and variables that comprise the formula, a summary of the steps in the rule's flow chart (not in graphical form), and the rule's properties. You can also print templates and components that are used in the business rule.

Support for Runtime Prompts in Essbase Business Rules

You can create runtime prompt variables for Essbase business rules. Runtime prompt variables enable users to enter values for the variables when they are launching the business rules in Calculation Manager or Oracle Essbase Administration Services. After all the values are validated, the business rule is launched.

Note:

If the runtime prompt variable contains a default value, when the rule is validated, it is validated with the default runtime prompt values.

You can create runtime prompts for the following Essbase variable types:

  • Numeric

  • Integer

  • String

  • Cross dimension

  • Dimension

  • Member

  • Members

  • Percent

  • Member range

Entering Missing Values for Runtime Prompts during Validation, Debugging, and Analysis (Planning and Essbase Users Only)

When validating or launching a rule, now you are prompted to enter the values for the runtime prompt variables used in the rule for Planning and Essbase block storage rules. If there is a default value for the variable, that value is used for validation, but when launching the rule you are prompted to enter values for all runtime prompt variables used within the rule. During validation, you can select the option, Apply values to the rule, to apply the values you enter for the runtime prompts. During launch, these values will be displayed so they can be used or changed for the runtime prompts.

Creating Variables Using Dimension Names

You can create variables of the type member, members, cross dimension, member range, and dimension with dimension names instead of dimension types. At the Global level, you can type the dimension name; at the application level, there is a drop-down that lists all of the dimension names in the application.

Searching in the Variable Designer

You can search for a variable by entering its name in the Search feature of the Variable Designer. You can also search for a text string in a variable. (For example, you can search for a string variable with a default value if you include basic properties in the search.)

By default, Calculation Manager searches using the variable's default value. If you include the basic properties of the variable in the search, Calculation Manager searches using both the default value and the name, type, description, and group of the variable.

Note:

Calculation Manager searches for the variable only within the type (that is, global, application, calculation, plan, or database, or business rule) you select in the Variable Navigator. (For example, if you select a plan type, then Calculation Manager searches only within that plan type.) To search for a variable within all variable types, you must perform the search within each type separately. If you do not select a type, the Search facility is disabled.

Editing Template Macro Calls in a Script

If you are editing a business rule in script mode, and the business rule contains a template, now you can edit the template from within the business rule script. To edit the template, select the template line in the script, and then click the icon, Edit Template. This launches the template wizard where you can make changes to the template.

Support for Two New Planning and Essbase System Templates

This release includes two new system templates for Planning and Essbase. You can use the Allocate Simple Exclude template in a Planning or Essbase business rule to allocate a range of members and exclude other members in the range from the allocation.

You can use the Currency Conversion template in Planning applications that are created without multi-currencies and in any Essbase block storage application. You use the Currency Conversion template to convert account values to reporting currencies using system type accounts (or accounts you choose) for Planning applications and user defined attributes (or accounts you choose) for Essbase applications.

The Allocate Simple Exclude template wizard enables you to:

  • Allocate to all members in the allocation range or define members to exclude from the allocation range

  • Allocate evenly to all members in the allocation range or allocate using a driver/basis for each member in the allocation range

  • Specify whether to round the values, and if so, how to round the data

  • Select Debug Wizard On to display comments in the script that show what you input for the design time prompts within the template

The Currency Conversion template wizard enables you to:

  • Select the custom dimension created for the currency

  • Select the reporting currency member within the currency dimension

  • Select the exchange rate for the reporting currency

Creating and Deleting Members Dynamically for Workforce Planning, Capital Asset Planning, Public Sector Budgeting, and Project Financial Planning Plan Types

If you are working with a Planning application with the Workforce Planning, Capital Asset Planning, Public Sector Budgeting, or the Project Financial Planning plan type enabled, you can create and/or delete members dynamically when a business rule is launched. When you do this, and define a default dynamic parent member, the children members of the parent are automatically created before the rule is launched, or automatically deleted after the rule is launched, in Oracle Hyperion Planning.

Using the Command Line Launcher for Essbase Business Rules in Calculation Manager

The Command Line Launcher utility is in the calcmgrCmdLine.jar file in %EPM_ORACLE_HOME%\common\calcmgr\11.1.2.0\lib. You need to install the Java Runtime binaries on the computer where you run the utility. To run the utility, copy the jar file to the computer where you want to run the utility, and use the following command:

java –jar calcmgrCmdLine.jar <Calc Server URL> <USER> <PASSWORD> <APPLICATION NAME> <DATABASE NAME> <RULE NAME> [,<VARIABLE NAME>=<VARIABLE VALUE>]
  • The Command Line Launcher can run only one rule at a time.

  • If a variable name that is not referenced in the rule is passed, it is ignored, and no message to that effect is generated.

  • If a variable is referenced in the rule, but not passed in as an argument, the generated rule script uses the validation value or the variable’s default value (if specified).

  • If the launch is successful, an error level of zero is returned. If the launch is not successful, an error level of 1 is returned.

Command Line Launcher Example and Arguments

Following are some examples of the Command Line Launcher.

java –jar calcmgrCmdLine.jar http://myBox:19000 admin password Sample Basic myRule var1=\"Jan\" var2=1000 var3=”Budget->\”001\”->FY10”
  • <Calc Server URL> - The protocol, such as http or https, and the host name and port

  • <USER> <PWD> - The user name and password

  • <APPLICATION NAME> - The Essbase application in which the rule is created

  • <DATABASE NAME> - The Oracle Essbase database (in the application) in which the rule is created

  • <RULE NAME> - The name of the business rule

  • <VARIABLE NAME> - The runtime prompt variable name to be replaced in the business rule

  • <VARIABLE VALUE> - The value of the runtime prompt variable

Non-Encrypted Mode Examples

java -jar calcmgrCmdLine.jar <CalcServer URL> <USER NAME> <PWD> <Application Name> <Database Name> <Rule Name> <variable name=value>,<variable name=value>
java -jar calcmgrCmdLine.jar http://myBox:19000 admin password Sample Basic myRule var1="Jan" var2=1000

Encrypted Mode Example

If you need to pass the password encrypted as an argument to the Command Line Launcher, first create an encrypted token for the password. You can encrypt the password using a default key as follows:

java -jar calcmgrCmdLine.jar -encrypt password

Encrypted Mode Using a Default Key to Decrypt Example

If you want to decrypt a password using a default key, decrypt as follows:

java –jar calcmgrCmdLine.jar -decrypt http://myBox:19000 admin g//Fl9AB2qrFN9R5m141CPgcLYmjmLyiIxk2CXz7hxbheZe6HDUvjYkQuW2l4Oer Sample Basic myRule var1="Jan" var2=1000

Encrypted Mode Using a Supplied Key to Encrypt Example

If you want to encrypt a password using a supplied key, encrypt as follows:

java -jar calcmgrCmdLine.jar -encrypt -key AAAAAAAAAAAAAAAAAAAAAA password

Encrypted Mode Using Supplied Key to Decrypt Example

java –jar clacmgrcmdLine.jar -key AAAAAAAAAAAAAAAAAAAAAA http://myBox:19000 admin g//Fl9AB2qrFN9R5m141CPgcLYmjmLyiIxk2CXz7hxbheZe6HDUvjYkQuW2l4Oer Sample Basic myRule var1="Jan" var2=1000

Using a Bat File in Windows to Run the Command Line Launcher

Following is an example of using a bat file in Windows to run the Command Line Launcher.

@echo off
java –jar calcmgrCmdLine.jar http://myBox:19000 admin password Sample Basic myRule var1=\"Jan\" var2=1000 var3=”Budget->\”001\”->FY10”
IF %ERRORLEVEL%==0 goto success
echo there is error
goto end
:success
echo success
:end

Using New Custom-Defined Functions in Calculation Manager

This release of Oracle Hyperion Calculation Manager contains several new custom defined functions that may be used in components. Following is a list of these functions.

  • @CalcMgrExecuteMaxLEnScript – launches encrypted MaxL scripts

    Java Class: com.hyperion.calcmgr.common.cdf.MaxLFunctions

    Spec: @CalcMgrExecuteMaxLEnScript(privateKey, maxlScripts, arguments, asynchronous)

  • @CalcMgrExecuteEncryptMaxLFile – launches an encrypted MaxL file

    Java Class: com.hyperion.calcmgr.common.cdf.MaxLFunctions

    Spec: @CalcMgrExecuteEnMaxLFile(privateKey, maxlFileName, arguments, asynchronous)

  • CalcMgrIntegerToString – converts an integer to a string

    Java Class: com.hyperion.calcmgr.common.cdf.MaxLFunctions

    Spec: @CalcMgrIntegerToString(integerNumber)

  • @CalcMgrDoubleToString - converts a double to a string

    Java Class: com.hyperion.calcmgr.common.cdf.MaxLFunctions

    Spec: @CalcMgrDoubleToString(doubleNumber)

  • @CalcMgrStringsToString – converts a string array to a string that uses a delimiter

    Java Class: com.hyperion.calcmgr.common.cdf.MaxLFunctions

    Spec: @CalcMgrStringsToString(strings, seperator)

Writing a MaxL Script or File Using Encryption

The command, essmsh –gk, produces a private and a public key on the console:

  • Public Key for Encryption: 25159,850102129

  • Private Key for Decryption: 240764119,850102129

  To write a MaxL script or file using encryption:

  1. To generate a token for the user, admin, with the public key essmsh -ep admin 25159,850102129, you might get a token similar to 906388712099924604712352658511.

    To generate a token for the user, admin, with the public key essmsh -ep password 25159,850102129, you might get a token similar to 0893542980829559883146306518502837293210.

  2. Write a MaxL script with the login:

    login $key $1 $key $2 on localhost;

  3. Execute MaxL: essmsh -D fileName privateKey userKey passwordKey

    essmsh -D C:/Temp/maxlcmd1.mxls 240764119,850102129 906388712099924604712352658511 0893542980829559883146306518502837293210

  4. To encrypt a MaxL file with a username and password, use the following command. This command creates an encrypted file on the folder; use this in the custom defined function.

    essmsh -E "<full path of MaxL file name>" <public key>

Calc Script Examples

Following are a couple of examples of calc scripts.

FIX ("Sales","100-10","New York","Actual")
    "Jan"(
@CalcMgrExecuteEncryptMaxLFile("2115028571,2505324337","C:/Temp/exportdata.mxls",@List("906388712099924604712352658511","0893542980829559883146306518502837293210"),
"true");
    )
ENDFIX


RUNJAVA com.hyperion.calcmgr.common.cdf.MaxLFunctions "false" "-D" "C:/Temp/maxlcmd1.mxls" "2115028571,2505324337" "906388712099924604712352658511" "0893542980829559883146306518502837293210" "sample" "var1" "var1_value";