ra.hyperionfm 1 0 0 hyperion 1.0 agent guide en (1)

8/18/2019 RA.hyperionFM 1 0 0 Hyperion 1.0 AGENT GUIDE en (1)

1/94

Rapid Automation

ONE Automation Platform

Hyperion Agent Guide

Version: 1.0

Publication Date: 2016-02

Automic Software GmbH


2/94

ii Copyright

Copyright Automic® and the Automic logo® are trademarks owned by Automic Software GmbH (Automic). All

such trademarks can be used by permission only and are subject to the written license terms. This

software/computer program is proprietary and confidential to Automic Software and is only available

for access and use under approved written license terms.

This software/computer program is further protected by copyright laws, international treaties and

other domestic and international laws and any unauthorized access or use gives rise to civil and

criminal penalties. Unauthorized copying or other reproduction of any form (in whole or in part),

disassembly, decompilation, reverse engineering, modification, and development of any derivative

works are all strictly prohibited, and any party or person engaging in such will be prosecuted by

Automic.

No liability is accepted for any changes, mistakes, printing or production errors. Reproduction in

whole or in part without permission is prohibited.

© Copyright Automic Software GmbH. All rights reserved.


3/94

Rapid Automation Hyperion Agent Guide iii

Contents

1 Introduction 1

1.1 Hyperion FM Integration 1

1.2 About Rapid Automation Agents 2

1.3 Using WebHelp at docs.automic.com 3

2 Installation and Configuration 5

2.1 General Set-up Information 5

2.2Installing the Hyperion FM Agent inanExisting Automation Engine System 6

2.3 Configuring System Objects 10

2.4 Specifying Automation Engine/Agent Timeout Seconds 12

3 Jobs 13

3.1 Creating Jobs 13

3.2 Job Types 14

3.2.1 Creating an Allocate Job 15

3.2.2 Creating a Calculate Job 17

3.2.3 Creating a Calculate Contribution Job 19

3.2.4 Creating a Clear Data Slice Job 21

3.2.5 Creating a Close Period Job 23

3.2.6 Creating a Consolidate Job 25

3.2.7 Creating a Copy Data Job 27

3.2.8 Creating an Extract Data To Database Job 30

3.2.9 Creating an Extract Data to Flat File Job 34

3.2.10 Creating an Extract Journals Job 38

3.2.11 Creating an Extract Member Lists Job 42

3.2.12 Creating an Extract Metadata Job 44

3.2.13 Creating an Extract Rules Job 48

3.2.14 Creating an Extract Security Job 50

3.2.15 Creating a Load Data Job 53

3.2.16 Creating a Load Journals Job 57

3.2.17 Creating a Load Member Lists Job 59

3.2.18 Creating a Load Metadata Job 61

3.2.19 Creating a Load Rules Job 65

3.2.20 Creating a Load Security Job 67


4/94

iv Contents

3.2.21 Creating a Translate Job 70

3.3 Creating Workflows with Hyperion FM Jobs 72

3.4 Managing Output and Execution Options with t he R A Tab 73

3.5 Hyperion FM Job Attributes 753.6 Setting Trace 86

Release Notes 89

Release Notes: Rapid Automation Hyperion FM Agent v1 89

Getting the Latest Information 89

V1.0.0 89

Supported Platf orms 89

What's New 89


5/94

Rapid Automation Hyperion Agent Guide 1

1 Introduction

1.1 Hyperion FM IntegrationThis integration allows you to run several Hyperion Financial Management (Hyperion FM or HFM)

job types.

Oracle Hyperion Financial Management is a packaged solution for finance users that helps develop

standardized financial data management processes with its Web-based guided workflow user

interface. Its data preparation server can ease integrating and validating financial data from any of

your source systems.


6/94

2 Chapter 1 Introduction

1.2 About Rapid Automation Agents

You define agent-specific connection, agent, and job objects with unique panels.

After loading a Rapid Automation (RA) .jar file into the Automation Engine, you will be able to define

RA agent-specific connection, agent, and job objects with unique panels. The topics in this guidedescribe how to use these RA panels, not how to define connection, agent, and job objects. For

information on creating these objects, see your Automation Engine documentation.

Using Object Variables in Fields

You can use object variables in the format & in most fields on Rapid Automation

panels. The values of these object variables will be replaced at run time.

It is recommended that you terminate object variable names with an # character.

Overriding Settings on RA Agent-specific Tabs

You can override settings on the RA agent-specific tab for:

l A single run of a Rapid Automation job you execute. To activate this option for a job, the

Request task parameters option must be checked on theRA tab of a job's definition. For

more information, see Managing Output and Execution Options with the RA Tab.

l Rapid Automation jobs added as tasks in a workflow. For more information on editing

workflow tasks, see your Automation Engine documentation.

l An instance of a task that is not yet active from theActivities window by right-clicking and

selecting Modify Task Parameters.


7/94


1.3 Using WebHelp at docs.automic.com

The format of the documentation at docs.automic.com requires a Web browser. There you will find

the most up to date version of this documentation. In addition you find the latest Automic software

components.

Automic documentation is written as a series of topics. Each topic begins with a heading followed

by a summary paragraph. The summary paragraph states the key concepts presented in the topic.

To get a quick overview of a chapter, read the summary paragraph for each topic and look at the

images and their captions.

Documentation at docs.automic.com contains the most up to date version of this documentation. It

is provided as in both .pdf and HTML5 formats.

The HTML5 documentation is displayed as individual HTML pages. You can:

l Find documents in the table of contents.

l Find documents with full-text search.

l Print individual topics.

Contents

The Contents tab contains the contents of the documentation in a tree-view of the directory

structure. It includes all the individual books that can be opened and contain further books or

documents.

Click on a book to open or close it. A click on a document in the TOC displays its contents in the

browser window.

If you click on a hyperlink that is shown in a document, the new document displays in a browser window. The TOC also shows the position where the open document is available.

Searching

You can search through the entire documentation using the search field in the top right-hand corner

of the WebHelp. Enter one or more search terms in the field and start the search either by clicking

the magnifying glass icon or using the Enter key. The search results are displayed in a separate

document.

l Uppercase and lowercase letters are not distinguished (not case-sensitive).

