oracle.epm.api.script

Class EpmScript

java.lang.Object

groovy.lang.GroovyObjectSupport

groovy.lang.Script

oracle.epm.api.script.EpmScript

All Implemented Interfaces:

groovy.lang.GroovyObject

public abstract class EpmScript
extends groovy.lang.Script

This object represents a Groovy script and is the base class for all EPM Groovy scripts. All methods on this class are available to be called directly in EPM Groovy scripts.

By default, parameters are case insensitive and may not be null or empty unless otherwise specified.

Constructor Summary

Constructors

Constructor and Description
EpmScript() Constructs an instance of this class with default parameters.

Method Summary

Modifier and Type	Method and Description
Connection	connection(java.lang.String url, java.lang.String userName, java.lang.String password) Returns a new connection to the resource identified by the sepcified URL.
oracle.epm.api.model.DataExportCsvWriter	createEpmCellCsvWriter(java.io.Writer writer, java.util.Collection<Dimension> rowDimensions, java.util.Collection<Member> columnMembers) Creates and returns a new cell based CSV writer.
oracle.epm.api.model.DataExportCsvWriter	createEpmCellCsvWriter(java.io.Writer writer, java.util.Collection<Dimension> rowDimensions, java.util.Collection<Member> columnMembers, char delimiter) Creates and returns a new cell based CSV writer.
oracle.epm.api.model.DataExportCsvWriter	createEpmColumnCsvWriter(java.io.Writer writer, java.util.Collection<Dimension> rowDimensions, java.util.Collection<Member> columnMembers) Creates and returns a new column based CSV writer.
oracle.epm.api.model.DataExportCsvWriter	createEpmColumnCsvWriter(java.io.Writer writer, java.util.Collection<Dimension> rowDimensions, java.util.Collection<Member> columnMembers, char delimiter) Creates and returns a new column based CSV writer.
java.io.PrintWriter	createFilePrintWriter(java.lang.String fileName) Creates and returns a new file PrintWriter.
java.io.PrintWriter	createFilePrintWriter(java.lang.String fileName, java.lang.String charsetName, boolean forceBomIfPossible) Creates and returns a new file PrintWriter.
java.io.Writer	createFileWriter(java.lang.String fileName) Creates and returns a new file writer.
java.io.Writer	createFileWriter(java.lang.String fileName, java.lang.String charsetName, boolean forceBomIfPossible) Creates and returns a new file writer.
RowData	createRowData(Tuple rowMembersTuple, java.util.Collection<Member> columnMembers, java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues) Returns the newly created RowData with the specified members and data.
RowData	createRowData(Tuple rowMembersTuple, java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues) Returns the newly created RowData with the specified members and data.
RowData	createRowData(Tuple rowMembersTuple, java.util.Set<Member> columnMembers, java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues) Returns the newly created RowData with the specified members and data.
java.io.Writer	createZipFileWriter(java.lang.String zipFileName, java.lang.String innerFileName) Creates and returns a new zip file writer.
java.lang.String	cscParams(java.util.Collection<?> items) Returns a string value with each of the specified items flattened, quoted and seperated by a comma.
java.lang.String	cscParams(java.lang.Object... items) Returns a string value with each of the specified items flattened, quoted and seperated by a comma.
CloseableIterator<java.lang.String[]>	csvIterator(java.lang.String inputFileName) Returns an iterator to iterate over the rows of a CSV file from the outbox.
CloseableIterator<java.lang.String[]>	csvIterator(java.lang.String inputFileName, char separator) Returns an iterator to iterate over the rows of a CSV file from the outbox.
CloseableIterator<java.lang.String[]>	csvIterator(java.lang.String inputFileName, java.lang.String separator) Returns an iterator to iterate over the rows of a CSV file from the outbox.
CsvWriter	csvWriter(java.lang.String outputFileName) Returns a CsvWriter to write values to a CSV file on the outbox using a comma for the separator and quoting only values that are required to be quoted.
CsvWriter	csvWriter(java.lang.String outputFileName, boolean quoteAllValues) Returns a CsvWriter to write values to a CSV file on the outbox using a comma for the separator and quoting based on the option provided.
CsvWriter	csvWriter(java.lang.String outputFileName, char separator) Returns a CsvWriter to write values to a CSV file using using a comma for the separator and quoting only values that are required to be quoted.
CsvWriter	csvWriter(java.lang.String outputFileName, char separator, boolean quoteAllValues) Returns a CsvWriter to write values to a CSV file on the outbox using the separator and quoting based on the options provided.
CsvWriter	csvWriter(java.lang.String outputFileName, java.lang.String separator) Returns a CsvWriter to write values to a CSV file on the outbox using the separator provided and quoting only values that are required to be quoted.
CsvWriter	csvWriter(java.lang.String outputFileName, java.lang.String separator, boolean quoteAllValues) Returns a CsvWriter to write values to a CSV file on the outbox using the separator and quoting based on the options provided.
long	currentTimeMillis() Returns the current time in milliseconds.
Job	executeJob(JobDefinition jobDef) Executes the job with the specified job definition and returns the job once it has completed or failed.
java.lang.String	fixValues(EssbaseCompatible... objects) Returns a string value for the specified objects that can be plugged into a Essbase calc script FIX command.
Rule	getCurrentRule() Returns the current rule being executed.
long	getEntryId(java.lang.String smartListName, java.lang.String smartListEntryName) Returns the smart list entry id for the specified smart list name and entry name.
oracle.epm.api.epmctl.EpmAutomate	getEpmAutomate() Returns an EpmAutomate instance class.
java.util.Map<java.lang.String,RtpValue>	getRtps() Returns an unmodifiable map of RtpValue objects for the run time prompts used in this script.
Rule	getRule() Returns the current rule being executed.
int	getTextCellId(java.lang.String textVal, boolean createIfNotFound) Returns the text cell id for the specified text value or 0 if the text value is not found and createIfNotFound is false.
java.lang.String	json(java.util.Map<java.lang.String,?> input) Returns a JSON string for the specified input map.
java.lang.String	mdxParams(java.lang.Object... items) Returns a string value with each of the specified items flattened, evaluated and converted to MDX delimited identifiers and separated by a comma.
GroovyMessageBundle	messageBundle(java.util.Map<java.lang.String,java.lang.String> resourceMap) Returns a new in memory resource bundle that contains locale-specific resources provided to it.
GroovyResourceBundleLoader	messageBundleLoader(java.util.Map<java.lang.String,GroovyMessageBundle> messageBundleMap) Returns a resource bundle loader that manages message bundles by locale.
long	nanoTime() Returns the current value of the running Java Virtual Machine's high-resolution time source, in nanoseconds.
void	print(java.lang.Object value) Prints the value to the current operation's job details, which can be viewed from the job console.
void	printf(java.lang.String format, java.lang.Object value) Prints a formatted string using the specified format string and argument to the current operation's job details, which can be viewed from the job console.
void	printf(java.lang.String format, java.lang.Object[] values) Prints a formatted string using the specified format string and arguments to the current operation's job details, which can be viewed from the job console.
void	println() Prints a newline to the current operation's job details, which can be viewed from the job console.
void	println(java.lang.Object value) Prints the value and a newline to the current operation's job details, which can be viewed from the job console.
java.lang.String	stripQuotes(java.lang.String text) Return the specified text with double quotation removed.
void	throwVetoException(GroovyResourceBundleLoader rbl, java.lang.String resourceKey, java.lang.Object... parameters) Throws an exception indicating that the operation in progress must be vetoed.
void	throwVetoException(com.hyperion.planning.HspDynamicLocalizedException cause) Throws an exception indicating that the operation in progress must be vetoed.
void	throwVetoException(com.hyperion.planning.HspLocalizedException cause) Throws an exception indicating that the operation in progress must be vetoed.
void	throwVetoException(java.lang.String message) Throws an exception indicating that the operation in progress must be vetoed.
void	validateRtp(RtpValue rtp, oracle.epm.api.model.Predicate<RtpValue> predicate, GroovyResourceBundleLoader rbl, java.lang.String resourceKey, java.lang.Object... parameters) Validates the run time prompt value against the specified predicate.
void	validateRtp(RtpValue rtpValue, java.lang.String pattern, GroovyResourceBundleLoader rbl, java.lang.String resourceKey, java.lang.Object... parameters) Validates the run time prompt value against the specified regular expression pattern.
Workbook	workbook() Returns a newly created empty Excel workbook.
java.util.zip.ZipInputStream	zipInputStream(java.lang.String fileName) Returns a zip input stream wrapping the specified file in the outbox folder.
java.util.zip.ZipOutputStream	zipOutputStream(java.lang.String fileName) Returns a zip output stream wrapping the specified file in the outbox folder.

