Command Line Parameters for the Outline Load Utility

The following command line parameters are available for the Outline Load utility. After running the utility, you can verify the results by reviewing the exception file and log file. If no errors are reported in the log file, you can then access the imported metadata and data in the application. It is not necessary to restart the application server.

HspOutlineLoad [-f:passwordFile] /A:application /U:userName [/CP:commandPropertieFileName] [/M] [ [/I:inputFileName|/IR[:RDBConnectionPropertiesFileName]|/IRA|/E:outputFileName|/ED:outputFileNameStem] [/EDD:dataExportSpecification] [/ICB:blockSpecification] [/SDM:driverMemberSpecification] /D[U]:loadDimensionName|/DA:attributeDimensionName:baseDimensionName|TR] [/N] [[/R] [/DPU]] [/C] [/F] [/K] [/8] [/DF:datePattern] [/RIQ:inputQueryOrKey] [/RIC:catalog /RID:driver /RIR:url /RIU:userName [/RIP:password]] [/X:exceptionFileName] [L:logFileName] [/?]

Parameter

Description

[-f:passwordFile]

Optional: If an encrypted password file is set up, use as the first parameter in the command line to read the password from the full file path and name specified in passwordFile.

/S:server

This parameter is obsolete and values specified with it are ignored. If used, the system checks that the server name specified is not null and that it is greater than 0 characters in length. This parameter is still available to provide backward compatibility. The (default) server for the Outline Load Utility is always localhost.

/A:application

Name of the Planning application to which you are importing.

/U:userName

User name with which to log on to the application.

/CP:commandPropertieFileName

Specifies a file that contains command line arguments that, in conjunction with command line arguments, constitutes the options for execution. For arguments that appear in both the command properties file and the command line, the command line arguments take precedence.

See Command Properties File.

/M

Generate fully qualified header records for loadable dimensions in the application. Use /-M if you do not want to display this information (default).

/I:inputFileName

Specifies the data load input file which contains a header record and data records in CSV format. You must also specify a data load dimension (/D option or /TR option). The /ICB switch can be specified to clear Essbase data.

/IR[:RDBConnectionPropertiesFileName]

Specifies that the input records will come from a relational database source. Specifying the optional properties file designates that some or all of the required relational connection switch properties (/RIQ, /RIC, /RID, /RIR, /RIU, /RIP) can be found within the properties file. A data load dimension (/D option) must be specified as well. The /ICB switch can be specified to clear Essbase data.

/IRA

Identical to the /IR switch except that the required RDB JDBC connection properties (/RIQ, /RIC, /RID, /RIR, /RIU, /RIP switch values) are obtained from the currently connected application's RDB data source. A data load dimension (/D option) must be specified as well. The /ICB switch can be specified to clear Essbase data.

/ICB:blockSpecification

Clears an Essbase block before performing an import operation (/I, /IR, /IRA). (A string of the form \"<loadDimensionMembers,...>, \"<driverMembers,...>, \"<point-of-view members,...>, <dataLoadCubeName>\"").

/ALS

Create alias tables on import if they do not exist (default). Use /-ALS to error out if the referenced alias tables do not exist.

/E:outputFileName

Exports the dimension specified with the /D switch to the specified output file. (When exporting planning unit hierarchies, the file is in the format defined for importing planning unit hierarchies.)

/ED:outputFileNameStem

Exports data to Planning Driver Member formatted data files. The /EDD switch must also be set. Files are generated in the form: <fileNameStem>.1-n.csv through <fileNameStem>.n-n.csv where n is the number of files generated.

/EDH

Exports a dimension header in Planning internal HEADERBLOCK format in the output file. This is used on import to dynamically create base and attribute dimensions prior to import.

/ER[:RDBConnectionPropertiesFileName]

Specifies that export records will be written to a relational database table. Setting the /EDD switch specifies that data will be exported as well. Specifying the optional properties file designates that some or all of the required relational connection switch properties (/REQ, /REC, /RED, /RER, /REU, and /REP) can be found within the properties file. A data load dimension must also be specified using the /D switch.

/ERA

Identical to the /ER switch except that the required RDB JDBC connection properties (/REQ, /REC, /RED, /RER, /REU, /REP switch values) are obtained from the currently connected application's RDB data source. Setting the /EDD switch specifies that data will be exported. A data load dimension must also be specified using the /D switch.

/EDD:dataExportSpecification

