Maintaining Mappings

Users with the appropriate permissions can create, view, and modify maps and mappings to maintain system data. A map is a collection of mappings for a specified dimension. A mapping is a rule for translating an account code or other code in your source file to a Longview symbol name when importing data into the Longview database.

You can use maps created using the Mappings editor in data import apps in Longview Designer and in the Define function in Longview Application Framework.

For more information on data import apps, see the Longview Designer Guide.

For more information on the Define function, see the Longview Developer’s Guide.

Understanding the Mappings editor interface

The Mappings editor contains a unique layout to maximize screen space and display as many mappings as possible.

Mappings editor

The Mappings editor is divided into the maps page and the map properties page.

All maps in the system are displayed in a list on the maps page. When you select a map, the map’s properties and all mappings for the selected map are displayed in a list on map properties page.

The Mappings editor includes the administrative toolbar.

Administrative toolbar

The following table lists the button that appears on the administrative toolbar:

Maps page

The maps page contains a list of all maps that currently exist in your system. The list shows the name, dimension, and tag for each map.

The maps page includes the page toolbar.

Page toolbar

The following table lists the buttons that appear on the page toolbar:

Map properties page

The map properties page contains the map information area and the mappings area. The map information area contains the selected map’s name, dimension, and tag. The mappings area contains a list of all mappings for a selected map. The map properties page contains the properties toolbar and the area toolbar.

Properties toolbar

The following table lists the buttons that appear on the properties toolbar:

Area toolbar

The following table lists the buttons that appear on the mappings area toolbar:

Working with maps

All maps in the system are displayed in a list on the Maps page. Depending on your authorizations and symbol access, you can view, add, modify, or delete maps.

Note: Mappings authorization is set by your Administrator

Accessing the Mappings editor

You can access the Mappings editor from the following locations, depending on the setup of your system, the products you have purchased, and your authorizations:

• Longview Dashboard — The Mappings editor is included with Longview Dashboard Designer as a system panel. Your System Administrator must add this panel to the appropriate Dashboard pages for you to access it.
• Longview Designer — The Mappings editor is available from the Administration category of the Designer navigation pane.
• Longview Tax — The Mappings editor is available from the Administration category of the Tax Provision navigation pane.

To access the Mappings editor from your Longview Dashboard:

1. On your Longview Dashboard page, click the Mappings link in the Mappings panel. The Mappings editor opens in a new window.

   Note: If this is the first time you are running the Mappings editor, you may have to complete additional steps. For more information, see the Longview Dashboard User’s Help.

To access the Mappings editor from Longview Designer:

1. In the Designer navigation pane, click Administration.
2. Click Mappings. The Mappings editor opens in the workspace.

To access the Mappings editor from Tax Provision:

1. In the Tax Provision navigation pane, click Administration.
2. Expand System and click Mappings. The Mappings editor opens in the workspace.

Adding maps

If you have the appropriate authorization, you can use the Mappings editor to add a new map to the system.

To add a map:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. Click Map. A new row appears at the bottom of the maps list.
3. Complete the following fields:

   Feild	Description
   Name	Type a name for the map. The map name must be unique and can have a maximum of 255 characters, including spaces.
   Dimension	Select the dimension to which the map applies. Accessible schedule dimensions also appear in the list.
   Tag	Type a tag to assign to the map. Tag is optional and can have a maximum of 255 characters, including spaces.

4. Click Save. The map appears in the maps list.
5. To add mappings to the map, proceed to Adding mappings or Importing mappings.

Editing maps

If you have the appropriate authorization, you can use the Mappings editor to edit the properties of a map including the name, dimension, and tag. When Edit mode is On, the map is locked and other users cannot make changes.

To edit a map:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. In the maps list, select the map you want to edit, and click Edit. Edit mode switches to Edit: On.

   Caution: Changing the Dimension of a map removes all existing mappings.

3. Make the necessary changes and click Save. The map is saved.
4. If you are done editing the selected map, click Edit. Edit mode switches to Edit: Off. If you want to modify mappings, proceed to Adding mappings or Editing mappings.

Searching maps

You can use the Search Maps box to search for a map.

To search maps:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. Type in the Search Maps box. Matches, if any, appear highlighted yellow in the maps page.
3. If your search returned more than one result, click Next to navigate the search results.

Sorting maps

You can sort the list of maps by name, dimension, or tag.

To sort maps:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. On the maps page, click the row header of the field by which you want to sort maps. Maps appear sorted alphabetically under the selected field.

Deleting maps

If you have the appropriate authorization, you can use the Mappings editor to delete a map.

Caution: Deleting a map deletes all the associated mappings. You cannot undo the deletion of a map; you must re-create the map and its mappings.