Methods inherited from class groovy.lang.Script

evaluate, evaluate, getBinding, getProperty, invokeMethod, run, run, setBinding, setProperty

Methods inherited from class groovy.lang.GroovyObjectSupport

getMetaClass, setMetaClass

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EpmScript

public EpmScript()

Constructs an instance of this class with default parameters.

Method Detail

connection

public Connection connection(java.lang.String url,
                             java.lang.String userName,
                             java.lang.String password)

Returns a new connection to the resource identified by the sepcified URL.

Parameters:

url - resource URL

userName - name of the user

password - password for the user

Returns:

a new connection to the resource identified by the sepcified URL

createEpmCellCsvWriter

public oracle.epm.api.model.DataExportCsvWriter createEpmCellCsvWriter(java.io.Writer writer,
                                                                       java.util.Collection<Dimension> rowDimensions,
                                                                       java.util.Collection<Member> columnMembers)

Creates and returns a new cell based CSV writer.

Example data file for cell Format:

"Years","Scenario","Version","Currency","Entity","Grades","Employee","Account","Period"
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Jan",5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Feb",5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Mar",4
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Jan",0.1
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Feb",0.5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Mar",0.15

Parameters:

writer - writer write to

rowDimensions - names of dimenisons for row members

columnMembers - names of cloumn members

Returns:

Creates and returns a new cell based CSV writer

createEpmCellCsvWriter