l You can use any combination of letters (a-z) and numbers (0-9).l You can search for several words. The following combinations can be used: AND relations

(separators: AND, +, &), OR relations (blank or | can be used as a separator) and negations

(^ character in front of the term, NOT will not work).

l To combine search operators and expressions, use ( ). Example: term1 AND (term2 OR

term3)

l Variant endings will be found (example: search for run and running , runner and runtime also

will be found)

l Search results will be highlighted

l Wildcards are not supported.

http://docs.automic.com/http://docs.automic.com/http://docs.automic.com/


8/94

4 Chapter 1 Introduction

l Punctuation marks that are used in the word (such as a dot, colon, semi colon, comma or

hyphen) have the effect that the searched term is split into two words.

Printing

It is possible to print individual pages from a book. Display the document you want to print and click

the Print button in the bar at the top.


9/94


2 Installation and Configuration

2.1 General Set-up InformationDo the following required steps.

1. Install the license.

2. Install the RA Core with Java version 1.7 or 1.8 on the machine where Oracle Hyperion FM is

installed.

3. Delete the content of the "lib" folder, the folder should remain empty

4. Set the environment variables EPM_ORACLE_HOME and EPM_ORACLE_INSTANCE if

they are not set.

Example for Windows:

SET EPM_ORACLE_HOME=C:\Oracle\Middleware\EPMSystem11R1SET EPM_ORACLE_INSTANCE=C:\Oracle\Middleware\user_

projects\epmsystem1

5. Make sure the matching agent object is created in client 0.

6. Start the agent with the following command line:

Windows:java -Xmx512M -cp ucxjcitx.jar;uc4.jar;shared/uc4-ra.jar;groovy-

all.jar;shared/bsf-2.4.0.jar;shared/commons-codec-

1.9.jar;shared/commons-logging-

1.2.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\e

pm_hfm_

web.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\e

pm_j2se.jar;C:\Oracle\Middleware\EPMSystem11R1\common\jlib\11.1.2.0\

epm_thrift.jar com.uc4.ex.cit.UCXJCITX

Unix:java -cp ucxjcitx.jar:uc4.jar:shared/uc4-ra.jar:groovy-

all.jar:shared/bsf-2.4.0.jar:shared/commons-codec-

1.9.jar:shared/commons-logging-

1.2.jar:/u0/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/

epm_hfm_

web.jar:/u0/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0/

epm_

j2se.jar:/u0/Oracle/Middleware/EPMSystem11R1/common/jlib/11.1.2.0

/epm_thrift.jar com.uc4.ex.cit.UCXJCITX


10/94

6 Chapter 2 Installation and Configuration

2.2 Installing the Hyperion FM Agent in an

Existing Automation Engine System

This topic describes how to install the Hyperion FM agent in an existing Automation Engine system.

Java Requirements

On the host and each machine where an Automation Engine user interface is installed, check the

current version of your system's Java Virtual Machine (JVM) using the following command:

java -version

For platform-specific Java requirements on your Automation Engine machine, see your Automation

Engine release notes.

You can get the necessary files to install Java from

http://www.oracle.com/technetwork/java/index.html.

Supplied Files

The files that belong to the RA agent are stored in the Automation Engine's

IMAGE:AGENTS\RAPIDAUTOMATION directory. You can get updated files for another

Automation Engine release by downloading the image for that release from the Automic Download

Center .

File name Description

ucxjcitx.jar Agent for Rapid Automation

ucxjcitx.ini Configuration file

*.jar Libraries

uc.msl Message library

setup.exe The Windows installation executable for the RA agent core

Setting Trace Before Running the Installation or Upgrade of the

Agent

Before installing or upgrading the agent, it is a good idea to turn Rapid Automation trace on by

adding ra=99 in the ucxjcitx.ini file as shown below.[TRACE]file=..\temp\RA_TRACE_##.TXTmax_trace_kb=8000tcp/ip=0ra=99trccount=10

This will give more troubleshooting information if something goes wrong during the install. After a

successful agent install, you can set ra=0, and restart the agent to turn Rapid Automation trace off.

http://www.oracle.com/technetwork/java/index.htmlhttp://downloads.automic.com/http://downloads.automic.com/http://www.oracle.com/technetwork/java/index.html


11/94


Setting Up a New or Upgraded Agent

To set-up an RA agent, you need:

l A license loaded in the database for the agent.

l To put the agent files on the host machine.

l To edit theucxjcitx.ini file.l To execute the setup.exe file.

l To load the RA solution.

License File Requirement

License files for RA agents need to have a EX.RA. line in them and be loaded into

the database. For more information on loading keyfiles, see your Automation Engine

documentation.

Putting Agent Files on the Host Machine

On the host machine of the agent, create a directory for the RA agent and copy the supplied files

listed above to it using the instructions below for your operating system.

We highly recommend installing the agent in its own directory.

The Hyperion FM agent must be installed on Hyperion Financial Management system.

You can update the agent core by getting updated files for an Automation Engine release by

downloading the image for that release from the Automic Download Center and putting the agent

files in place following these instructions.

For UNIX

1. Create a directory. For example, AE/agent/rapidautomation.

2. Unpack the file using the following commands:

gunzip ucxjcitx.tar.gztar -xvf ucxjcitx.tar

For Windows

1. Create a directory. For example, C:\AE\agent\rapidautomation.

2. Execute the setup.exe file.

Creating the cache Directory

The RA Solution to be used by the agent will be stored in the directory named cache. Create this

directory in the installation directory.

Editing the ucxjcitx.ini File

Edit the required parameters in the ucxjcitx.ini file for the RA agent described in the table below.

Parameter Description

system Automation Engine system name. This entry must be identical to the entry in the .ini

file of the Automation Engine server.

http://downloads.automic.com/


12/94


Parameter Description

name Name of the agent. The agent name is limited to 32 of the following characters: "A-

Z", "0-9", "_", ".", "$", "@", "-" and "#".

Hyphens ("-") are only allowed in agent names. They must not be used in the names

of any other objects. Although agent names are limited to 32 characters, you should keep them under

25 characters. The last seven characters are used for adding the suffix

'.NEW.nn' when a new agent is created from its template.