To delete a map:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. In the maps list, select the map you want to delete, and click Delete. A confirmation dialog opens.
3. Click Delete. The map is removed from the system, including all associated mappings.

Working with mappings

All maps in the system are displayed in a list on the maps page. When you select a map, the map’s properties and all mappings for the selected map are displayed on the map properties page. Depending on your authorizations and symbol access, you can view, add, modify, or delete mappings.

Note: Mapping authorization is set by your Administrator.

Understanding mapping methods and expressions

Maps contain instructions for importing data when the symbol names in your source file do not match the symbol names in the Longview database. A map contains a number of mappings, which specify methods for the way in which a source symbol should be mapped to a Longview database symbol using an expression.

You can create internal maps using the Mappings editor and external maps in Longview Application Framework.

For more information on a creating a sample external map, see “Sample External Map” in the Longview Developer’s Guide. You can use one of three methods in a mapping:

• Exact
• Wildcard
• Range
• In

You can use all alphanumeric and ASCII characters in an expression except for double quotation marks (”). The following are the rules for each method:

Exact

Use this method to match the expression value exactly. For example, use the exact method to map a single source symbol name to a Longview database symbol name exactly as indicated in the expression.

Note: Special characters are matched exactly when used in an expression for the Exact method.

• Internal syntax

  

• External syntax

  Map Cash, EXACT, 10000

  Map AccountsReceivable, EXACT, 20000

Wildcard

Use this method to match the expression field partially by including wildcards in an expression. This method is case sensitive. Use the question mark ( ? ) to specify any one character as wildcard. Use the asterisk ( * ) to specify zero or more characters as wildcards. You can use multiple question marks in an expression but only one asterisk. For example, use the wildcard method to import source symbols beginning with certain characters to a Longview database symbol name.

Note: If you use an asterisk, it must be the last character in the expression

• Internal syntax

  

• External syntax

  Map Cash, WILDCARD, 1000?

  Map AccountsReceivable, WILDCARD, 200*

Range

Use this method to match a range of values, separated by a hyphen. This method is case sensitive. For example, use the range method when you have a range of source symbol names to import to a Longview database symbol name.

• Internal syntax

  

• External syntax

  Map Cash, RANGE, 10000-10009

In

Use this method to match the expression value to one of several values. For example, use the IN method when you have a set of source symbol names to import to a Longview database symbol name. This method is case sensitive. You may also use the wildcard characters question mark (?) and asterisk (*) in the IN clause.

• Internal syntax

  

• External syntax

  Map E12130, IN, “E12130,E11130, E11140, E12000”

  Map E13100, IN, “E13*,E00000”

  Map E11110, IN, “E11??0,E11111”

Understanding duplicate mappings

When you use the Mappings editor to add mappings, the map containing the mappings is used to import data using a data import app. The designer of a data import app can permit duplicate mappings using the Allow Duplicate Mappings setting in Longview Designer. If Allow Duplicate Mappings is not selected for a data import app, duplicate mappings are not permitted. If duplicate mappings are not permitted and multiple mappings are found, the system reports an error for each mapping.

In some cases, you may add duplicate mappings intentionally. You may want to, for example, translate an account code in your source file to multiple Longview symbols. This is classified as a duplicate mapping.

Note: Do not confuse duplicate mappings with duplicate records. A duplicate record occurs when you translate multiple account codes in your source file to one Longview symbol. You can use the Duplicate Records setting in Longview Designer to specify the way the system treats duplicate records.

Use the following table to review sample duplicate mappings for each mapping method and the way the system imports the data when Allow Duplicate Mappings is selected.

Order

When Allow Duplicate Mappings is selected, the order of mappings in a map does not matter for Exact mappings. Consider the order of mappings contained in the following two maps, and the result:

Map A

Map B

In both cases, the system imports the value from 10020 to A1000.

Order matters for Wildcard and Range mappings. The system imports the value based on the first matching Wildcard or Range mapping listed. Consider the order of mappings in the following map for the source file account code 10020:

In this case, the value from 10020 is imported to A3000, not to A4000, because the specified Range mapping is listed first and includes 10020.

Adding mappings

If you have the appropriate authorization, you can use the Mappings editor to add mappings to a map.

Note: Typically, you should list Exact mappings first, followed by Wildcard and Range mappings.

To add a mapping:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. From the map list, select the map to which you want to add mappings. The list of mappings for the selected map appears in the maps properties page.
3. Click Edit. Edit mode switches to Edit: On.
4. Do one of the following:
   • To add a new mapping to the bottom of the list, click Mapping. The new mapping appears at the bottom of the mappings list.
   • To add a new mapping below a specific mapping, select a row and click Mapping. The new mapping appears below the selected row.