public oracle.epm.api.model.DataExportCsvWriter createEpmCellCsvWriter(java.io.Writer writer,
                                                                       java.util.Collection<Dimension> rowDimensions,
                                                                       java.util.Collection<Member> columnMembers,
                                                                       char delimiter)

Creates and returns a new cell based CSV writer.

Example data file for cell Format:

"Years","Scenario","Version","Currency","Entity","Grades","Employee","Account","Period"
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Jan",5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Feb",5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price","Mar",4
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Jan",0.1
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Feb",0.5
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage","Mar",0.15

Parameters:

writer - writer write to

rowDimensions - names of dimenisons for row members

columnMembers - names of cloumn members

delimiter - delimiter to use, defaults to ','

Returns:

Creates and returns a new cell based CSV writer

createEpmColumnCsvWriter

public oracle.epm.api.model.DataExportCsvWriter createEpmColumnCsvWriter(java.io.Writer writer,
                                                                         java.util.Collection<Dimension> rowDimensions,
                                                                         java.util.Collection<Member> columnMembers)

Creates and returns a new column based CSV writer.

Example data file for Column Format:

"Years","Scenario","Version","Currency","Entity","Grades","Employee","Account","Period"
"Jan","Feb","Dec"
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price",5,5,4
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage",0.1,0.5,0.15

Parameters:

writer - writer write to

rowDimensions - names of dimenisons for row members

columnMembers - names of cloumn members

Returns:

Creates and returns a new column based CSV writer

createEpmColumnCsvWriter

public oracle.epm.api.model.DataExportCsvWriter createEpmColumnCsvWriter(java.io.Writer writer,
                                                                         java.util.Collection<Dimension> rowDimensions,
                                                                         java.util.Collection<Member> columnMembers,
                                                                         char delimiter)

Creates and returns a new column based CSV writer.

Example data file for Column Format:

"Years","Scenario","Version","Currency","Entity","Grades","Employee","Account","Period"
"Jan","Feb","Dec"
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Price",5,5,4
"FY19","Current","BU Version_1","EUR","CA","Grade 1","Employee 1","Discount Percentage",0.1,0.5,0.15

Parameters:

writer - writer write to

rowDimensions - names of dimenisons for row members

columnMembers - names of cloumn members

delimiter - delimiter to use, defaults to ','

Returns:

Creates and returns a new column based CSV writer

createFilePrintWriter

public java.io.PrintWriter createFilePrintWriter(java.lang.String fileName)
                                          throws java.io.UnsupportedEncodingException,
                                                 java.io.FileNotFoundException

Creates and returns a new file PrintWriter.

The file will be available in the Outbox when the writer is closed.

Example call from Groovy:

 /*RTPS: */
 createFilePrintWriter('test.log').withCloseable() { out ->
   out.println 'Hello World!'
 }
 

Parameters:

fileName - name of the file to create

Returns:

Creates and returns a new file PrintWriter

Throws:

java.io.UnsupportedEncodingException - if the UTF-8 charset is not supported

java.io.FileNotFoundException - if an exception occurs when opening or creating a new file with the specified name, possibly due to an invalid file name or illegal characters

createFilePrintWriter

public java.io.PrintWriter createFilePrintWriter(java.lang.String fileName,
                                                 java.lang.String charsetName,
                                                 boolean forceBomIfPossible)
                                          throws java.io.FileNotFoundException,
                                                 java.io.IOException

Creates and returns a new file PrintWriter.

The file will be available in the Outbox when the writer is closed.

Example call from Groovy:

 /*RTPS: */
 createFilePrintWriter('test.log').withCloseable() { out ->
   out.println 'Hello World!'
 }
 

Parameters:

fileName - name of the file to create

charsetName - name of the requested charset

forceBomIfPossible - if true, the byte order mark will be added to the writer for the following charsets: UTF_8, UTF_16, UTF_16LE, UTF_16BE

Returns:

Creates and returns a new file PrintWriter

Throws:

java.io.FileNotFoundException - if an exception occurs when opening or creating a new file with the specified name, possibly due to an invalid file name or illegal characters

java.io.IOException - if an I/O error occurs

java.nio.charset.IllegalCharsetNameException - - If the given charset name is illegal

java.lang.IllegalArgumentException - - If the given charsetName is null

java.nio.charset.UnsupportedCharsetException - - If the specified charset is not supported

createFileWriter

public java.io.Writer createFileWriter(java.lang.String fileName)
                                throws java.io.UnsupportedEncodingException,
                                       java.io.FileNotFoundException

Creates and returns a new file writer.

The file will be available in the Outbox when the writer is closed.

Parameters:

fileName - name of the file to create

Returns:

Creates and returns a new file writer

Throws:

java.io.UnsupportedEncodingException - if the UTF-8 charset is not supported

java.io.FileNotFoundException - if an exception occurs when opening or creating a new file with the specified name, possibly due to an invalid file name or illegal characters

createFileWriter

public java.io.Writer createFileWriter(java.lang.String fileName,
                                       java.lang.String charsetName,
                                       boolean forceBomIfPossible)
                                throws java.io.FileNotFoundException,
                                       java.io.IOException

Creates and returns a new file writer.

