Creating Data Import Apps

You can use Longview Designer to create data import apps. Data import apps can be used to import data into your system.

Note: If you intend to run your data import app in batch mode, include only commands supported in batch mode; do not include any Show commands.

Working with variables

You can use Longview Designer to create, modify, reorder, or delete variables for your app. Variables are optional. You might include variables in your app if you want to, for example, use an attribute such as the current time period, or if you want to prompt a user to select a symbol or a file.

Once you have created variables, you can use them elsewhere in your app by enclosing them in dollar signs ($  $).

For more information, see “Variables” in the Longview Developer’s Guide.

You can also use external variables not defined on the Variables page of your app by enclosing them in dollar signs ($  $).

Variables tasks include:

• Creating variables
• Modifying variables
• Reordering variables
• Deleting variables

Creating variables

You can use Longview Designer to create variables for your app. Each variable you specify is created and set to the specified value when your app runs.

To create a variable:

1. Open the Variables section.
2. Do one of the following:
   • To create a new variable at the bottom of the list, click Variable. The new variable appears at the bottom of the variables list.
   • To create a new variable below a specific variable, select a row and click Variable. The new variable appears below the selected row.
3. Complete the following fields:

   Field	Notes
   Name	Type the name of the variable. Do not prefix the variable name with “LV_” or “LVS_”.
   Type	Specify the type of data to be stored in the variable using one of the following options: String — Designates a string value. Range — Designates a list of symbols. Number — Designates a numeric value. List — Designates a list of string values. NumberList — Designates a list of numeric values. The default is String.
   Expression	Specify the value that the variable is set to. Based on the Type field this can be a number, a string, or a list of symbols, respectively.

Note: You can include attribute values in an expression. To include an attribute value in an expression, you must first set a variable to the value of the attribute using an attribute token, and then use the variable. For example, you could create a string variable named “currentPeriod” and use the expression “[[SYSTEM,SGPCurrentPeriod,DBDefault]]”. For more information on setting variables, see “Set Variable” in the Longview Developer’s Guide. For more information on using attributes, see “Attribute tokens” in the Longview Developer’s Guide.

Modifying variables

You can use Longview Designer to modify existing variables for your app.

To modify a variable:

1. Open the Variables section.
2. Select the variable you want to modify and make the necessary changes.

Reordering variables

You can use Longview Designer to change the order of variables in your app. The order of variables is important because you cannot use a variable in an expression until you first define the variable. Variables are created in the same order in which they are defined.

To reorder a variable:

1. Open the Variables section.
2. Select the variable you want to reorder, and then click either Move Up or Move Down. The variable moves one row in the indicated direction.
3. If you want to continue to move the selected variable, repeat step 2 until the variable is in the desired location.

Deleting variables

You can use Longview Designer to delete variables from your app.

To delete a variable:

1. Open the Variables section.
2. In the variables list, select the variable you want to delete, and click Delete. The variable is deleted.

Specifying import file details

You can use Longview Designer to specify import file details. The import file contains the source data you want to import.

To specify import file details:

1. In the Data Import Apps category, expand Existing Apps. A list of existing data import apps displays. 
2. Open the data import app for which you want to specify import file details. The data import app opens in the workspace with the Properties page in view.
3. Click the Import File tab.
4. Complete the following fields:

   Field	Notes
   File	Specify the path and name of the import file.
   Number of Header Records to Filter	Specify the number of header rows to filter on import. If you leave the value as the default value of 0, the system assumes your import file starts with data records with no header rows.
   Number of Footer Records to Filter	Specify the number of footer rows to filter on import. If you leave the value as the default value of 0, the system assumes your import file ends with data records with no footer rows.
   Field Delimiter	Specify whether the character used to separate fields in the import file is the brace ( { ), comma ( , ), semicolon ( ; ), or pipe ( | ). Alternatively, you can type a field delimiter of your choice. The default is the brace ( { ).
   Number of Fields	Specify the number of fields per line in the import file using an integer from 1 through 999.
   Number of Value Fields	Specify whether the import file contains a single value field per line or multiple value fields per line and the corresponding details using one of the following values: Single Value at Field Position — Indicates there is a single value field in each line of the import file. For example, each line of your import file may contain a data value in the third field position. If you select this option, you must specify the field position at which the data value is found using a number from 1 up to and including the number you specified for Number of Fields. For example, type 3.  Multiple Value Fields for Dimension — Indicates there are multiple value fields in each line of the import file, with each value corresponding to a different symbol in the specified dimension. For example, in the TIMEPERIODS dimension you may have eight data values in each line of the import file corresponding to eight symbols in the TIMEPERIODS dimension. If you select this option, you must specify the dimension for which there are multiple value fields. For example, select TIMEPERIODS from the list.

5. In the Dimension Definition section, complete the following fields for each dimension:

   Field	Notes
   Schedule	This field displays only if your system is configured to use schedules and you have access to schedules. The default of None indicates the data import app is on base data only. Specify the schedule to use for the data import app, and the schedule dimensions appear at the bottom of the list of Dimensions.
   Type	Specify the type of relationship between dimension symbols and field values in the import file using one of the following values: Consecutive — The values encountered in the import file are placed consecutively in the dimension starting at the indicated symbol, moving in priority order through the indicated symbol’s siblings. Note: Consecutive is designed to work with a symbol existing in only one hierarchy. If the symbol belongs to more than one hierarchy, the behavior used to determine the siblings is undefined and may be affected by hierarchy reorganizations and imports/exports. You can specify only one dimension as Consecutive. Map — The values encountered in the import file are mapped to dimension symbols as specified in the indicated map. Match — The values encountered in the import file are matched to the dimension symbols exactly. Unique — All values encountered in the import file are placed in the specified dimension symbol. If you select this option, you can use the variables you defined on the Variables page for the specified symbol. Note: If you selected Multiple Value Fields for Dimension in step 4, the dimension you indicated has Values for the Type field and cannot be changed.
   Field Position	This field is available only when Type is Map or Match. Specify the field position to assign the dimension to using a positive integer. For example, for the Accounts dimension, type 3 if the account will be the third column of the data target.
   Symbol	This field is available only when Type is Unique. Type the symbol name for the specified dimension to which the data is imported. Alternatively, you can use the symbol selector. Note: You can also use a variable to define the symbol.
   Map Location	This field is available only when Type is Map. Indicate the location of the map using one of the following values: Internal — Indicates the map exists inside the database, created using the Mappings editor. For more information, see "Maintaining mappings". External — Indicates the map exists as a file, such as a text file on your local machine or network location. Document — Indicates the map exists as a document within the Symbol Maps folder of the app.
   Map	This field is available only when Type is Map. Do one of the following: If you selected Internal as the Map Location, select a map from the list of available maps in the system. If you selected External as the Map Location, type the path of the external map or click the ellipsis button ( ... ) to select the external map. Note: You can use a variable for the Map field value.

6. Do one of the following:
   • If you selected Single Value at Field Position in step 4, proceed to step 9.
   • If you selected Multiple Value Fields for Dimension in step 4, click Value Field in the Value Fields section to add a new Value Field. A new row appears in the table.
7. Complete the following fields:

   Field	Notes
   Field Position	Specify the field position of the value field using a positive integer, where the field position is the corresponding column in the data source containing the data. For example, if the value is exported to the third column in the target file, type 3.
   Symbol	Type the name of a symbol from the dimension indicated in Multiple Value Fields for Dimension for the value in the corresponding field position. Alternatively, you can use the symbol selector. Note: You can use a variable for the Symbol field.

   Note: You can delete a value field by selecting a value field row and clicking Delete.

8. Repeat step 6 and step 7 for each value field in the import file.
9. Optionally, to apply a filter to the records in the import file where records meeting the filter criteria are the only records imported, click Filter in the Filters section to add a new Filter. A new row appears in the table.

   Note: You can delete a filter by selecting a filter row and clicking Delete.

10. Type an expression for the filter using the following guidelines:
    • The expression can be joined together by two or more expressions using AND or OR and grouped by brackets, as appropriate.
    • Each expression uses field names, operators, and values as follows: FieldName EQ|NE|LE|LT|GE|GT Value. If Value is a string, enclose the string in double quotation marks.
    • You can optionally include wildcard characters (? and *) and symbols for Value.
    • You can optionally use symbols for operators, such as ==, !=, <=, <, >=, and >.
    • You must use Field# for FieldName to refer to a specific field on which you want to filter. For example, if Products is the fourth column in your import file and you want to filter Products to import only the Products_Default symbol, use Field4 == "Products_Default" as the expression.

Note: For more information on creating expressions, see “Using conditional operators” and “Search” in the Longview Developer’s Guide.

Specifying data areas

You can use Longview Designer to define the data area specification and related information for your data import app. The data area specification defines the data area to lock and to which the data is imported. If the data area includes a schedule, all symbols in the schedule dimensions are included in the data area specification.

To specify a data area:

1. In the Data Import Apps category, expand Existing Apps. A list of existing data import apps displays.
2. Open the data import app for which you want to specify a data area. The data import app opens in the workspace with the Properties page in view.
3. Click the Data Area tab.
4. Complete the following fields:

   Field	Notes
   Lock description	Type a description for the data area lock. The lock description can have a maximum of 100 characters, including spaces. The default is Data Import - name of data import app. Note: You can use the variables you defined on the Variables page for the Lock Description field.
   Submission description	Type a description for the submission. The submission description can have a maximum of 100 characters, including spaces. The default is Data Import - name of data import app. Note: You can use the variables you defined on the Variables page for the Submission Description field.
   Schedule	This field displays only if your system is configured to use schedules and you have access to schedules. This field displays the schedule selected for the data import app in Specifying import file details.

5. In the table, complete the following fields for each dimension for the data area specification of the data import:

   Note: The Spec and Level fields are not applicable if a symbol contains a variable.

   Field	Notes
   Symbols	Type a symbol name. Alternatively, you can use the symbol selector. To add more than one symbol for a dimension, select a row containing the dimension for which you want to add another symbol and click Symbol. To move a symbol up or down within a dimension, click Move Up or Move Down. Note: To use the symbol selected by the user or defined by an attribute, enter the name of the dimension as a variable, for example $ENTITIES$
   Spec	Indicate the symbol specification using one of the following values: All: Includes all symbols within the selected symbol’s hierarchy. Leaf: Includes only leaf symbols within the selected symbol’s hierarchy. Parent: Includes only parent symbols within the selected symbol’s hierarchy. Root and Parent: Includes only root and parent symbols within the selected symbol’s hierarchy. Note: To use the symbol selected by the user or defined by an attribute, enter the name of the dimension as a variable, for example $ENTITIES$
   Level	Specify the number of levels down from the symbol to be included in the data area.

Specifying custom code

You can use Longview Designer to specify custom code for your data import app. Longview provides you with the following insertion points in the import process where you can specify custom code:

You can set the LV_Success variable to 0 at any point within your custom code to indicate an error and stop the import process. You may choose to, for example, specify custom code in order to validate the data before the upload occurs.

To specify custom code:

1. In the Data Import Apps category, expand Existing Apps. A list of existing data import apps displays.
2. Open the data import app for which you want to specify custom logic. The data import app opens in the workspace with the Properties page in view.
3. Click the Custom Code tab.
4. In the relevant custom code area, specify your code as needed.

Specifying options

You can use Longview Designer to specify options for your data import app.

To specify options:

1. In the Data Import Apps category, expand Existing Apps. A list of existing data import apps displays.
2. Open the data import app for which you want to specify options. The data import app opens in the workspace with the Properties page in view.
3. Click the Options tab.
4. Complete the following fields:

   Field	Notes
   Data Import Method	Specify the way the data is imported using one of the following values: Full — The data area is not downloaded before the system imports the data. The system imports zeros to any cells in the data area not included in the import file.  Incremental — The data area is downloaded before the system imports the data. The system does not import values to any cells in the data area not included in the import file. The default is Full.
   Decimal Character	Specify the decimal character for the data import app using one of the following values: “ . ” — The period is the decimal character. “ , ” — The comma is the decimal character. The default is the period “ . ”.
   Apply Sign Reversal Logic	Select this option to reverse the sign for numeric values for accounts with Credit as the Balance Type. For more information on the balance type in the ACCOUNTS dimension, see “Working with dimensions” in the Longview Application Administrator Guide. The default is cleared.
   Allow Duplicate Mappings	This option applies only when Type is Map. Select this option to indicate that duplicate mappings are permitted. If multiple mappings are found, the system does the following for each type of mapping: Exact — All duplicate Exact mappings are used so that the same value is imported to multiple data cells. If there are duplicate Exact and Wildcard or Range mappings, the Exact mapping is used and the Wildcard or Range mapping is ignored. Wildcard — If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed.  Range — If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed.  If you do not select this option, duplicate mappings are not permitted. If multiple mappings are found, the system reports an error for each mapping. The default is cleared. For more information on duplicate mappings, see Understanding duplicate mappings.
   Duplicate Records	Specify the way duplicate records are handled for the data import app using one of the following values: Disallow — Specifies that duplicate records should not be allowed. The first entry is submitted. If a duplicate record is encountered, the system reports an error. Add — Specifies that duplicate records should be allowed and the value of all such records summed. If a duplicate record is encountered that contains text (versus numeric) data, it is treated as an invalid/error record. Use First — Specifies that the first entry of duplicate records should be used. If a duplicate record is encountered, the system does not report an error. Use Last — Specifies that the last entry of duplicate records should be used. If a duplicate record is encountered, the system does not report an error.  The default is Disallow.
   Maximum Errors Allowed	Specify the maximum number of error records to permit before stopping the import process. The default is 0.
   Prompt Before Importing	Select this option to display a prompt dialog to the user before the data is imported, and optionally customize the message displayed to the user. The prompt dialog contains the buttons Import and Cancel. The default message displayed to the user is “Are you sure you want to import data?”. Note: Variables created on the Variables page of this data import app are not supported for the message displayed to the user. If you do not select this option, the user does not see a message before data is imported. The default is cleared.
   Error File	Specify the path and name of the error file. This creates a text file in the location specified. All rejected records are captured in this file. Note: You can use the variables you defined on the Variables page for the Error File field.
   Log File	Specify the path and name of the log file. This creates a text file in the location specified. This log file captures all information related to the import such as the name and value of all variables created during execution. Error codes returned to the log file for ‘process complete’ or ‘terminated’ include: invalid coordinates encountered (i.e. parent symbols) duplicate records detected line number and error if a line of data fails aborted with errors (for example, if the MAXERROR parameter has been reached) completed with errors completed without errors (successful) process not complete Note: You can use the variables you defined on the Variables page for the Log File field.