cache_

directory

Directory to which the agent should store the RA solutions. This will be set to cache

by default and does not need to be altered unless you want to change it.

cp Address of the communication process in the Automation Engine system to which

the agent should connect itself. The format is:

:

ra Used for addit ional trace.

For information on the additional parameters in the ucxjcitx.ini file, see your Automation Engine

documentation.

A sample ucxjcitx.ini f ile is shown below. The required parameters are shown in bold:

[GLOBAL]name=RA01system=AElogcount=10logging=../temp/RA_LOG_##.TXT;LogMaxSize: 0...default, qualifiers k...Kilo, M...Mega, G...GigaLogMaxSize = 0language=Ehelplib=uc.msl

[RA]cache_directory=cacheext_directory=externalshared_directory=sharedlib_directory=lib

[TCP/IP]connect=20cp=localhost:2217

[AUTHORIZATION]KeyStore=InitialPackage=

[VARIABLES]uc_host_jcl_var=RAuc_ex_path_bin=.uc_ex_path_temp=..\temp\uc_ex_path_jobreport=..\temp\


13/94


[TRACE]file=..\temp\RA_TRACE_##.TXT;TraceMaxSize: 0...default, qualifiers k...Kilo, M...Mega, G...GigaTraceMaxSize=0tcp/ip=0ra=0

trccount=10

[CP_LIST]2218=PC01

Loading the RA Solution

On the host machine, start the utility AE.DB Load and select the RA Solution's .jar file. The utility

will then load it to the Automation Engine database. The .jar file can be loaded via the graphical

interface or the Java batch mode (ucybdbld.jar ) of the utility AE DB Load. Loading with the AE DB

Load in batch mode (ucybdbld.exe) under Windows is not possible.

The RA agent can only connect to one RA Solution. If you intend to use several RA Solutions,keep in mind that each solution requires its own RA agent.

You cannot load the same JAR file of an RA Solution to several systems at a time. Any attempt

to do so can cause the utility AE DB Load to abort.


14/94


2.3 Configuring System Objects

The following guide describes the specific configuration of an Automation Engine's system objects

that are required for the RA agent.

l Log on to your Automation Engine's system client.l Create and configure a Hyperion FM connection object.

l Create and configure a Hyperion FM agent object.

l Start the agent.

Connection Object

The connection object determines...

l Create a new Hyperion FM connection object (new object: CONN -> HYPERIONFM) and

open it.

Field Description

User Name The Hyperion FM user

Password The Hyperion FM password

Cluster The Hyperion FM cluster

l Store and close the object.

Agent Object

l Create a new HYPERIONFM AGENT agent object (preferably in the HOST folder)

Note that the object name must comply with the agent name that is used in the INI file.

The traffic light symbol in the tab's lower bar is shown in green if the agent is active.

There is nothing to define on the Hyperion FM agent's HyperionFM tab.

l Store and close the agent object.


15/94


Start the agent by using the following command:

java -jar


16/94


2.4 Specifying Automation Engine/Agent

Timeout Seconds

You can specify the timeout seconds between the Automation Engine v9/10/11 UserInterface and

Rapid Automation agents using the agentTimeout setting in the uc4config.xml file.

You can specify the timeout seconds between the Automation Engine v9/10/11 UserInterface and

Rapid Automation agents using the agentTimeout setting in the uc4config.xml file.

../../docu ../temp/UCDJ_LOG_##.TXT ../temp/UCDJ_TRC_

##.TXT 1 1 300

1048576 1048576

If no agentTimeout setting is specified, 100 seconds will be used.

When an agent times out, a pop-up error like the following will be returned.

A sample timeout error


17/94


3 Jobs

3.1 Creating JobsThis document describes how you can create jobs and the peculiarities that must be considered.

Once you have installed and configured the RA agent for Hyperion FM, you can create the

corresponding job objects (new object: JOBS -> HYPERIONFM -> ).

When you have created your jobs, you must enter the particular agent in the Attributes tab.

Verify that this agent is active and available. Otherwise, no data is available in the specific

HyperionFM object tabs.

The specific settings for the relevant action are available in the HyperionFM tab and are described

in the Job Types topics. The other tabs are all the same in each RA job. For further information, see

your Automation Engine documentation.


18/94

14 Chapter 3 Jobs

3.2 Job TypesThe Hyperion FM agent includes the following Hyperion Financial Management job types:

l Allocate

l Calculate

l Calculate Contribution

l Clear Data Slice

l Close Period

l Consolidate

l Copy Data

l Extract Data to Database

l Extract Data to Flat file

l Extract Journals

l Extract Member Lists

l Extract Metadata

l Extract Rules

l Extract Security

l Load Data

l Load Journals

l Load Member Lists

l Load Metadata

l Load Rules

l Load Security

l Translate


19/94


3.2.1 Creating an Allocate Job

This job type triggers the allocation action within Hyperion FM. The three main groups of data

allocation include allocating from one entity to many related entities, from one account to many

related accounts and from one period to a range of periods.

ALLOCATE Job

Field Description

Login data The Hyperion FM Connection Object.

Application The Hyperion FM application to log into.

POV The point of view (POV) which contains at least Scenario, Year, Period, Entity and

Value.

Format: S#.Y#.P#.E#.V#

Job Status

The status of the job is "ENDED_OK - ended normally" if the Allocate action returns 0. Otherwise itis "ENDED_NOT_OK".

Job Output

If the Allocate action returns 0, then "Execution of AllocationAction succeeded" appears in the

report. Otherwise, an error message is posted to the report.

In the report, you can also see the passed options, which are provided from the UserInterface.


20/94

16 Chapter 3 Jobs

Log messages from Hyperion Financial Management can only be correctly translated/displayed

in the job reports if they are either Latin-9 or UTF-16 encoded.


21/94


3.2.2 Creating a Calculate Job

This job type triggers the calculation action within Hyperion FM.

CALCULATE Job

Field Description



POV The point of view (POV) which contains at least Scenario, Year, Period, Entity andValue.


Force Forces a calculation.

Job Status

The status of the Job is "ENDED_OK - ended normally" if the Calculate action returns 0. Otherwise

