Overview of Map Designer Express

Map Designer Express is a graphical development tool for creating and modifying maps. A map is made up of a series of transformation steps that define how to calculate the value for each attribute in the destination business object. Creating a map is the process of specifying the transformation steps for each destination attribute that you want to transform.

Using Map Designer Express, you can specify simple transformation steps, such as copying a source attribute to a destination attribute of the same data type, interactively using drag-and-drop. Map Designer Express automatically generates the Java code necessary to perform the transformation.

To assist with other common transformations, such as splitting a source attribute into multiple destination attributes or joining multiple source attributes into a single destination attribute, Map Designer Express prompts you for information, such as the delimiter on which to split or join, then generates the necessary Java code. To specify more complex transformations, you can define activities graphically using the Activity Editor in a custom transformation rule.

This section provides the following information as an overview to Map Designer Express:

Starting Map Designer Express

To launch Map Designer Express, you can do any of the following:

Important:
For Map Designer Express to be able to access maps stored in System Manager, Map Designer Express must be connected to an instance of System Manager. The preceding steps assume that you have already started System Manager. If you have not started System Manager, see the User Guide for WebSphere Business Integration Express for Item Synchronization for more information. If System Manager is already running, Map Designer Express will automatically connect to it.

Map Designer Express displays in its own application window. You can launch more than one instance of Map Designer Express at a time to edit more than one map.

Working in projects

Map Designer Express views, edits, and modifies maps stored in System Manager on a project basis. A project is simply a logical grouping of entities for managing and deployment purposes. System Manager allows you to create multiple projects.

When Map Designer Express establishes a connection to System Manager, it obtains a list of business objects that are defined in the current project. If you add or delete a business object using Business Object Designer Express, System Manager notifies Map Designer Express, which dynamically updates the list of business object definitions.

Before you can work on a map, you select which project the map is in by entering the name of the project in the Open a Map from a Project dialog. Before you switch to another project, you need to save the maps you modified in the current project. For more information on opening a map from a project and saving a map in a project, see "Opening a map from a project in System Manager" and "Saving a map to a project", respectively.

Layout of Map Designer Express

When you first open Map Designer Express without specifying a map, the Map Designer Express tab window is empty and the output window does not display. When you open an existing map, the Map Designer Express window displays the Map tabs in the tab window.

Table 5 describes each of the components in the Map Designer Express main window.

Table 5. Components of the Map Designer Express window
Window area Description For more information
Menus Provide options to access Map Designer Express functionality. "Main menus of Map Designer Express"
Toolbar Actually contains three separate toolbars, each of which provides a set of icons to access Map Designer Express functionality. "Map Designer Express toolbars"
Map Designer Express tab window Displays map information for an open map in one of four Map tabs. "Table tab" "Diagram tab" "Messages tab" "Test tab"
Output Window Displays results from the compilation of a map and other status messages. If the output window is not currently displaying when Map Designer Express generates a status message, it opens this window automatically. You can clear the contents of the output window with the Clear Output option of the View menu.

Tip: You can control whether the output window pane displays as part of the main window of Map Designer Express with the Output window option of the View menu.

N/A
Status Bar Displays Map Designer Express status messages.

Tip: You can control whether the status bar displays as part of the Map Designer Express window with the Status Bar option of the View menu.

N/A

The following sections describe the general layout of each of the tabs that display in Map Designer Express's tab window.

Table tab

The Table tab of Map Designer Express displays mapping information in a tabular format that lists all mapping attributes and transformations.

The Table tab consists of the following areas:

Attribute transformation table

The attribute transformation table presents in a tabular format all transformations associated with the map. Table 6 shows the columns that make up this table.

Table 6. Columns of the Attribute Transformation Table
Column name Description
Exec. Order The execution order for the destination attribute.

When you add a transformation to the end of this table, Map Designer Express automatically assigns its execution order as the last in the table. You can change the execution order of an attribute by typing the desired order number in the Exec. Order field.