Specifies the format of the exported Planning Driver Member formatted data files. A string of the form <loadDimensionMembers,...>, <driverMembers,...>, <point-of-view members,...>, <dataLoadCubeName>.

/SDM:driverMemberSpecification

Sets driver members on the base load dimension for the application (/A) on import operations only (/I, /IR, /IRA). (A string of the form \"<baseLoadDimension>, \"<driverMembers,...>\", <PlanTypeName>")

/D:loadDimensionName

Dimension to be loaded, whose member fields correspond to the header record in the load file. You must also specify a load file (/I) or the planning unit hierarchy to be exported with the /E switch.

See the following rows to load user-defined dimensions and attributes using /DU, /DA[T], /DAN, /DAB, and /DAD.

/DU:userDefinedLoadDimensionName

User-defined dimension to be loaded; a dimension with this name will be created if it does not exist.

/DA[T]:attributeLoadDimensionName:baseDimensionName

Text attribute dimension to be loaded; an attribute dimension with this name, bound to the base dimension, will be created if it does not exist.

/DAN:attributeLoadDimensionName:baseDimensionName

Numeric attribute dimension to be loaded; an attribute dimension with this name, bound to the base dimension, will be created if it does not exist.

/DAB:attributeLoadDimensionName:baseDimensionName

Boolean attribute dimension to be loaded; an attribute dimension with this name, bound to the base dimension, will be created if it does not exist.

/DAD:attributeLoadDimensionName:baseDimensionName

Date attribute dimension to be loaded; an attribute dimension with this name, bound to the base dimension, will be created if it does not exist.

/DX:HSP_Rates

Load the HSP_Rates dimension and create exchange rate tables if they do not exist.

/DS:HSP_SMARTLISTS

Load the Smart Lists dimension and Smart List dimension entries.

/DL:comma|tab

Set the field delimiter to the comma character \",\" comma (default), or the tab character.

/TR

Load data when driver members are specified in the load file in the Driver Members column. All members except the driver member must be specified in the Point-of-View column. With /TR, you can load one value per row in the load file.

/T

Inherit unspecified plan type settings from the parent when adding new members (default). Use /-T to force explicit setting of plan type settings for the member.

/N

Perform a “dry run” by parsing the load file without loading data or metadata. Use /-N (or do not specify the /N parameter) to parse the load file while loading data and metadata (default).

Note:

Performing a dry run parses the load file (for example, checks the header record, checks if the number of values matches the header record number) but does not check the validity of the values defined in the file.

/O

Maintain the order of members in the load file when loading, with the exception of UDAs (default). Use /-O to ignore the order of members in the load file when loading.

/H

Order input records in parent-child order, with the exception of UDAs (default). Use /-H to load input records as they appear in the load file; this option is faster and uses less memory.

/R

Delete all members of the load dimension before performing the load. Use /-R (or do not specify the /R parameter) to keep all members of the load dimension (default). See also /U.

Note:

Use caution with /R; this option removes attribute bindings and approvals states.

/DPU

Delete all planning units with the /R parameter, otherwise error-out if members in planning units attempt to be deleted. Use /-DPU to prevent the delete operation from deleting members in planning units.

/IDU

Delete unspecified members not explicitly specified in the load. Members not explicitly specified in the input source will be deleted from the Planning outline on load completion unless: 1) they are an ancestor of a member that was specified, or 2) they are a base member of a shared member that was specified. (/-IDU is the default.)

/C

Perform a cube refresh after the metadata load. Use /-C if you do not want to perform a cube refresh (default). See also /F.

/F

Create security filters when refreshing with the /C option. Use /-F if you do not want to refresh security filters (default). (This option does not provision users to the application; it only creates security filters for users that currently exist. Users can be provisioned to applications using other methods.) For this option to take effect, /C must also be specified.

/K

Lock the load dimension before loading (default), recommended. Use /-K if you do not want to lock the dimension (not recommended unless you are using /N).

/8

Specifies UTF-8 encoding on input, output, log and exception files and prepends a UTF-8 BOM marker to the output file (default). Use /-8 to not set UTF-8 encoding.

/DF:datePattern

Override the default date pattern on date data conversions to the specified pattern. The pattern must be one of the following:

  • MM-DD-YYYY

  • DD-MM-YYYY

  • YYYY-MM-DD

Use /-DF to use the default date pattern setting (default).

/RIQ:inputQueryOrKey