it is "ENDED_NOT_OK".

Job Output

If the Calculate action returns 0, then "Execution of CalculationAction succeeded" appears in the

report. Otherwise, an error message is posted to the report.



22/94

18 Chapter 3 Jobs

Log messages from Hyperion Financial Management can only be correctly translated/displayedin the job reports if they are either Latin-9 or UTF-16 encoded.


23/94


3.2.3 Creating a Calculate Contribution Job

This job type executes a calculate contribution action within Hyperion FM.

CALCULATE_CONTRIBUTION Job

Field Description




Value.



Job Status

The status of the job is "ENDED_OK - ended normally" if the Calculate Contribution action returns

0. Otherwise it is "ENDED_NOT_OK".

Job Output

If the Calculate Contribution action returns 0, then "Execution of CalculationContributionActionsucceeded" appears in the report. Otherwise, an error message is posted to the report.



24/94

20 Chapter 3 Jobs



25/94


3.2.4 Creating a Clear Data Slice Job

This job type executes a clear data slice action within Hyperion FM.

CLEAR_DATA_SLICE Job

Field Description

Login data The H yperion F M Connection Object.


POV The point of view (POV) which contains at least Scenario, Year, Period,Entity and Value.

Format:

S#.Y#.P#.E#.V#

Clear Entity

Currency Data

When checked, entity currency data is cleared.

Default: Unchecked

Clear Rates and

System Data

When checked, rates and system data are cleared.

Default: Unchecked

Enable Detailed

Logging

When checked, detailed logging is enabled.

Default: Unchecked

Job Status

The status of the job is "ENDED_OK - ended normally" if the clear data slice action throws no

exception. Otherwise it is "ENDED_NOT_OK".

Job Output

If clear data slice finished successfully then "Execution of clear data slice succeeded" appears in

the report. Otherwise an error message is posted to the report.


26/94


27/94


3.2.5 Creating a Close Period Job

This job type triggers the close period action within Hyperion FM. It closes the journal-period for a

specific scenario and year.

CLOSE_PERIOD Job

Field Description



Scenario The scenario for the close period. This is a required field.

Year The year for the close period. This is a required field.

Period The period for the close period. This is a required field.

Job Status

The status of the Job is "ENDED_OK - ended normally" if the no exception occurs during the call of

close-period action through the HFM-API, otherwise it returns "ENDED_NOT_OK" and shows the

error in report.

Job Output

If any period parameter is empty, an appropriate error-message is shown. Also if an exception

occurs during call of HFM-API, the error message is posted to the report.

The report also shows the parameters passed along to the Hyperion FM API call which have been

entered in the user interface.

If the job is successful, the message: "Status: Close of period succeeded" is shown at the end of

the report.


28/94

24 Chapter 3 Jobs




29/94


3.2.6 Creating a Consolidate Job

This job type triggers the consolidation action within Hyperion FM.

CONSOLIDATE Job

Field Description




Value.


Type The consolidation type. Available options:

l Impacted

l All with data

l All

Job Status

The status of the Job is "ENDED_OK - ended normally" if the consolidation executed successfully.

Otherwise it is "ENDED_NOT_OK".

Job Output

If consolidate action returns 0 then "Execution of ConsolidateAction succeeded" appears in the

report. Otherwise an error message is posted to the report.

In the report you can also see the parameters passed along to the Hyperion FM API call which were

entered in the UserInterface.


30/94

26 Chapter 3 Jobs




31/94


3.2.7 Creating a Copy Data Job

This job type triggers the copy data action within Hyperion FM.

COPY_DATA Job

Field Description

Logindata The Hyperion FM Connection Object.


Source POV The source point of view (POV), three dimensions can be defined: Scenario(S),

Year(Y), Period(P), with one entry per dimension.

For example: S#Actual.Y#2006.P#June

CopyMembers

POV

The copy members point of view (POV), two dimensions can be defined: Account(A) and Entity(E), with more entries per dimension

For example: A#NetProfit.E#Sales

Destination

POV

The destination point of view (POV), three dimensions can be defined: Scenario

(S), Year(Y), Period(P), with one entry per dimension

For example: S#Actual.Y#2006.P#July


32/94

28 Chapter 3 Jobs

Field Description

Mode The mode. Allowed values:

l Merge

l Accumulate

l

ReplaceView The View. Allowed values:

l Periodic

l YTD

Multiplier The multiplier.

If Hyperion FM cannot process the input, the job will fail and with an according

error message.

Entity

Currency

Rate

The entity currency data.

Rates and

System Data

The rates and system data.

Cell Text The cell text.

Copy Derived

Data

The copy derived data.

Enable

Detailed

Logging

Whether to enable detailed logging.

Job Status

The status of the Job is "ENDED_OK - ended normally" if the no exception occurs during the call of

copy data action through the HFM-API, otherwise it returns "ENDED_NOT_OK" and shows the

error in report.

Job Output

The report also shows the parameters passed to the Hyperion FM API call which have been entered

in the user interface.

If an exception occurs during call of HFM-API, the error message is posted to the report.If the job is successful, the message: "Status: Execution of Copy Data succeeded" is shown at the

end of the report.


33/94




The Hyperion FM log is transfered to the report directory of the agent (typically "temp") and

registered as output file.

The prefix of the file name is "Log" followed by the RunID of the Job.

The report type of the Hyperion FM log in the Automation Engine is "W1".


34/94

30 Chapter 3 Jobs

3.2.8 Creating an Extract Data To Database Job

This job type triggers the execution of the extract data to database action in Hyperion FM and as a

result writes the extracted data into a database. The file is on the host where the agent is located.

Be aware that "Extract Data" influences "Line Item Option", "Extract Dynamic Accounts",

"Calculated Data" and "Derived Data". When "Extract Data" is unchecked these controls aredisabled and cannot be set.

EXTRACT_DATA_TO_DATABASE Job

Field Description

Login data The H yperion F M Connection Object.


POV The point of view (POV) which contains at least Scenario, Year, Period,Entity and Value.

For mat:

S#.Y#.P#.E#.V#

Extract format The Extract format. Allowed values:

l Metadata only (default)

l Selected metadata only

l Standard

l Essbase

l Data Warehouse