5. Complete the following fields:

   Field	Description
   Symbol	Type a symbol name or use the Symbol Selector to specify the symbol for the mapping.
   Method	Select one of the following mapping methods: Note: If Allow Duplicate Mappings is selected for Data Import Apps, duplicate mappings are handled differently depending on the specified mapping method. For more information, see Understanding duplicate mappings. Exact — Use this method to match the expression field value exactly. Wildcard — Use this method to match the expression field partially by including the question mark ( ? ) to specify any one character and/or the asterisk ( * ) to specify zero or more characters. You can use multiple question marks but only one asterisk in an expression. Note: If you use an asterisk, it must be the last character in an expression. Range — Use this method to match a range of values, separated by a hyphen ( - ). Note: The start range and end range values must have the same number of characters
   Expression	Type the expression for the symbol mapping. For more information on creating expressions, see Understanding mapping methods and expressions.

6. Click Save. The mapping appears in the mappings list.
7. If you are done adding mappings to the selected map, click Edit. Edit mode switches to Edit: Off.

Editing mappings

If you have the appropriate authorization, you can use the Mappings editor to edit a mapping.

Note: You can edit mappings only for symbols to which you have write access.

To edit a mapping:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. In the maps list, select the map containing the mapping you want to edit. The list of mappings for the selected map appears on the mappings page.
3. Click Edit. Edit mode switches to Edit: On.
4. Make the necessary changes and click Save. The mapping is saved.
5. If you are done editing mappings in the selected map, click Edit. Edit mode switches to Edit: Off.

Importing mappings

If you have the appropriate authorization, you can use the Mappings editor to import mappings. You can use a comma-delimited (.csv) file to import mappings into a map.

The .csv file must contain the following information on each line for each mapping:

Symbol, Method, Expression

To import mappings:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. From the maps list, select the map to which you want to import mappings.
3. Click Edit. Edit mode switches to Edit: On.
4. Click Import. A dialog opens.
5. Navigate to, and select, the .csv file containing the mappings you want to import and click Open. The mappings are appended to the mappings list.
6. If you are done importing mappings to the selected map, click Edit. Edit mode switches to Edit: Off.

Exporting mappings to Microsoft Excel

If you have the appropriate authorization, you can use the Mappings editor to export mappings to Microsoft Excel.

Note: Any mappings with symbols you do not have access to are not exported.

To export mappings:

1. Open the Mappings tool using the appropriate method. For more information, see Accessing the Mappings editor.
2. From the map list, select the map containing the mappings you want to export. The mappings list appears on the mappings page.
3. Click Export to Excel. A dialog opens.
4. Specify a name for the export file and click Save. The mappings are exported to the specified file.

Searching mappings

You can use the Search Mappings box to search for a mapping.

To search mappings:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. From the map list, select the map containing the mappings you want to search. The mappings list for the selected map appears on the mappings page.
3. Type in the Search Mappings box. Matches, if any, appear highlighted yellow.
4. If your search returned more than one result, click Next to navigate the search results.

Reordering mappings

If you have the appropriate authorization, you can use the Mappings editor to change the order of mappings. The order of mappings is important because the system maps the source file symbol names to the database sequentially.

To reorder mappings:

1. Open the Mappings editor using the appropriate method.
   For more information, see Accessing the Mappings editor.
2. From the map list, select the map containing the mappings you want to reorder. The mappings list for the selected maps appears on the map properties page.
3. Click Edit. Edit mode switches to Edit: On.
4. Select the mapping you want to reorder, and then click either Move Up or Move Down. The mapping moves one row in the indicated direction.
5. If you want to continue to move the selected mapping, repeat step 4 until the mapping is in the desired location.
6. If you are done reordering mappings for the selected map, click Edit. Edit mode switches to Edit: Off.

Deleting mappings

If you have the appropriate authorization, you can use the Mappings editor to delete a mapping.

Note: You can delete mappings only for symbols to which you have write access.

To delete a mapping:

1. Open the Mappings editor using the appropriate method. For more information, see Accessing the Mappings editor.
2. In the maps list, select the map containing the mapping you want to delete. The list of mappings for the selected map appears on the map properties page.
3. Click Edit. Edit mode switches to Edit: On.
4. In the mappings list, select the mapping you want to delete, and click Delete. The mapping is deleted.

   Note: You can select multiple mappings by pressing and holding the Ctrl key on your keyboard while clicking rows. You can select multiple contiguous mappings using the Shift + click keystroke combination, or all mappings using the Ctrl + a keystroke combination.

5. If you are done deleting mappings in the selected map, click Edit. Edit mode switches to Edit: Off.