An SQL query or a key in the command arguments properties file (/CP switch) in which the value is a SQL query that is executed to produce input for an import operation. The /IR switch must be set for this to be used, and if it is used, the /RIC, /RID, /RIR, /RIU, and /RIP switches must also be set.

/RIC:catalog

An RDB JDBC catalog name for the input RDB connection. The /IR switch must be set for this to be used, and if it is used, the /RIQ, /RID, /RIR, /RIU, and /RIP switches must also be set. If the /IRA switch is used, this switch does not need to be specified.

/RID:driver

An RDB JDBC driver name for the input RDB connection. The /IR switch must be set for this to be used, and if it is used, the /RIQ, /RIC, /RIR, /RIU, and /RIP switches must also be set. If the /IRA switch is used, this switch does not need to be specified.

/RIR:url

An RDB JDBC URL for the input RDB connection. The /IR switch must be set for this to be used, and if it is used, the /RIQ, /RIC, /RID, /RIU, and /RIP switches must also be set. If the /IRA switch is used, this switch does not need to be specified.

/RIU:userName

An RDB JDBC username for the input RDB connection. The /IR switch must be set for this to be used, and if it is used, the /RIQ, /RIC, /RID, /RIR, and /RIP switches must also be set. If the /IRA switch is used, this switch does not need to be specified.

/RIP:password

An RDB JDBC password for the input RDB connection. The /IR switch must be set for this to be used, and if it is used, the /RIQ, /RIC, /RID, /RIR, and /RIU switches must also be set. If the /IRA switch is used, the /RIP switch need not be specified.

Enter the password in its unencrypted form when specifying it for the first time in the .properties file. When the Outline Load utility is run, the properties file will be rewritten with an encrypted value for the /RIP password. If this value is not specified in the properties file, a command line prompt will be issued to obtain the password.

/REQ:exportQueryOrKey

A SQL query or a key in the command arguments properties file (/CP switch) in which the value is a SQL query that specifies the exported values of the form. 'INSERT INTO<tableName> (column1, column2, ...) VALUES (property1, property2, ...)' where properties are Planning member properties as found in the flat file column header records. The /ER or /ERA switch must be set for this to be used, and if it is used, the /REC, /RED, /RER, /REU, and /REP switches must also be set.

/REC:catalog

An RDB JDBC catalog name for the export RDB connection. The /ER switch must be set for this to be used, and if it is used, the /REQ, /RED, /RER, /REU, and /REP switches must also be set.

/RED:driver

An RDB JDBC driver name for the export RDB connection. The /ER switch must be set for this to be used, and if it is used, the /REQ, /REC, /RER, /REU, and /REP switches must also be set.

/RER:url

An RDB JDBC URL for the export RDB connection. The /ER switch must be set for this to be used, and if it is used, the /REQ, /REC, /RED, /REU, and /REP switches must also be set.

/REU:userName

An RDB JDBC username for the export RDB connection. The /ER switch must be set for this to be used, and if it is used, the /REQ, /REC, /RED, /RER, and /REP switches must also be set.

REP:password

An RDB JDBC password for the export RDB connection. The /ER switch must be set for this to be used, and if it is used, the /REQ, /REC, /RED, /RER, and /REU switches must also be set.

If this value is not specified in the command properties file, a command line prompt will be issued to obtain the password.

/C2A:(column1, alias1), (column2, alias2), ...

Column to alias” mapping, or runtime column renaming and exclusion. This parameter enables you to rename a column header at runtime, have the column ignored, or have specific plan type properties ignored or renamed.

Note:

An alias specified on the column overrides assignments made by this command.

/UCH

Ignore unrecognized column headers and proceed with load. /-UCH is the default current functionality: abort the load if unrecognized column headers are encountered. An information message listing the ignored columns is output.

/X:exceptionFileName

Specify the file that will contain exceptions that occur during the load. (If no file name is specified, the information is written to a file called stderr.)

/L:logFileName

Specify the file that will contain status and informational messages. (If no file name is specified, the information is written to a file called stdout.)

/?

Display usage text.

Example: Load numeric attribute dimension and values, and associate them with the Entity dimension. (An attribute dimension will be created if it does not exist, but no assignment is made of attribute values to base numbers.)

OutlineLoad /A:Test  /U:admin  /M /I:c:/outline1_attribvals_text.csv /DAN:NumericAttrib:Entity /L:c:/outlineLoad.log /X:c:/outlineLoad.exc
NumericAttrib,Parent
One,NumericAttrib
1,One 
2,NumericAttrib