The file will be available in the Outbox when the writer is closed.

Parameters:

fileName - name of the file to create

charsetName - name of the requested charset

forceBomIfPossible - if true, the byte order mark will be added to the writer for the following charsets: UTF_8, UTF_16, UTF_16LE, UTF_16BE

Returns:

Creates and returns a new file writer

Throws:

java.io.FileNotFoundException - if an exception occurs when opening or creating a new file with the specified name, possibly due to an invalid file name or illegal characters

java.io.IOException - if an I/O error occurs

java.nio.charset.IllegalCharsetNameException - if the given charset name is illegal

java.lang.IllegalArgumentException - if the given charsetName is null

java.nio.charset.UnsupportedCharsetException - if the specified charset is not supported

createRowData

public RowData createRowData(Tuple rowMembersTuple,
                             java.util.Collection<Member> columnMembers,
                             java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues)

Returns the newly created RowData with the specified members and data.

Parameters:

rowMembersTuple - row dimension to members map

columnMembers - column members

columnMemberNamesToValues - column member names to values map

Returns:

the newly created RowData with the specified members and data

createRowData

public RowData createRowData(Tuple rowMembersTuple,
                             java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues)

Returns the newly created RowData with the specified members and data.

The column members from the first RowData of the current data export will be used.

Parameters:

rowMembersTuple - row dimension to members map

columnMemberNamesToValues - column member names to values map

Returns:

the newly created RowData with the specified members and data

createRowData

public RowData createRowData(Tuple rowMembersTuple,
                             java.util.Set<Member> columnMembers,
                             java.util.Map<java.lang.String,java.lang.String> columnMemberNamesToValues)

Returns the newly created RowData with the specified members and data.

Parameters:

rowMembersTuple - row dimension to members map

columnMembers - column members

columnMemberNamesToValues - column member names to values map

Returns:

the newly created RowData with the specified members and data

createZipFileWriter

public java.io.Writer createZipFileWriter(java.lang.String zipFileName,
                                          java.lang.String innerFileName)
                                   throws java.io.UnsupportedEncodingException,
                                          java.io.FileNotFoundException,
                                          java.io.IOException

Creates and returns a new zip file writer.

The zip file will be available in the Outbox when the writer is closed.

Parameters:

zipFileName - name of the zip file to create

innerFileName - name of the file the content will be written to and zippped

Returns:

Creates and returns a new zip file writer

Throws:

java.io.UnsupportedEncodingException - if the UTF-8 charset is not supported

java.io.FileNotFoundException - if an exception occurs when opening or creating a new file with the specified name, possibly due to invalid file name or illegal characters

java.io.IOException - if an I/O error occurs

cscParams

public java.lang.String cscParams(java.util.Collection<?> items)

Returns a string value with each of the specified items flattened, quoted and seperated by a comma.

The string returned by this method can be plugged into a Essbase calc script command as parameters.

This method accepts primitive arrays, Object arrays, Iterable objects and Maps which are flattened before quoting them. Maps are converted into map.values() as they are flattened.

This method supports objects that are references to a member (see section Member References)

Example call from Groovy to demonstrate calling this method with a list of HeaderCell, RtpValue and Member type of objects as parameters.

 /*RTPS: {Periods}*/
 Application app = operation.application
 Cube cube = app.getCube("OEP_FS")
 println operation.grid.pov*.mbrName
 List<DataGrid.HeaderCell> povMemberCells = operation.grid.pov.findAll { DataGrid.HeaderCell it -> it.dimName != "Plan Element" } 
 List&ltMember&gt; products = app.getDimension("Product").getEvaluatedMembers("ILvl0Descendants(Product)", cube)
 String calcScript = """
 Fix(${cscParams([povMemberCells, rtps.periods, products])})
     "OFS_Calculated"
     (
         "OFS_Product Revenue" = "OFS_Volume" * "OFS_Avg Selling Price";
     )
 EndFix;"""

 println("The following calc script was executed by $operation.user.fullName: \n $calcScript")
 return calcScript

Parameters:

items - collection of one or more objects

Returns:

a string value for the specified items that can be plugged into a Essbase calc script command as parameters

Throws:

oracle.epm.api.model.IllegalScriptArgumentException - if null items were found in the flattened list.

cscParams

public java.lang.String cscParams(java.lang.Object... items)

Returns a string value with each of the specified items flattened, quoted and seperated by a comma.

The string returned by this method can be plugged into a Essbase calc script command as parameters.

This method accepts primitive arrays, Object arrays, Iterable objects and Maps which are flattened before quoting them. Maps are converted into map.values() as they are flattened.

This method supports objects that are references to a member (see section Member References)

Example call from Groovy to demonstrate calling this method with an array of HeaderCell, RtpValue and Member type of objects as parameters.

 /*RTPS: {Periods}*/
 Application app = operation.application
 Cube cube = app.getCube("OEP_FS")
 println operation.grid.pov*.mbrName
 List<DataGrid.HeaderCell> povMemberCells = operation.grid.pov.findAll { DataGrid.HeaderCell it -> it.dimName != "Plan Element" }
 List<Member> products = app.getDimension("Product").getEvaluatedMembers("ILvl0Descendants(Product)", cube)
 String calcScript = """
 Fix(${cscParams(povMemberCells, rtps.periods, products)})
     "OFS_Calculated"
     (
         "OFS_Product Revenue" = "OFS_Volume" * "OFS_Avg Selling Price";
     )
 EndFix;"""

 println("The following calc script was executed by $operation.user.fullName: \n $calcScript")
 return calcScript