35/94


Field Description

Schema Actions The schema actions. Allowed values:

l Create Star Schema (default)

l Update Star Schema

l

Delete Star SchemaDestination

Datanase (DSN)

The Destination Database (DSN), which has to be predefined in Hyperion

FM.

Line Item Option The line item option. Allowed values:

l None (default)

l Total Summary for Cell

Relation Table

Prefix

The prefix.

Extract Data When checked, data is extracted.

Default: UncheckedExtract Dynamic

Accounts

When checked, dynamic accounts are extracted.

Default: Unchecked

Calculated Data When checked, data is calculated.

Default: Unchecked

Derived Data When checked, data is derived.

Default: Unchecked

Job Status

The Job status is "ENDED_NOT_OK - aborted" if an invalid POV is provided.

The status of the Job is "ENDED_OK - ended normally" otherwise.

Known issue: HFM API has issues with handling invalid DSNs as well as update and delete star

schema.

Job Output

The report tab of the job contains the job parameters and the result of the extract action.


36/94

32 Chapter 3 Jobs



All entries have a time stamp. The HFM log is transferred to the report directory of the agent

(typically "temp") and registered as output file.


The report type of the HFM log in the Automation Engine is "W1".


37/94


Special Case

When selecting "Delete Starschema" in Schema Actions Combobox, Hyperion FM does not

provide any taskID. Unfortunately the task then can not be monitored. We are working on a solution

on that topic.


38/94


39/94


40/94

36 Chapter 3 Jobs

Job Output








41/94




42/94

38 Chapter 3 Jobs

3.2.10 Creating an Extract Journals Job

Use Extract Journals jobs to extract journals from HFM into a file. This path refers to the file system

on the agent host computer.

EXTRACT_JOURNALS Job

Field Description


Application The Hyperion FM application to log into. This path refers to the file system on

the agent host computer (which is also the Hyperion FM file system).

File Name The name of the file witha .jlf extension to extract.


43/94


Field Description

Delimiter

character

The delimiter character. Allowed values:

l ; (default)

l ,

l

~l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

POV The point of view (POV) which contains at least Scenario, Year, Period, Entityand Value.

Format:

S#.Y#.P#.E#.V#

Labels Labels, list of Strings separated by ; (wildcard % can be used)

Groups Groups, list of Strings separated by ; (wildcard % can be used)

Extract

Journals

When checked, journals are extracted.

Default: Checked

Extract

Templates

When checked, templates are extracted.

Default: CheckedExtract

Recurring

Templates

When checked, recurring templates are extracted.

Default: Checked

Working Show working in the log.

Default: Checked

Submitted Show submitted in the log.

Default: Checked

Approved Show approved in the log.

Default: Checked

Rejected Show rejected inthe log.Default: Checked

Posted Show posted in the log.

Default: Checked

Regular Show regular in the log.

Default: Checked

Auto-reversing Show auto-reversing in the log.

Default: Checked

Auto-reversal Show auto-reversal in the log.

Default: Checked


44/94

40 Chapter 3 Jobs

Field Description

Balanced Show balanced in the log.

Default: Checked

Balanced by

Entity

Show balanced by entity in the log.

Default: Checked

Unbalanced Show unbalanced in the log.

Default: Checked

Job Status

The status of the Job is "ENDED_OK - ended normally" if the status is COMPLETED_

SUCCESSFULLY or COMPLETED_WITH_WARNINGS. The Job status is "ENDED_NOT_OK -

aborted" if the extract status is FAILED.

Job Output



45/94




All entries have a time stamp. The HFM log is transfered to the report directory of the agent


The options that are part of the option groups "Status", "Type", and "Balance Type" will only show

up in the report if they are selected. If they are selected, there will be a line in the report containing

text similar to this: "Filter by Status: JSF_WORKING".




46/94


47/94



The HFM Log has the Automic report type "W1".


48/94

44 Chapter 3 Jobs

3.2.12 Creating an Extract Metadata Job

This job type triggers the execution of the extract metadata action in Hyperion FM and as a result

writes the extracted metadata into a file. The file is on the host where the agent is located.

EXTRACT_METADATA Job

Field Description



File Name The name of the filewith an .xml or .app extension. This path refers to the file

system on the agent host computer (which is also the Hyperion FM file system).


49/94


Field Description

Delimiter

character


l ; (default)

l ,

l

~l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

File format The file format. Allowed values:

l Financial Management (.app)

l Financial Management (.xml)

Application

Settings

Extract application settings.

Default: Unchecked

Consolidation

Methods

Extract consolidation methods.

Default: Unchecked

Cell Text

Labels

Extract cell text labels.

Default: Unchecked

Values Extract values.Default: Unchecked

Scenarios Extract scenarios.

Default: Unchecked

Entities Extract entities.

Default: Unchecked

Accounts Extract accounts.

Default: Unchecked

Currencies Extract currencies.

Default: Unchecked

ICPs Extract ICPs.

Default: Unchecked

Custom

Dimensions

The custom dimensions to include. To define custom dimensions write the name

(s) in this field. Use ';' to separate various dimensions. Blank characters between

dimensions are allowed. When this field is left empty, no metadata for any

custom dimension is extracted.

Periods, Views, Years are always selected.


50/94

46 Chapter 3 Jobs

Job Status




Job Output








51/94




52/94

48 Chapter 3 Jobs

3.2.13 Creating an Extract Rules Job

This action extracts HFM rules.

EXTRACT_RULES Job

Field Description



File Name The name of the file with an .rle extension to extract to. This path refers to the file

system on the agent host computer (which is also the Hyperion FM file system).

Job Status

The status of the job is "ENDED_OK - ended normally" if the status is COMPLETED_



Job Output

The output contains the status and log file from HFM.


53/94






54/94

50 Chapter 3 Jobs

3.2.14 Creating an Extract Security Job

This action extracts security information from HFM into a file.

EXTRACT_SECURITY Job

Field Description



File Name The name of the filewith an .sec extension to extract to. This path refers to the

file system on the agent host computer (which is also the Hyperion FM file

system).

Delimiter

character


l ; (default)

l ,

l ~

l @

l #

l $l %

l ^

l &

l |

l :