Example: Load Exchange Rates, add EUR as a member of the Currency dimension, and change the year in the load file to match an existing year in the Planning application. The Exchange Rate table is created in the Planning application if it does not exist.

OutlineLoad /A:Test /U:admin /M /I:c:/outline1_rates.csv /DX:HSP_Rates /L:c:/OutlineLogs/outlineLoad.log /X:c:/OutlineLogs/outlineLoad.exc
Table, To Currency, From Currency, Method, Historical, Beg Balance, Year, Period, Average, Ending

FX1 , USD, EUR, multiply, 1, 2, FY08, Jan, 3, 4
FX1 , USD, EUR, , , , FY09, Feb, 5, 6

Example: Set Weekly Distribution to Use 445

Account, Parent, Use 445
a11,a1,1

Example: Load a file that contains all of the properties available for a UDA. The UDA is loaded and associated with a dimension, but it is not assigned to any member in the dimension.

OutlineLoad /A:Test  /U:admin  /M /I:c:/outline1_uda.csv /D:UDA /L:c:/OutlineLogs/outlineLoad.log /X:c:/OutlineLogs/outlineLoad.exc
Dimension,UDA 
Account,New2

Example: Load a file for Currency that does not specify the currency symbol. In this case, the symbol for this currency in the Planning application is set to the ISO symbol, EUR. The scale defaults to 1.

Currency,Parent,Symbol,Scale
EUR,,,

Example: Load a file for Currency that sets the symbol to the name of the new currency. The symbol is automatically set to NewCurr1 in the Planning application for currency NewCurr1. Currency names are limited to 8 characters.

Currency,Parent,Symbol,Scale
NewCurr1,,,

Example: Use the -f parameter with an encrypted password

If you have generated an encrypted password file, you can use -f as the first parameter in the command line to run the Outline Load utility without entering a password. For example, if you used the PasswordEncryption utility to create a password file called encrypt.txt, you could use this command line:

OutlineLoad -f:c:\encrypt.txt /A:acpt /U:admin /M /I:c:/outline1_accounts.csv /D:Account /L:c:/OutlineLogs/outlineLoad.log /X:c:/OutlineLogs/outlineLoad.exc

Example: /O parameter and load file order

In the following load file, if Entity members e1 and e2 already exist in the Entity dimension, e3 could be added as the last sibling, even though it is first in the load file. If /O is used, e3 is loaded as the first sibling. Because /O is the default, you must specify /-O to have e3 loaded as the last sibling.

Entity,Parent,Data Storage,TextAttrib
e3,Entity,Store,
e2,Entity,Store,
e1,Entity,Store,

Example: /H parameter and parent/child order

Assume that member e1 already exists, and A and B are new members being loaded. Without /H, an error would display because member B does not exist. With /H, members are sorted internally, so B is loaded first as child of e1, and then A is loaded successfully as child of B.

Entity,Parent,Data Storage
A,B,Store 
B,e1,Store

Example: /R parameter

If some members already exist in the dimension, only the members in the input load file should exist in the dimension after the load. If an error occurs during the load after the delete operation, all members of the dimension may be deleted, and the dimension may be empty. Attribute dimensions are not deleted. If a planning unit is started, no Entity members are deleted because the Entity member in the planning unit cannot be deleted.

Entity,Parent,Data Storage,TextAttrib
e1,Entity,Store,
e11,e1,Store,orange
e2,Entity,Store,
e21,e2,Store,
e11,e2,shared,yellow

Example: /T parameter

Load the Account dimension with /T to inherit plan types not explicitly specified in the load file from the parent when adding new members. Assume that member a1 already exists in the application and is valid for all three plan types. After the load completes, member a11 is valid for all three plan types, even though only Plan1 and Plan3 are specified in the load file.

Account, Parent, Source Plan Type, Plan Type (Plan1), Plan Type (Plan2), Plan Type (Plan3)
a11,a1,Plan1,1,,1

Example: /-T parameter

Load the Account dimension with /-T to force explicit setting of plan types for new members. Assume that member a1 already exists in the application and is valid for all three plan types. After the load, member a11 will be valid only for the Plan1 and Plan3 plan types specified in the load file, and not for Plan2.

Example: /TR parameter

OutlineLoad /A:acpt1 /U:admin /M /I:c:\outline1data.csv /TR /L:c:/OutlineLogs/outlineLoad.log /X:c:/OutlineLogs/outlineLoad.exc
Value,Driver Member,Point-of-View,Data Load Cube Name
14,a1,"Jan,Local,e1,Current,Version1,FY08",Plan1
sl1_value2,a2,"Jan,Local,e1,Current,Version1,FY08",Plan1