Note:
You can specify how Map Designer Express handles the execution order of destination attributes with the option Defining Map: automatically adjust execution order. By default, this option is disabled. When the option is enabled, Map Designer Express automatically adjusts the execution order of other attributes. You can change the setting of this option on the General tab of the Preferences dialog. For more information, see "Specifying General Preferences".
Source Attribute

The name of the source attribute for the transformation.

This field provides a combo box that contains a list of all source and destination business objects with their attributes listed under them. Click the appropriate source attribute from this list. You can select multiple source attributes by clicking the Multiple Attributes entry in the combo box list. Map Designer Express displays the Multiple Attributes dialog from which you can select the attributes.

Note:
You can specify how Map Designer Express displays the source attribute name with the option Defining Map: show full attribute path. By default, this option is disabled and Map Designer Express displays all source attribute names as ...AttrName. When the option is enabled, Map Designer Express displays the full attribute path: ObjSrcBusObj.AttrName. You can change the setting of this option on the General tab of the Preferences dialog. For more information, see "Specifying General Preferences".
Source Type The data type of the source attribute.
This field is read-only.
Destination Attribute The name of the destination attribute for the transformation.

This field provides a combo box that contains a list of all source and destination business objects with their attributes listed under them. Click the appropriate destination attribute from this list.

Note:
You can specify how Map Designer Express displays the destination attribute name with the option Defining Map: show full attribute path. By default, this option is disabled and Map Designer Express displays all destination attribute names as ...AttrName. When the option is enabled, Map Designer Express displays the full attribute path: ObjDestBusObj.AttrName. You can change the setting of this option on the General tab of the Preferences dialog. For more information, see "Specifying General Preferences".
Dest. Type The data type of the destination attribute.
This field is read-only.
Transformation Rule The transformation rule and code for this attribute's transformation step.

This field provides a combo box that contains a list of standard transformations:

  • None (no transformation)
  • Join
  • Move
  • Split
  • Set Value
  • Submap
  • Cross-Reference
  • Custom

Click the appropriate transformation from this list to enter it in the field. For more information, see "Specifying standard attribute transformations".

Comment An informational description of the attribute's transformation.

See "Setting comments in the comment field of the attribute".

Defining a map from the Table tab: To define a map from the Table tab, follow these general steps:

  1. Click in an empty cell in the Source Attribute column. From the available combo box, click the source attribute to transform.
  2. Click in the corresponding cell in the Destination Attribute column. Click the destination attribute from the available combo box.
  3. Click in the corresponding cell in the Transformation Rule column. This column provides a combo box:
  4. Click in the corresponding cell in the Comment column. For more information, see "Setting comments in the comment field of the attribute".

Business Objects Pane

The business objects pane presents in a list all source and destination business objects associated with the map. Its left area displays the source business objects; its right area displays the destination business objects. If the map contains a temporary business object, the business objects pane contains three areas: Source Business Object, Temporary Business Object, and Destination Business Object.

Tip: You can control whether the business objects pane displays as part of the Table tab with the Business Objects Pane option of the

View menu.

Diagram tab

The Diagram tab of Map Designer Express provides a drag-and-drop interface for defining and reviewing the transformations. You view and design maps in the map workspace, which displays on the right side of the window.

The Diagram tab consists of the following areas:

Messages tab

The Messages tab displays the map's messages. A message consists of a message ID and its associated message text.

The Messages tab is divided into two panes. The top pane is the message grid, which consists of three columns: Message ID column, Message column, and Explanation column (for comments for the entire message file). The bottom or Description pane is for entering plain text. When you enter text into the Description pane, the text is added to the top of the generated message file as comments. Map Designer Express saves any change made to the map's messages in the project of System Manager.

For more information on messages and how to use them, see Appendix A, "Message files". For information about the format of messages, see "Format for map messages"..