l ?

l \

Extract Users

and Groups

When checked, users and groups are extracted to the file.

Default: Unchecked


55/94


Field Description

Extract

Security

Classes

When checked, security classes are extracted to the file.

Default: Unchecked

Extract Role

Access

When checked, role access is extracted to the file.

Default: Unchecked

Extract

Security

Class Access

When checked, security class access is extracted to the file.

Default: Unchecked

Job Status




Job Output

The output contains the status and log file from HFM..





56/94

52 Chapter 3 Jobs


57/94


3.2.15 Creating a Load Data Job

This action loads data from a file into HFM. If the agent is not running the Browse button is disabled.

Be aware that "File contains process management data" cannot be used together with "File

contains ownership data" and/or "Accumulate within File". If you select these options together, one

or both are programmatically disabled. Also, if you check "File contains process management data","Load Mode" will only support the "Replace" and "Merge" options.

LOAD_DATA Job

Field Description



File Name The name of the fileto load (witha .dat extension). To browse the agent file

system (which is also the of the Hyperion FM file system) for the file, use the

Browse button. If there is no connection to the agent, the Browse button is

disabled.


58/94

54 Chapter 3 Jobs

Field Description

Delimiter

character


l ; (default)

l ,

l

~l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

Load Mode Allows you to select the load mode:

l Merge

l Replace by security

l Replace

l Accumulate

File contains

ownership

data

When checked, the file will contain ownership data.

Default: Unchecked

File contains

process

managementdata

When checked, the file will contain process management data.

Default: Unchecked

"File contains process management data" cannot be used together with "File

contains ownership data" and/or "Accumulate within File". If you select these

options together, one or both are programmatically disabled.

If you check "File contains process management data", "Load Mode" will only

support the "Replace" and "Merge" options.

Accumulate

within file

When checked, the file will accumulate within the file.

Default: Unchecked

Scan only When checked, a scan is done, but the list is not loaded.

Default: Unchecked

Job Status

The load process may run for a long time. After the process has been triggered the status is polled

every 3 seconds. The Job remains active until the load process has finished.

The status of the Job is "ENDED_OK - ended normally" if the status is COMPLETED. The Job

status is "ENDED_NOT_OK - aborted" if the load status is ABORTED, NOT_RESPONDING or

STOPPED.

Further it is "ENDED_NOT_OK - aborted" if the wrong load mode (either "Replace by security" or

"Accumulate") is selected for "File contains process management data".


59/94


If you choose "Replace by security" or "Accumulate" then the JOBS will ENDED_NOT_OK with an

error like "Error: Invalid duplicate handling 'Replace by Security'".

Job Output

The report tab of the job contains the job parameters and the result of the load action.Every 3 seconds (status check) the progress of the load task is written to the report.

In addition the remote status of the Job which is updated in the Job check interval will show the

completion rate in percent for long running jobs.



The Log of the load process is added in a new report tab. The file name is "Log" followed by the

RunID of the Job.



60/94

56 Chapter 3 Jobs


61/94


3.2.16 Creating a Load Journals Job

This action loads Journals from a file into HFM.

LOAD_JOURNALS Job

Field Description



File Name The name of the file to load (with a .jlf extension). To browse the agent file system

(which is also the of the Hyperion FM file system) for the file, use the Browse

button. If there is no connection to the agent, the Browse button is disabled.

Delimiter

character


l ; (default)

l ,

l ~

l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

Job Status


SUCCESSFULLY or COMPLETED_WITH_WARNINGS.The Job status is "ENDED_NOT_OK -

aborted" if the load status is FAILED.


62/94

58 Chapter 3 Jobs

Job Output

The report tab of the job contains the job parameters and the result of the load action.



All entries have a timestamp. The HFM log is transfered to the report directory of the agent (typically

"temp") and registered as output file.




63/94


3.2.17 Creating a Load Member Lists Job

This action loads member lists into HFM.

LOAD_MEMBER_LISTS Job

Field Description



File Name The name of the file to load (with an .lsy extension). To browse the agent file



disabled.


Default: Unchecked

Job Status




Job Output



64/94

60 Chapter 3 Jobs








65/94


3.2.18 Creating a Load Metadata Job

This job type triggers an action within Hyperion FM that loads metadata into Hyperion FM. The

metadata is contained in a file that needs to be located on the host of the agent.

LOAD_METADATA Job

Field Description



File Name The name of the fileto load (with an .xml extension). To browse the agent file


Browse button. If there is no connection to the agent, the Browse button isdisabled.


66/94


67/94


Field Description

Accounts When checked, accounts are loaded.

Default: Unchecked

Currencies When checked, currencies are loaded.

Default: Unchecked

ICPs When checked, ICPs are loaded.

Default: Unchecked

Custom

Dimensions

The custom dimensions to include. To define custom dimensions write the name

(s) in this field. Use ';' to separate various dimensions. Blank characters between

dimensions are allowed. When this field is left empty, no metadata for any

custom dimension is loaded.

Periods, Views, Years are always selected.

Job Status




Job Output





68/94


69/94


3.2.19 Creating a Load Rules Job

This action loads rules from a file into HFM.

LOAD_RULES Job

Field Description



File Name The name of the file to load (with an .rle extension). To browse the agent file system

(which is also the of the Hyperion FM file system) for the file, use the Browse

button. If there is no connection to the agent, the Browse button is disabled.

Check

Integrity

When checked, integrity is checked.

Default: Unchecked


Default: Unchecked

Job Status




Job Output



70/94

66 Chapter 3 Jobs








71/94


3.2.20 Creating a Load Security Job

This action loads security information into HFM.

LOAD_SECURITY Job

Field Description


Application The Hyperion FM application to log into.File Name The name of the fileto load (with an .sec extension). To browse the agent file



disabled.

Delimiter

character


l ; (default)

l ,

l ~

l @

l

#l $

l %

l ^

l &

l |

l :

l ?

l \


72/94

68 Chapter 3 Jobs

Field Description

Clear

Security

Information

Before

Loading

When checked, security information is cleared before loading.

Default: Unchecked

Load Users

and Groups

When checked, users and groups are loaded.

Default: Unchecked

Load

Security

Classes