Example: Load Smart List dimensions and Smart List dimension entries using the /DS:HSP_SMARTLISTS parameter.

OutlineLoad /A:acpt /U:admin /M /I:c:/smartlist_create1.csv /DS:HSP_SMARTLISTS /L:c:/OutlineLogs/outlineLoad.log /X:c:/OutlineLogs/outlineLoad.exc
SmartList Name, Operation, Label, Display Order, Missing Label, Use Form Missing Label, Entry ID, Entry Name, Entry Label
SL1,addsmartlist,SL1Label,,,,,,
SL1,addEntry,,,,,,entry1,entrylabel1
SL1,addEntry,,,,,,entry2,entrylabel2

Example: Perform incremental data loads using the LINEITEM flag.

You can include a LINEITEM flag in the data load file to perform incremental data loads for a child of the data load dimension based on unique driver dimension identifiers. This specifies that data should be overwritten if a row with the specified unique identifiers already exists on the form. If the row does not exist, data is entered as long as enough child members exist under the Data Load Dimension Parent member.

For example, when loading employee data, you can load budget line item detail for predefined Salary Grades. This example shows a command that could be used with a data load file that includes the LINEITEM flag.

OutlineLoad /A:pln1dv /U:admin  /M /I:c:\dataload_file.csv /D:”Budget Item”

This sample data load file loads data for the Budget Item dimension for children of Grade Changes.

"Budget Item","Data Load Cube Name","Point-of-View","Grade Step","Option Value","Start Date","End Date"
"<LINEITEM("Grade Changes">","HCP","POVMembers","Step1","31721","7/1/09",""
"<LINEITEM("Grade Changes">","HCP","POVMembers","Step2","32673","7/1/09",""
"<LINEITEM("Grade Changes">","HCP","POVMembers","Step3","33654","7/1/09",""
"<LINEITEM("Grade Changes">","HCP","POVMembers","Step4","33654","7/1/09",""

In this case, <LINEITEM("Grade Changes")> finds the first available member from Budget Item that is a child of the Grade Changes member, based on these unique identifiers selected in the Data Load Settings page: Grade Step, Option Value, Start Date, and End Date.

During data load, if any child members of Grade Changes already have data for Step1 and 7/1/09, the corresponding member is used to update the remaining data values. If not, the next available empty data row is assigned to Step1 and 7/1/09.

When the first data row is processed, the member Grade1 is assigned. Similarly, the next two members, Grade2 and Grade3 are assigned to the second and third data rows. When the fourth data row is processed, Step1 and 7/1/09 are already assigned to the member Grade1, so that row is used to update the value of the remaining fields.

Example: Import a planning unit hierarchy using the /D parameter.

OutlineLoad /A:acpt /U:admin /I:c:\puh1.csv /D:PUH1

When using /D to import a planning unit hierarchy, you must specify the name of a planning unit hierarchy (not a dimension). The planning unit hierarchy must already exist in a Planning application before new members can be loaded into it.

Example: Export a planning unit hierarchy using the /E parameter.

OutlineLoad /A:acpt_580 /U:admin /M /E:puh_test2.csv /D:test2
Primary Member, Primary Enabled, Secondary Dimension, Secondary Parent, Relative Generation, Auto Include, Secondary Member, Include, Owner, Reviewers, Notifiees
e1, true, <none>, <none>, <none>, false, , true, <none>, admin, planner
e11, true, <none>, <none>, <none>, false, , true, <none>, <none>, <none>
e2, true, <none>, <none>, <none>, false, , true, <none>, <none>, <none>
e21, true, Account, a1, 1, false, , true, <none>, <none>, <none>
e21, true, Account, a1, 1, false, a11, true, <none>, <none>, <none>
e21, true, Account, a1, 1, false, a12, true, admin, <none>, "admin,admin"
e21, true, Account, a1, 1, false, a13, true, planner, "planner2,admin", admin
e21, true, Account, a1, 1, false, a14, true, <none>, <none>, <none>
e21, true, Account, a1, 1, false, a15, true, <none>, <none>, <none>
e21, true, Account, a1, 1, false, a16, true, <none>, <none>, <none>
e21, true, Account, a1, 1-2, false, a111, true, <none>, <none>, <none>

Note:

Secondary members for the first four records are not specified.