When you compile a new map, Map Designer Express generates an external message file, based on the information entered in the Messages tab. This message file is saved in the message directory.

Attention:
You must make all changes to a map's messages through the Messages tab of Map Designer Express. Do not use an external text editor to make changes to the generated message file. Any changes made from the external editor will not be visible to Map Designer Express because they will not be stored in the map definition of the project. Furthermore, such changes will be overwritten the next time you compile the map.

Test tab

The Test tab provides an interface for testing maps and viewing the results. In this tab, you can run tests to verify that transformations are working properly.

The Test tab consists of the following areas:

Note:
Map Designer Express displays results from the test run of the map in the output window.

For more information on how to use the Test tab, see "Testing maps".

Assigning preferences

Map Designer Express provides the Preferences dialog to allow you to customize behavior of the Map Designer Express tool. To display the Preferences dialog:

Figure 6 shows the Preferences dialog.

Figure 6. Preferences dialog

Map Designer Express saves preference settings in the Windows registry. Therefore, they remain in effect for the current Map Designer Express session and future sessions. The Preferences dialog provides the following tabs:

Specifying General Preferences

The General tab of the Preferences dialog displays the general preferences you can specify for how Map Designer Express manages maps.

Table 7. General Map Designer Express Preferences

General Preference Description For more information
Open Map


validate map when open When this option is enabled, Map Designer Express validates the map when it opens it.

Recommendation: If a map uses business objects with many attributes, that is, more than a thousand attributes, enabling this option may result in the map taking a long time to open. If that is the case, and it is not desirable, you should disable this option.

"Opening a map"
Delete Map


close map before delete When this option is enabled, Map Designer Express always closes the currently open map before displaying the Delete Map dialog. "Deleting maps"

always display warning message When this option is enabled, Map Designer Express always displays a confirmation before deleting a map. "Deleting maps"
Compile Map


save map before compile When this option is enabled, Map Designer Express always saves the current map to the project in System Manager before compiling it. "Compiling a map"
Defining Map


automatically adjust execution order When this option is enabled, Map Designer Express automatically renumbers the execution order of destination attributes in the Table tab when execution order of an existing attribute changes. "Using execution order"

show full attribute path When this option is enabled, Map Designer Express shows the full attribute path for the names of source and destination attributes in the Table tab. "Table tab"

show business object instance name When this option is enabled, Map Designer Express displays the names of the source and destination business object and their variable names. When this option is disabled, Map Designer Express omits the names of the business object variables in both the Table and Diagram tabs. "Generating business object variables"

Specifying Validation

The Validation tab of the Preferences dialog provides options you can choose for Map Designer Express to perform validations on the map when you save the map. The options are as follows:

Map Designer Express will do the selected validation as deep as there are other transformation rules in that level.

Example: If path a.b.c is mapped, then Map Designer Express will perform these validations on business objects level a, a.b, and a.b.c.

For more information, see "Validating a map"..

Specifying Key Mappings

The Key Mapping tab of the Preferences dialog displays the key mappings for several standard transformations in the Diagram tab.

Table 8. Key Mapping Map Designer Express Preferences
Key map Description For more information
Move/Join/Submap Key map to use when creating a Move, Join, or Submap transformation. Map Designer Express distinguishes between the transformations by the type and number of source attributes:

  • Move--one source attribute that is not a child business object

"Copying a source attribute to a destination attribute"

  • Join--more than one source attribute that is not a child business object

"Joining attributes"

  • Submap--one or more source attributes that are a child business object

"Transforming with a submap"
Split
Key map to use when creating a Split transformation. "Splitting attributes"
Cross-Reference
Key map to use for maintaining identity relationships "Cross-referencing identity relationships"
Custom
Key map to use when creating a Custom transformation. "Creating a Custom transformation"

The Key Mapping tab provides the following functionality:

Customizing the main window

Map Designer Express provides the following ways to customize its main window:

Choosing how windows display