When checked, security classes are loaded.

Default: Unchecked

Load Role

Access

When checked, role access is loaded.

Default: Unchecked

Load

Security

Class Access

When checked, security class access isloaded.

Default: Unchecked

Job Status




Job Output





73/94







74/94

70 Chapter 3 Jobs

3.2.21 Creating a Translate Job

This job type triggers the translation of data within Hyperion FM. Translation in the context of

Hyperion FM means converting financial data between currencies.

TRANSLATE Job

Field Description




Value.



Job Status

The status of the job is "ENDED_OK - ended normally" if the Translation action returns 0.

Otherwise it is "ENDED_NOT_OK".

Job Output

If translate action returns 0 then "Execution of TranslateAction succeeded" appears in the report.

Otherwise a error message is posted to the report.

In the report you can also see the passed options which are provided from the UserInterface.


75/94





76/94

72 Chapter 3 Jobs

3.3 Creating Workflows with Hyperion FM

Jobs

This document describes how you can create jobs and the peculiarities that must be considered.

Automating Hyperion Financial Management (HFM) allows companies financial consolidation,

reporting, and analysis processes involving HFM are more consistent, visible, and controllable.

Exemplary features that covered by Automic's Hyperion FM RA Solution and Automation Engine

include:

l Translating and calculating all base entities.

l Loading data files and consolidating data.

l Extracting data from one application and loading it into another Application.

l Reconsolidating all prior periods and scenarios.

l Regularly consolidating main points of view overnight during the close process.

Since the HFM actions are implemented as individual job types, the solution provides maximum

flexibility.

With this flexibility it is possible to model custom use cases as workflows within Automic that

perfectly fit the needs of any use case.

For example, in order to load data into Hyperion FM, then consolidate the data and finally close a

period, you simply create jobs of type LOAD_DATA, CONSOLIDATE and CLOSE_PERIOD and

then arrange them in a workflow as shown below.


77/94


3.4 Managing Output and Execution Options

with the RA Tab

Using the RA tab, you can specify how job reports are saved, whether they include agent log

information, and whether the information from the RA agent-specific tab is displayed whenexecuting the job.

Using the RA tab, you can specify how job reports are saved, whether they include agent log

information, and whether the information from the RA agent-specific tab is displayed when

executing the job. A sample RA tab for a job is shown below.

A sample RA tab for a Rapid Automation Hyperion FM job

Options on the RA tab for jobs are described in the table below.

Field Description

Database When checked, the job report is managed in the Automation Engine. After the

execution of a job, the process protocol is transferred to the Automation Engine

database via file transfer.

File When checked, the job report is managed in the Automation Engine. After the

execution of a job, the process protocol is available in the target system as a file.

Generate

on error only

When checked, the job report is stored in the Automation Engine database and/or a

file in the target system only if the job has been canceled. This function is onlyavailable when Database and/or File are checked.

Agent log When checked, job reports will include an agent log tab with an agent log when

there are errors. Keeping this box checked is recommended for troubleshooting

purposes.

Request

task

parameters

When checked, the information from the job's RA agent-specific tab is available in

the pop-up window when you execute the job. From this window, you can make one

time changes for a single run of the job. Some fields from RA agent-specific tabs

can only be set in job definitions. These fields are not included in the pop-up window

when the job is requested and the Request task parameters option is checked. A

pop-up window for a sample job is shown below.


78/94

74 Chapter 3 Jobs

When Request task parameters is checked, you can edit the information from the job's RA-specific tab for asingle run of the job.


79/94


3.5 Hyperion FM Job Attributes

You can read and set the specific attributes of Hyperion FM jobs by using the script elements

:GET_ATT and :PUT_ATT. This topic lists the available attributes for Hyperion FM jobs by job

type. Job attributes are case-sensitive.

Allocate Jobs

Field XML Name Available Values

Login data CONNECTION String

Application APPLICATION String

POV POV String

Calculate Jobs




POV POV String

Force FORCE l true

l false

Calculate Contribution Jobs

Field XML Name Available ValuesLogin data CONNECTION String


POV POV String

Force FORCE l true

l false

Clear Data Slice Jobs




POV POV String

Clear Entity Currency Data CLEARCURRENCY l true

l false

Clear Rates and System Data CLEARRATES l true

l false


80/94

76 Chapter 3 Jobs


Enable Detailed Logging DETAILEDLOGGING l true

l false

Close Period JobsField XML Name Available Values



Scenario SCENARIO String

Year YEAR String

Period PERIOD String

Consolidate JobsField XML Name Available Values



POV POV String

Type TYPE l Impacted

l All With Data

l All_With_Data

l All

Copy Data Jobs




Source POV SOURCEPOV String

Copy Members POV COPYMEMBERSPOV String

Destination POV DESTINATIONPOV String

Mode MODE String

View VIEW String

Multiplier MULTIPLIER Decimal

Entity Currency Rate ENTITYCURRENCYDATA l true

l false

Rates and System Data RATESANDSYSTEMDATA l true

l false

Cell Text CELLTEXT l true

l false


81/94



Copy Derived Data COPYDERIVEDDATA l true

l false

Enable Detailed Logging ENABLEDETAILEDLOGGING l true

l

false

Extract Data To Database Jobs




POV POV String

Extract format EXTRACTFORMAT l Metadata only

l Selected

metadata onlyl Standard

l Essbase

l Data

Warehouse

Schema Actions SCHEMAACTION l Create Star

Schema

l Update Star

Schema

l Delete Star

Schema

Destination Datanase (DSN) DSN String

Line Item Option LINEITEMOPTION l None

l Total Summary

for Cell

Relation Table Prefix PREFIX String

Extract Data DATA l true

l false

Extract Dynamic Accounts DYNAMICACCOUNTS l true

l false

Calculated Data CALCULATEDDATA l true

l false

Derived Data DERIVEDDATA l true

l false

Extract Data To Flatfile Jobs





82/94

78 Chapter 3 Jobs


POV POV String

File name DATAFILE String

Delimiter character DELIMITER l ;

l ,l ~

l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

Extract format EXTRACTFORMAT l Flatfile - without

header

l Flatfile - with

header

Line Item Option LINEITEMOPTION l None