Parameters:

items - one or more objects

Returns:

a string value with each of the specified items flattened, quoted and seperated by a comma

Throws:

oracle.epm.api.model.IllegalScriptArgumentException - if null items were found in the flattened list.

csvIterator

public CloseableIterator<java.lang.String[]> csvIterator(java.lang.String inputFileName)
                                                  throws java.io.IOException

Returns an iterator to iterate over the rows of a CSV file from the outbox.

The values in the file have to be comma separated.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvIterator('test.csv').withCloseable() { reader ->
   reader.each { String[] values ->
       println(Arrays.toString(values))
   }
 }
 

Parameters:

inputFileName - name of the file to read from the outbox and iterate over

Returns:

an iterator to iterate over the rows of a CSV file

Throws:

java.io.IOException - if an I/O error occurs

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvIterator

public CloseableIterator<java.lang.String[]> csvIterator(java.lang.String inputFileName,
                                                         char separator)
                                                  throws java.io.IOException

Returns an iterator to iterate over the rows of a CSV file from the outbox.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvIterator('test.csv', (char)'\t').withCloseable() { reader ->
   reader.each { String[] values ->
       println(Arrays.toString(values))
   }
 }
 

Parameters:

inputFileName - name of the file to read from the outbox and iterate over

separator - separator used in the input file

Returns:

an iterator to iterate over the rows of a CSV file

Throws:

java.io.IOException - if an I/O error occurs

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvIterator

public CloseableIterator<java.lang.String[]> csvIterator(java.lang.String inputFileName,
                                                         java.lang.String separator)
                                                  throws java.io.IOException

Returns an iterator to iterate over the rows of a CSV file from the outbox.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvIterator('test.csv', '\t').withCloseable() { reader ->
   reader.each { String[] values ->
       println(Arrays.toString(values))
   }
 }
 

Parameters:

inputFileName - name of the file to read from the outbox and iterate over

separator - separator used in the input file(first char will be used as the separator)

Returns:

an iterator to iterate over the rows of a CSV file

Throws:

java.io.IOException - if an I/O error occurs

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName)

Returns a CsvWriter to write values to a CSV file on the outbox using a comma for the separator and quoting only values that are required to be quoted.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv').withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

Returns:

a CsvWriter to write values to a CSV file using a comma for the separator and quoting only values that are required to be quoted

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName,
                           boolean quoteAllValues)

Returns a CsvWriter to write values to a CSV file on the outbox using a comma for the separator and quoting based on the option provided.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv', true).withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

quoteAllValues - true if all values are to be quoted, false to quote only values that are required to be quoted

Returns:

a CsvWriter to write values to a CSV file using a comma for the separator and quoting based on the option provided

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName,
                           char separator)

Returns a CsvWriter to write values to a CSV file using using a comma for the separator and quoting only values that are required to be quoted.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv', (char)'\t').withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

separator - separator to be used

Returns:

a CsvWriter to write values to a CSV file using using a comma for the separator and quoting only values that are required to be quoted

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName,
                           char separator,
                           boolean quoteAllValues)

Returns a CsvWriter to write values to a CSV file on the outbox using the separator and quoting based on the options provided.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv', (char)',', true).withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

separator - separator to be used

quoteAllValues - true if all values are to be quoted, false to quote only values that are required to be quoted

Returns:

a CsvWriter to write values to a CSV file using the separator and quoting based on the options provided

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName,
                           java.lang.String separator)

Returns a CsvWriter to write values to a CSV file on the outbox using the separator provided and quoting only values that are required to be quoted.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv', '\t').withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

separator - separator to be used, first char will be used as the separator

Returns:

a CsvWriter to write values to a CSV file using the separator provided and quoting only values that are required to be quoted

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

csvWriter

public CsvWriter csvWriter(java.lang.String outputFileName,
                           java.lang.String separator,
                           boolean quoteAllValues)

Returns a CsvWriter to write values to a CSV file on the outbox using the separator and quoting based on the options provided.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

Example call from Groovy:

 /*RTPS: */
 csvWriter('test.csv', '\t').withCloseable() { out ->
   out.writeNext 'Scenario', 'Data Storage', 'Start Year', 'End Year', 'Start Period', 'End Period'
   out.writeNext 'Current', 'Store', 'FY16', 'FY24', 'Jan', 'Dec'
   out.writeNext 'Variance', 'Never Share', 'FY12', 'FY20', 'Jan', 'Dec'
   out.writeNext 'Variance Comments', 'Store', 'FY12', 'FY24', 'Apr', 'Aug'
   out.writeNext 'Act vs Plan %', 'Dynamic Calc', 'FY10', 'FY18', 'Jan', 'Dec'
 }
 

Parameters:

outputFileName - name of the file on the outbox where values are written; The file will be overwritten if it exists

separator - separator to be used(first char will be used as the separator)

quoteAllValues - true if all values are to be quoted, false to quote only values that are required to be quoted

Returns:

a CsvWriter to write values to a CSV file using the separator and quoting based on the options provided

Throws:

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

currentTimeMillis

public long currentTimeMillis()

Returns the current time in milliseconds.

Note that while the unit of time of the return value is a millisecond, the granularity of the value depends on the underlying operating system and may be larger. For example, many operating systems measure time in units of tens of milliseconds.

Returns:

the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

executeJob

public Job executeJob(JobDefinition jobDef)
               throws java.lang.Exception

Executes the job with the specified job definition and returns the job once it has completed or failed.

This will execute the job synchronously and will return only when the job execution either completes successfully or fails.

This job instance will get created as a child job of the current Groovy rule being executed.

Supported job types are Rules, Ruleset and Template. Parameter values for Member, Members, Member Range and Cross Dimension type of rtps being passed to this job should be valid in the cube the current Groovy rule is being executed against.

Note: At this time, rtp evaluations are indetermined if a rule executing against one cube executes a rule directly or indirectly in a different cube. In most cases this should be avoided as behavior in this area is subject to change.

Parameters:

jobDef - job definition

Returns:

executes the job with the specified job definition and returns the job once it has completed or failed

Throws:

java.lang.Exception - if an unexpected fault occurs

fixValues

public java.lang.String fixValues(EssbaseCompatible... objects)

Returns a string value for the specified objects that can be plugged into a Essbase calc script FIX command.

An EssbaseCompatible object can be a variety of objects such as a Member, Dimension, RtpValue, etc.

Parameters:

objects - one or more EssbaseCompatible objects

Returns:

a string value for the specified objects that can be plugged into a Essbase calc script FIX command

getCurrentRule

public Rule getCurrentRule()

Returns the current rule being executed.

Returns:

the current rule being executed

getEntryId

public long getEntryId(java.lang.String smartListName,
                       java.lang.String smartListEntryName)

Returns the smart list entry id for the specified smart list name and entry name.

The entry name can be the name of the entry such as Active or the label resource key of the entry such as LABEL_ACTIVE.

Parameters:

smartListName - smart list name

smartListEntryName - smart list entry name or non localized label

Returns:

the smart list entry id for the specified smart list name and entry name

Throws:

oracle.epm.api.model.IllegalScriptArgumentException - if smartListName is null or empty

getEpmAutomate

public oracle.epm.api.epmctl.EpmAutomate getEpmAutomate()

Returns an EpmAutomate instance class.

This is a privileged method. A user with administrator privileges can automate many repeatable tasks by executing various EPM Automate commands via the returned EpmAutomate instance.

For examples on how to call EPM Automate commands from Groovy, see Running Commands without Installing EPM Automate.

Returns:

an EpmAutomate instance class

getRtps

public java.util.Map<java.lang.String,RtpValue> getRtps()

Returns an unmodifiable map of RtpValue objects for the run time prompts used in this script.

Returns:

an unmodifiable map of RtpValue objects for the run time prompts used in this script

getRule

public Rule getRule()

Returns the current rule being executed.

Returns:

the current rule being executed

See Also:

getCurrentRule()

getTextCellId

public int getTextCellId(java.lang.String textVal,
                         boolean createIfNotFound)
                  throws java.lang.Exception

Returns the text cell id for the specified text value or 0 if the text value is not found and createIfNotFound is false.

Parameters:

textVal - text value

createIfNotFound - if true a new text id is created if one does not exist for the specified text value

Returns:

the text cell id for the specified text value or 0 if the text value is not found and createIfNotFound is false

Throws:

java.lang.Exception - if an unexpected error occurrs

oracle.epm.api.model.IllegalScriptArgumentException - if textVal is null or empty

json

public java.lang.String json(java.util.Map<java.lang.String,?> input)

Returns a JSON string for the specified input map.

Parameters:

input - input map

Returns:

a JSON string for the specified input map

mdxParams

public java.lang.String mdxParams(java.lang.Object... items)

Returns a string value with each of the specified items flattened, evaluated and converted to MDX delimited identifiers and separated by a comma.

The string returned by this method can be plugged into an ASO custom calc or allocation script command as parameters.

This method accepts Object arrays, Iterable objects and Maps which are flattened before converting them. Maps are converted into map.values() as they are flattened.

This method supports objects that are references to a member (see section Member References) or objects that evaluate to Member objects.