When you first open Map Designer Express without specifying a map, the main window is empty with the toolbars and status bar visible. When you open a map, Map Designer Express displays the Diagram tab in the tab window and opens the output window. By default, Map Designer Express displays each of the map tabs as follows:

You can customize the appearance of the main window and the Map tabs with options from the View menu. Table 9 describes the options of the View pull-down menu and how they affect the appearance of the Map Designer Express window.

Table 9.
View menu options for Map Designer Express window customization
View menu option Element displayed
Toolbars

A submenu with options for each of the Map Designer Express toolbars:

  • Standard toolbar
  • Designer toolbar
  • Programs toolbar

Status Bar A single-line pane in which Map Designer Express displays status information.
Business Objects Pane A pane that displays the source and destination business objects in the Table tab of Map Designer Express.
Project Pane A pane that displays the business object browser in the Diagram tab of Map Designer Express.
Diagram

A submenu with options for which attributes to display in the source and destination business objects in the business object windows of the Diagram tab:

  • All Attributes
  • Linked Attributes
  • Unlinked Attributes

The Designer toolbar also provides icons for displaying these attributes.

Output Window A small window across the bottom of the Map Designer Express window. The Clear Output option of the View menu clears all text in the output window.

Tip: When a menu option appears with a check mark to the left, the associated element displays. To turn off display of the element, select the associated menu option. The check mark disappears to indicate that the element does not currently display. Conversely, you can turn on display of an undisplayed element by selecting the associated menu option. In this case, the check mark appears beside the displaying element.

Floating a dockable window

Map Designer Express supports the following features as dockable windows:

Tip: By default, a dockable window is usually placed along the edge of the main window and moves as part of the main window. When you float a dockable window, you detach it from the main window, allowing it to function as an independent window. To float a dockable window, hold down the left mouse button, grab the border of the window and drag it onto the main window or desktop.

Using Map Designer Express functionality

You can access Map Designer Express's functionality using any of the following:

Main menus of Map Designer Express

Map Designer Express provides the following pull-down menus:

The following sections describe the options of each of these menus.

Functions of the File menu

The File pull-down menu of Map Designer Express provides the options shown in Table 10.

Table 10. Options of the File menu in Map Designer Express
File menu option Description For more information
New... Creates a new map file, clearing any existing map from the map workspace "Creating a map: Basic steps"
Open (submenu) A submenu that provides options for opening an existing map "Opening a map"
Close Closes the current map "Closing a map"
Save (submenu) A submenu that provides options for saving the current map to the same name "Saving maps"
Save As (submenu) A submenu that provides options for saving the current map to a name different from the map "Saving maps"
Delete... Deletes a specified map "Deleting objects"
Validate Map Validates the current map "Validating a map"
Compile Compiles the current map "Compiling a map"
Compile with Submap(s) Compiles the current map and its submaps "Compiling a map"
Compile All... Compiles all or a subset of maps defined "Compiling a set of maps"
Create Map Document... Creates HTML files that describe the map between business objects "Creating a map document"
View Map Document... Displays the HTML map-document file in your HTML browser "Viewing a map document"
Print Setup... , Print Preview , Print... Standard Windows print options so you can preview, print, and configure a print job "Printing a map"
Exit Exits Map Designer Express N/A

Functions of the Edit menu

The Edit pull-down menu of Map Designer Express provides the following options:

Functions of the View menu

The View pull-down menu of Map Designer Express provides the following options:

For information on View menu options that control display, see "Choosing how windows display".

Functions of the Debug menu

The Debug pull-down menu provides access to the debugging facilities of Map Designer Express. It provides the following options:

For more information about the use of Map Designer Express testing and debugging facilities, see "Testing maps".

Functions of the Tools menu

The Tools pull-down menu of Map Designer Express provides options to start each of the tools:

Functions of the Help Menu

Map Designer Express provides a standard Help menu with the following options:

Context menu