l Individual Line

Items

l Total Summary

for Cell

Extract File Prefix PREFIX String

Extract data DATA l true

l false

Extract dynamic accounts DYNAMICACCOUNTS l true

l false

Calculated data CALCULATEDDATA l true

l false

Derived data DERIVEDDATA l true

l false

Cell description CELLDESC l truel false

Phased submission group

data

PHASEDSUBMISSIONGROUPDATA l true

l false

Extract Member Lists Jobs




File Name DATAFILE String


83/94


Extract Journals Jobs






l ,

l ~

l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

POV POV String

Labels LABELS String

Groups GROUPS String

Extract Journals EXTRACTJOURNALS l true

l false

Extract Templates EXTRACTTEMPLATES l true

l false

Extract Recurring Templates RECURRINGTEMPLATES l true

l false

Working WORKING l true

l false

Submitted SUBMITTED l true

l false

Approved APPROVED l true

l false

Rejected REJECTED l true

l false

Posted POSTED l true

l false

Regular REGULAR l true

l false

Auto-reversing AUTOREVERSING l true

l false


84/94

80 Chapter 3 Jobs


Auto-reversal AUTOREVERSAL l true

l false

Balanced BALANCED l true

l

falseBalanced by Entity BALANCEDBYENTITY l true

l false

Unbalanced UNBALANCED l true

l false

Extract Metadata Jobs






l ,

l ~

l @

l #

l $

l %

l ^

l &l |

l :

l ?

l \

File format FILEFORMAT l app

l xml

Application Settings APPLICATIONSETTINGS l true

l false

Consolidation Methods CONSOLIDATIONMETHODS l true

l false

Cell Text Labels CELLTEXTLABELS l true

l false

Accounts SYSTEMACCOUNTS l true

l false

Values VALUES l true

l false

Scenarios SCENARIOS l true

l false


85/94


86/94

82 Chapter 3 Jobs

Load Data Jobs






l ,

l ~

l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

Load Mode LOADMODE l Merge

l Replace by

Security

l Replace

l Accumulate

File contains ownership data OWNERSHIPDATA l true

l false

File contains ownership data PROCESSDATA l true

l false

Accumulate within file ACCUMULATE l true

l false

Scan only SCANONLY l true

l false

Load Journals Jobs

Field XML Name Available ValuesLogin data CONNECTION String


Application DATAFILE String


87/94


88/94

84 Chapter 3 Jobs


Clear metadata and data CLEARMETAANDDATA l true

l false


l

false Application Settings APPLICATIONSETTINGS l true

l false

Consolidation Methods CONSOLIDATIONMETHODS l true

l false

Cell Text Labels CELLTEXTLABELS l true

l false

System Accounts SYSTEMACCOUNTS l true

l false

Values VALUES l truel false

Scenarios SCENARIOS l true

l false

Entities ENTITIES l true

l false

Accounts ACCOUNTS l true

l false

Currencies CURRENCIES l true

l

falseICPs ICPS l true

l false

Custom Dimensions CUSTOMDIMENSIONS String

Load Rules Jobs





Check Integrity CHECKINTEGRITY l true

l false


l false

Load Security Jobs




89/94






l ,l ~

l @

l #

l $

l %

l ^

l &

l |

l :

l ?

l \

Clear Security Information Before Loading CLEARALL l true

l false

Load Users and Groups LOADUSERS l true

l false

Load Security Classes SECURITYCLASSES l true

l false

Load Role Access ROLEACCESS l true

l false

Load Security Class Access SECURITYCLASSACCESS l truel false

Translate Jobs




POV POV String

Force FORCE l true

l false


90/94

86 Chapter 3 Jobs

3.6 Setting Trace

When you need to troubleshoot a Rapid Automation agent, you can turn on Rapid Automation trace

for AGENT and JOBS objects from either the System Overview window in the Automation Engine

user interface or the ucxjcitx.ini file. You can turn on Rapid Automation user interface trace from the

uc4config.xml file.

Turning Rapid Automation Trace On or Off From the System

Overview Window

To turn on trace for Rapid Automation AGENT and JOBS objects in the user interface, go to

System Overview window, right-click the agent, pick Properties. In the window that pops up, set

RA to 9 to turn trace on or set RA to 0 to turn trace off.

Turning Rapid Automation Trace On or Off From the ucxjcitx.ini

File

To turn on trace for Rapid Automation AGENT and JOBS objects with the ucxjcitx.ini file:

1. Stop the agent(s) from the ServiceManager window or command line.

2. Edit the ucxjcitx.ini file.

To turn trace: Set:

On for the Rapid automation agent, and its third-party libraries ra=99

Off ra=0

Third-party library trace can only be set in the ucxjcitx.ini file. It cannot be set through

the UserInterface like for other agents

3. In the code below, ra=9 turns Rapid Automation trace on:

[TRACE]file=..\temp\RA_TRACE_##.TXTmax_trace_kb=8000tcp/ip=0ra=9trccount=10

4. Restart the agent(s).

Turning On Rapid Automation User Interface TraceTo turn on Rapid Automation user interface trace:

1. Exit out of the Automation Engine user interface.

2. From the uc4config.xml file, add ra="9" to the trace line as shown below:

..\temp\UCDJ_TRC_

##.TXT

3. Open the user interface.

Turning Off Rapid Automation User Interface Trace

To turn off Rapid Automation user interface trace:


91/94


1. Exit out of the Automation Engine user interface.

2. From the uc4config.xml file, add ra="0" to the trace line as shown below:

..\temp\UCDJ_TRC_##.TXT

3. Open the user interface.

For more information on setting trace, see your Automation Engine documentation.


92/94


93/94


94/94

90 Release Notes

l Close Period

l Consolidate

l Copy Data

l Extract Data to Database

l Extract Data to Flat file

l

Extract Journalsl Extract Member Lists

l Extract Metadata

l Extract Rules

l Extract Security

l Load Data

l Load Journals

l Load Member Lists

l Load Metadata

l Load Rules

l Load Security

l

TranslateThe user interface and documentation for this agent are currently available only in English.

ra.hyperionfm 1 0 0 hyperion 1.0 agent guide en (1)

Documents