Example call from Groovy to demonstrate calling this method with an RtpValue type of object as parameters.

 /*RTPS: {Month}*/
 AllocationParameters allocationParameters = new AllocationParameters()
 allocationParameters.pov = "Crossjoin(Crossjoin(Crossjoin(Crossjoin(
 Crossjoin(Crossjoin({[No Currency]},{[No Entity]}),{[No Manager]}),
 {${mdxParams(rtps.Month)}}),{[BU Version_1]}),{[FY15]}),{[Bonus]})"
 allocationParameters.amount = '([No Employee], [Actual])'
 allocationParameters.zeroAmountOption = ZeroAmountOption.ABORT
 allocationParameters.targetTimeSpanOption = TargetTimeSpanOption.DIVIDE_AMOUNT
 allocationParameters.range = '{Descendants([Total Employees], [Total Employees].dimension.Levels(0))}'
 allocationParameters.target = '([Current])'
 allocationParameters.basis = '([Salary], [Actual])'
 allocationParameters.basisTimeSpanOption = BasisTimeSpanOption.COMBINE_BASIS
 allocationParameters.zeroBasisOption = ZeroBasisOption.NEXT_AMOUNT;
 allocationParameters.negativeBasisOption = NegativeBasisOption.DEFAULT
 allocationParameters.allocationMethod = AllocationMethod.SHARE
 allocationParameters.roundDigits = 2
 allocationParameters.roundMethod = RoundingMethod.ERRORS_TO_HIGHEST
 Application app = operation.application
 Cube cube = app.getCube("OEP_FS")
 cube.executeAsoAllocation(allocationParameters)

Parameters:

items - one or more objects

Returns:

Returns a string value with each of the specified items flattened, evaluated and converted to MDX delimited identifiers and separated by a comma.

Throws:

oracle.epm.api.model.IllegalScriptArgumentException - if null items were found in the flattened list.

messageBundle

public GroovyMessageBundle messageBundle(java.util.Map<java.lang.String,java.lang.String> resourceMap)

Returns a new in memory resource bundle that contains locale-specific resources provided to it.

Example call from Groovy:

 def mbUs = messageBundle(["validation.invalidemail":"Email address is invalid: {0}"],
 ["validation.invalidphone":"Phone number is invalid: {0}"],
 ["validation.memberexists":"The member you have specified already exists and cannot be created: {0}."],
 ["validation.invalidnamelength":"Employee name must be 5 to 40 characters: {0}"])
 

Parameters:

resourceMap - a map of locale-specific resource key/value pairs

Returns:

a new in memory resource bundle that contains locale-specific resources provided to it

messageBundleLoader

public GroovyResourceBundleLoader messageBundleLoader(java.util.Map<java.lang.String,GroovyMessageBundle> messageBundleMap)

Returns a resource bundle loader that manages message bundles by locale.

Parameters:

messageBundleMap - a map of locale to resource bundle

Returns:

a resource bundle loader that manages message bundles by locale

nanoTime

public long nanoTime()

Returns the current value of the running Java Virtual Machine's high-resolution time source, in nanoseconds.

Returns:

the current value of the running Java Virtual Machine's high-resolution time source, in nanoseconds

See Also:

System.nanoTime()

print

public void print(java.lang.Object value)

Prints the value to the current operation's job details, which can be viewed from the job console.

Overrides:

print in class groovy.lang.Script

Parameters:

value - the value to print

printf

public void printf(java.lang.String format,
                   java.lang.Object value)

Prints a formatted string using the specified format string and argument to the current operation's job details, which can be viewed from the job console.

Overrides:

printf in class groovy.lang.Script

Parameters:

format - the format to follow

value - the value to format

printf

public void printf(java.lang.String format,
                   java.lang.Object[] values)

Prints a formatted string using the specified format string and arguments to the current operation's job details, which can be viewed from the job console.

Overrides:

printf in class groovy.lang.Script

Parameters:

format - the format to follow

values - the value to be formatted

println

public void println()

Prints a newline to the current operation's job details, which can be viewed from the job console.

Overrides:

println in class groovy.lang.Script

println

public void println(java.lang.Object value)

Prints the value and a newline to the current operation's job details, which can be viewed from the job console.

Overrides:

println in class groovy.lang.Script

Parameters:

value - the value to print

stripQuotes

public java.lang.String stripQuotes(java.lang.String text)

Return the specified text with double quotation removed.

Parameters:

text - the string

Returns:

the specified text with double quotation removed

throwVetoException

public void throwVetoException(GroovyResourceBundleLoader rbl,
                               java.lang.String resourceKey,
                               java.lang.Object... parameters)

Throws an exception indicating that the operation in progress must be vetoed. The specified resource bundle loader dynamically loads and return a localized message for the specified resource key indicating the reason for veto.

Parameters:

rbl - a resource bundle loader with resource bundles containing the specified resourceKey

resourceKey - resource key present in the resource bundle

parameters - parameters for the message or null

Throws:

VetoOperationException - that vetoes the current operation and is shown to the end user

oracle.epm.api.model.IllegalScriptArgumentException - if rbl is null or resourceKey is null or empty

throwVetoException

public void throwVetoException(com.hyperion.planning.HspDynamicLocalizedException cause)
                        throws java.lang.Exception

Throws an exception indicating that the operation in progress must be vetoed.

Parameters:

cause - the cause for this exception

Throws:

java.lang.Exception - if an unexpected fault occurs

throwVetoException

public void throwVetoException(com.hyperion.planning.HspLocalizedException cause)
                        throws java.lang.Exception

Throws an exception indicating that the operation in progress must be vetoed.

Parameters:

cause - the cause for this exception

Throws:

java.lang.Exception - if an unexpected fault occurs

throwVetoException