The Context menu is a shortcut menu that is available, by right-clicking, from numerous places, such as the transformation rule column, row header in the Table view, child business object in the source testing pane, or edit box in a dialog.

A menu opens that contains useful commands, which change depending on where you click.

Example: Clicking in the transformation rule column opens a Context menu that provides the following options:

Note:
The default action when you double-click the transformation cell is Open. If Open is not available for that transformation, then a message saying that the action is not available is displayed in the status bar.

Map Designer Express toolbars

Map Designer Express provides three toolbars with common tasks you need to perform:

These toolbars are dockable; that is, you can detach them from the palette of the main window and float them over the main window or the desktop.

Tip: To identify the purpose of each toolbar button, roll over each button with your mouse cursor.

Standard toolbar: Figure 7 shows the Standard toolbar.

Figure 7. Standard toolbar

The following list provides the function of each Standard toolbar button, left to right:

  1. New map
  2. Open
  3. Save to project
  4. Open from file
  5. Save to file
  6. Find in map
  7. Print map
  8. Cut
  9. Copy
  10. Paste
  11. Delete
  12. Help

Designer toolbar: Figure 8 shows the Designer toolbar.

Figure 8. Designer toolbar

The following list provides the function of each Designer toolbar button, left to right:

  1. Add Business Object
  2. Validate
  3. Compile
  4. Run Test
  5. Continue
  6. Step over
  7. Toggle Breakpoints
  8. Clear All Breakpoints
  9. All Attributes
  10. Linked Attributes
  11. Unlinked Attributes

Programs: Figure 9 shows the Programs toolbar.

Figure 9. Programs toolbar

The following list provides the function of each Programs toolbar button, left to right:

  1. Map Designer Express
  2. Business Object Designer Express
  3. Relationship Designer Express

Keyboard shortcuts

Map Designer Express provides the keyboard shortcuts shown in Table 11 for many of the menu options.

Table 11. Keyboard shortcuts for Map Designer Express
Keyboard shortcut Description For more information
Ctrl+E Save the current map definition to a map definition file "Saving a map to a file"
Ctrl+F Display Find control panel to locate text or unlinked attributes in the map (use Ctrl+H for replace) "Finding information in a map"
Ctrl+H Display Replace dialog to find and replace text in customized Java Code and comments of transformation rules. "Finding and replacing text"
Ctrl+I Open a map definition file "Opening a map from a file"
Ctrl+M View a map document "Viewing a map document"
Ctrl+N Display the New Map wizard to create a new map "Creating a map: Basic steps"
Ctrl+O Open a map definition from the project in System Manager "Opening a map from a project in System Manager"
Ctrl+P Print the map definition "Printing a map"
Ctrl+S In Map Designer Express main window--Save the current map definition to the project in System Manager "Saving a map to a project"
Ctrl+U Display the Preferences dialog to set Map Designer Express preferences "Assigning preferences"
Ctrl+Alt+F Save the current map definition to a map definition file with a different name (Save As) "Saving a map to a file"
Ctrl+Alt+S Save the current map definition to the project in System Manager with a different name (Save As) "Saving a map to a project"
Ctrl+Shift+P Display the Print Setup dialog to specify information for printing the map definition "Printing a map"
Ctrl+Enter Display the Map Properties dialog, from which you can set general and business object properties for the map "Providing map property information"
F7 Compile the current map "Compiling a map"
Alt+F4 Close the current map "Closing a map"
Del Delete the currently selected entity N/A
F1 Display context-sensitive help for the current dialog or window N/A
Ctrl+F7 Compile all or a subset of maps defined in System Manager "Compiling a set of maps"
F8 During a test run, continue a paused map by executing until the end of the map or another active breakpoint "Processing breakpoints"
F9 Toggle the state of a breakpoint for a transformation rule "Setting breakpoints"
F10 During a test run, continue a paused map by executing the next single step "Processing breakpoints"

Copyright IBM Corp. 1997, 2003