public void throwVetoException(java.lang.String message)
                        throws java.lang.Exception

Throws an exception indicating that the operation in progress must be vetoed.

Parameters:

message - detailed localized message indicating the reason for the veto

Throws:

java.lang.Exception - if an unexpected fault occurs

validateRtp

public void validateRtp(RtpValue rtp,
                        oracle.epm.api.model.Predicate<RtpValue> predicate,
                        GroovyResourceBundleLoader rbl,
                        java.lang.String resourceKey,
                        java.lang.Object... parameters)

Validates the run time prompt value against the specified predicate.

If the value does not match the predicate, a veto exception is thrown indicating that the operation in progress must be vetoed.

Example call from Groovy that validates the length of the employee name:

 /*RTPS: {EmployeeName}*/
 def mbUs = messageBundle(["validation.invalid.name.length":"Employee name must be 5 to 40 characters: {0}"])
 def mbl = messageBundleLoader(["en" : mbUs]);
 validateRtp(rtps.EmployeeName, {(5..40).contains(it.enteredValue.size()) }, mbl, "validation.invalid.name.length", rtps.EmployeeName);
 

Parameters:

rtp - an RtpValue that should be validated

predicate - the predicate to validate the rtp value against

rbl - a resource bundle loader with resource bundles containing the specified resourceKey

resourceKey - resource key present in the resource bundle

parameters - parameters for the message or null

Throws:

VetoOperationException - that vetoes the current operation and is shown to the end user

oracle.epm.api.model.IllegalScriptArgumentException - if rbl is null or resourceKey is null or empty

validateRtp

public void validateRtp(RtpValue rtpValue,
                        java.lang.String pattern,
                        GroovyResourceBundleLoader rbl,
                        java.lang.String resourceKey,
                        java.lang.Object... parameters)

Validates the run time prompt value against the specified regular expression pattern.

If the value does not match the pattern, a veto exception is thrown indicating that the operation in progress must be vetoed.

Example call from Groovy that validates the employee email:

 /*RTPS: {EmployeeEmail}*/
 def mbUs = messageBundle(["validation.invalid.email":"Email address is invalid: {0}"])
 def mbl = messageBundleLoader(["en" : mbUs]);
 validateRtp(rtps.EmployeeEmail, /^.+@.+/, mbl, "validation.invalid.email", rtps.EmployeeEmail.enteredValue);
 

Parameters:

rtpValue - an RtpValue that should be validated

pattern - the regular expression to validate the rtp value against

rbl - a resource bundle loader with resource bundles containing the specified resourceKey

resourceKey - resource key present in the resource bundle

parameters - parameters for the message or null

Throws:

VetoOperationException - that vetoes the current operation and is shown to the end user

oracle.epm.api.model.IllegalScriptArgumentException - if rbl is null or resourceKey is null or empty

workbook

public Workbook workbook()

Returns a newly created empty Excel workbook.

The caller is responsible for closing the workbook when finished with it.

Example call from Groovy:

 
 /*RTPS: */
 workbook().withCloseable { Workbook book ->
     book.createSheet().with { sheet ->
         addRow('','Jan','Feb','Mar')
         addRow('Plan','10','','30')
         addRow('Budget','','200','100')
         addRow('Actual','','110','120')
     }
     book.createSheet('Sheet#2').with { sheet ->
         addRow('','Apr','May','Jun')
         addRow('Variance','1','2','3')
         addRow('Revised','10','20','')
     }
     book.getSheet(0).addRow('Working','15','20','300')
     book.save('Test.xlsx')
 }
 

Returns:

a newly created empty Excel workbook

zipInputStream

public java.util.zip.ZipInputStream zipInputStream(java.lang.String fileName)
                                            throws java.io.IOException

Returns a zip input stream wrapping the specified file in the outbox folder.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

The caller is responsible for closing this stream when finished with it.

Example call from Groovy:

 
 /*RTPS: */
 zipInputStream('file.zip').withCloseable { ZipInputStream zis ->
   ...
 }
 

Parameters:

fileName - name of the zip file from the outbox folder

Returns:

a zip input stream wrapping the specified file in the outbox folder

Throws:

java.io.FileNotFoundException - if the file do not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading

java.io.IOException - if an I/O error occurs

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters

zipOutputStream

public java.util.zip.ZipOutputStream zipOutputStream(java.lang.String fileName)
                                              throws java.io.IOException

Returns a zip output stream wrapping the specified file in the outbox folder.

A valid file name is a simple name that may only contain letters, digits, underscores (_), hyphens (-), periods (.), and spaces. No relative paths or subfolders are allowed.

If the file does not exist, it will be created. If the file already exists, it will be overwritten.

The caller is responsible for closing this stream when finished with it.

Example call from Groovy:

 
 /*RTPS: */
 zipOutputStream('file.zip').withCloseable { ZipOutputStream zipos ->
   ...
 }
 

Parameters:

fileName - name of the zip file to be created in the outbox folder

Returns:

a zip output stream wrapping the specified file in the outbox folder

Throws:

java.io.IOException - if an I/O error occurs

com.hyperion.planning.HspRuntimeException - if the file name contains invalid characters