Creating a map: Basic steps

Table 13 provides an overview of the subtasks for creating a new map.

Table 13. Subtasks for creating a new map

Subtask Associated procedure (see . . . )
1. Creating a new map file with the New Map wizard, specifying the project, the source and destination business objects, and the name for the new map. "Steps for creating the map definition".
2. Setting the verb for each destination business object. In most cases, destination business objects have the same verb as source business objects. You can also set the value of the verb always to be a specific value. "Setting the destination business object verb".
3. Specifying the transformation steps for each destination attribute that you want to map. How you do this depends on what kind of transformation is required. "Specifying standard attribute transformations".
4. Specifying the comment for the destination attribute. Although this information is optional, it greatly improves readability of the map information in Map Designer. "Setting comments in the comment field of the attribute".
5. Saving the map. "Saving maps".
6. Checking completion, validating, and compiling the map. Checking completion, Validating a map, and Compiling a map
7. Testing and debugging the map. Testing maps

Steps for creating the map definition

Map Designer provides a New Map wizard to assist you in creating a map definition. Perform the following steps to create a map definition using the New Map wizard :

  1. Start the New Map wizard in one of the following ways:

    Result: Map Designer displays the first window of the New Map wizard.
    This figure is a screen shot of the New Map wizard screen with a project type selected.

    Figure 10. Welcome window of New Map wizard

  2. From the list box, select the name of the project for which you want to create the map.
  3. Select the business object you will use as the source business object for the map. You can select one or more source business objects by clicking in the Use column of each desired business object. Then click Next to continue.
    This figure is a screen shot showing a list of source business objects with one source object selected.

    Figure 11. Selecting source business objects

    Tip: To locate a particular business object, enter its name in the Find field. The up and down arrows scroll through the business object list. Click Next to continue.

    The New Map wizard does not require that you specify the source business object. You can click Next without selecting the source business object to postpone specifying this business object definition. You can specify it at a later time in the map workspace of the Diagram tab. For more information, see "Creating the source and destination business objects".

    Note:
    If you add or delete a business object from System Manager, it dynamically updates the list of business object definitions.
  4. Select the business object type you will use as the destination business object for the map. You can select one or more destination business objects by clicking in the Use column of each desired business object. Then click Next to continue.
    This figure is a screen shot of the list of destination business objects with one business object selected described in Step 4.

    Figure 12. Selecting destination business objects

    Tip: To locate a particular business object, enter its name in the Find field. The up and down arrows scroll through the business object list. Click Next to continue.

    The New Map wizard does not require that you specify the destination business object. You can click Next without selecting the destination business object to postpone specifying this business object definition. You can specify it at a later time in the map workspace of the Diagram tab. For more information, see "Creating the source and destination business objects".

    Note:
    If you add or delete a business object from System Manager, it dynamically updates the list of business object definitions.
  5. Specify the name to associate with the map.
    This figure is a screen shot of Save Map screen with "Generic to Application Specific" option selected in the Mapping Direction section.

    Figure 13. Saving new map

    Rule: A map name must be less than or equal to 76 alphanumeric characters and underscores (_). It cannot contain spaces or certain punctuation symbols, such as a period, a left brace([), a right brace (]), a single quotation mark, or a double quotation mark.

    The New Map wizard does not require that you specify the map name. You can click Finish without entering the map name to postpone naming this map definition. When you save the map, Map Designer prompts you with the Save Map As dialog for you to specify the required map name. For more information, see "Saving a map to a project".

    Specify whether the map is an inbound or outbound map. This map role is needed for automatically generating relationship codes.

  6. Click Finish to save the new map definition with the specified source and destination business objects.

    Result: Map Designer displays the new map's information in its Diagram tab.

Creating the source and destination business objects

If you do not specify the map's source and destination business objects from the New Map wizard, you can specify them from the Add Business Object dialog or the Diagram tab in the business object browser.

Steps for specifying business objects from the Add Business Object dialog

Perform the following steps to add a source or destination business object to a map from the General tab of the Add Business Object dialog.

  1. Display the Add Business Object dialog in one of the following ways:
  2. To specify a source business object:

    Tip: To locate a particular business object, enter its name in the Find field. The up and down arrows scroll through the business object list.

  3. To specify a destination business object:

    Tip: To locate a particular business object, enter its name in the Find field. The up and down arrows scroll through the business object list.

  4. To close the dialog, click Done.

Steps for specifying business objects from the Diagram tab in the business object browser

From the Diagram tab, you can add a source or destination business object to a map. Perform the following steps to do this:

  1. Drag the source business object from the business object browser to the left side of the map workspace. The business object displays and its title starts with Src.
  2. Drag the destination business object from the business object browser to the right side of the map workspace. The business object displays and its title starts with Dest.

Note:
A dotted-line boundary divides the left and right halves of the workspace and identifies the source and destination portions of the map workspace. Be sure to carefully drop objects in the appropriate place.

Figure 14 shows the source and destination business objects in the map workspace.
This figure is a screen capture showing the source business objects on the left side of the screen and the destination business objects on the right side of the screen.

Figure 14. Defining Source and Destination business objects

Tip: Alternatively, you can create the source and destination business objects by right-clicking the business object in the business object browser; selecting Copy from the Context menu; then right-clicking in the map workspace and selecting Paste As Input Object or Paste As Output Object.

Map Designer creates a window, called a business object window, for the source and destination objects. The title bar of this window displays the business object instance name. For help interpreting the title bar of the business object window, see "Using generated business object variables and attributes".. The business object window for the source business object contains columns for the name and data type of each source attribute. The business object window for the destination business object contains columns for the name, data type, transformation rule (which identifies the transformation step), and an optional comment.

Guideline: If you make a mistake by dragging the wrong business object or making it an output object instead of input, you can delete the object from the map workspace and try again. To delete a business object from the map workspace, you can either:

Setting the destination business object verb

The verb indicates how the system should process the business object's data. When a map executes, the system needs to know what verb to assign to each destination business object it creates.

If a map has only one source business object and one destination business object, the verb for the destination business object is usually the same as the verb for the source business object.

In this case, you need to copy the verb from the source business object to the destination business object (see Figure 14), by defining a Move transformation rule with the source attribute as the source business object's verb and the destination attribute as the destination business object's verb. For more information, see Copying a source attribute to a destination attribute.

Tip: You can also drag-and-drop the verb from the source business object to the destination business object to define the value of the verb.

If a map has a destination business object with a verb that is not found in the source business object, you need to set the verb to a constant value, by defining a Set Value transformation rule with the destination attribute as the destination business object's verb. In the Set Value dialog box, enter the constant verb value. For more information, see Specifying a value for an attribute.

Maps sometimes have more than one source or destination business object, and these objects can have several child business objects. In these cases, you must consider carefully which verb to assign to each destination business object. Some destination business objects might require some custom logic to set the verb based on the verbs of one or more source business objects.

Specifying standard attribute transformations

You can specify several standard attribute transformations interactively in Map Designer while writing little or no Java code. Table 14 shows the standard transformations that you can specify in Map Designer.

Table 14. Common attribute transformations

Name Transformation step Purpose
Set Value
Specifying a value for an attribute For an attribute in the destination business object that is not found in the source business object but is required in the destination application
Move
Copying a source attribute to a destination attribute For an attribute that is the same in both the source and destination business objects
Join
Joining attributes For an attribute in the destination business object that is a combination of several attributes in the source business object
Split
Splitting attributes

For an attribute in the destination business object that is either:

  • Only one part of an attribute in the source business object
  • Made up of several fields, but with different delimiters from those in the source business object

Submap
Transforming with a submap For attributes in the source and destination business objects that contain child business objects
Cross-Reference
Cross-referencing identity relationships For maintaining the identity relationships for the business objects
Custom
Creating a Custom transformation For an attribute that requires transformations not provided by the automatically generated transformations

For information on additional transformations you can perform, see "More attribute transformation methods".

In the Diagram tab, you can select which attributes display in the business object windows with the options of the View > Diagram menu. You can choose to display all attributes, only linked (mapped) attributes, or only unlinked (unmapped) attributes.

Tip:
Attributes appear in the same order that they appear in the business object definition. To locate a particular attribute in a long list of attributes, select Find from the Edit menu (or use the keyboard shortcut of Ctrl+F). For more information, see "Finding information in a map"..

Specifying a value for an attribute

Some destination attribute values do not depend on a source attribute and can be filled in with a constant value. This is especially true if the destination business object contains many attributes that are not found in the source business object but are required in the destination application. Some examples of default values for attributes are CustomerStatus = "active" or AddressType = "business".

This type of transformation is called a Set Value transformation. You set the value of a destination attribute with the Set Value dialog, shown in Figure 15.

Steps for specifying a Set Value transformation

Perform the following steps to specify a Set Value transformation:

  1. Display the Set Value dialog in one of the following ways:
  2. Through the Set Value dialog, you set the constant value to assign to the destination attribute. The Set Value dialog provides the following functionality:

Copying a source attribute to a destination attribute

The simplest kind of transformation step is a copy of one source attribute into a corresponding destination attribute. This type of transformation is called a Move transformation.

Steps for specifying a Move transformation

Perform the steps from one of these map tabs to specify a Move transformation:

Result: Map Designer generates the code to copy the value of the source attribute to the destination attribute. If the source and destination attributes are of different data types, Map Designer determines whether a type conversion is possible, and if so, generates the code to convert the source type to the destination type. If a type conversion is not possible, or might result in data loss, Map Designer displays a dialog box for you to confirm or cancel the operation.

If you want to see a sample of the generated code for the Move transformation, in the Context menu of the rule column, select View Source.

Joining attributes

You can concatenate, or join, the values from more than one source attribute into a single destination attribute. This type of transformation is called a Join transformation. For instance, the source business object might store the area code, telephone number, and extension in separate attributes, while the destination business object stores these values together in one attribute.

In addition to joining the attributes, you can reorder them and insert delimiters, parentheses, or other characters. For instance, when joining separate area code and telephone number attributes into a single attribute, you might want to insert parentheses around the area code.

Tip:
The attributes you want to join can sometimes be located in more than one source business object, such as in a parent business object and one of its child business objects. You can also join an attribute with a variable you have defined. (To learn about defining variables, see Creating temporary variables.)

You join multiple source attributes into one destination attribute with the Join dialog, shown in Figure 16.

Steps for specifying a Join transformation

Perform the following steps to specify a Join transformation:

  1. Display the Join dialog in one of the following ways:
  2. Through the Join dialog, you build an expression to concatenate the source attributes by adding delimiters, grouping with parentheses, and reordering the attributes if necessary. The Join dialog provides the following functionality:

Result: Map Designer generates the code to join the source attributes. If any source attribute is of a different data type from the destination attribute, Map Designer makes the necessary calls to methods in the DtpDataConversion class to convert the types.

Splitting attributes

To split a source attribute into two or more destination attributes, you specify the transformation for each destination attribute separately. This type of transformation is called a Split transformation. For instance, to split a source attribute, such as phone_number, into three separate destination attributes, such as area_code, tel_number, and extension, you specify the transformations for area_code, tel_number, and extension separately.

You split a source attribute into multiple destination attributes with the Split dialog, shown in Figure 17.

Steps for specifying a Split transformation

Perform the following steps to specify a Split transformation:

  1. Display the Split dialog in one of the following ways:
  2. Through the Split dialog, you split an expression into segments that are separated by a delimiter. Each segment is identified with an index number, with the first segment having an index number of zero (0). The Split dialog provides the following functionality:

Result: Map Designer generates the transformation code for the destination attribute. The generated code uses methods from the DtpSplitString() class to parse the source attribute into segments.

Transforming with a submap

A submap is a map that is called from within another map, called the main map. This section provides the following information about submaps:

Uses for submaps

You can call a submap to obtain a value for any destination attribute, but submaps are most commonly used for the following:

Improving map modularity

Using submaps can improve the modularity of your maps by isolating common transformations that can be reused in more than one map. For example, a Customer business object might have an Address child business object that is also a child of an Order business object. If you create a submap for the Address business object, you can reuse the submap in both the Customer and Order business object maps.

Figure 18 illustrates how a submap, MyAddrToGenAddr, can be reused by two different maps.

Figure 18. Using submaps for modularity


Transforming child business objects

When the source and destination attributes contain multiple-cardinality child business objects, it is useful to use a submap to specify their transformations. Typical examples of multiple-cardinality child business objects are the multiple addresses of a customer or the multiple line items in an order.

In the simplest case, you transform each source child business object into a single destination child business object, in a one-to-one relationship. Figure 19 illustrates the use of submaps for an Employee business object and its child business array that contains instances of EmployeeAddress.

Figure 19. One-to-one transformation of child business object arrays

This figure shows the Employee business object map with Address (2), Address(1), and Address(0) depicited as submaps.

A submap can be associated with a conditional statement that governs whether it executes. For example, consider Figure 20: the Order business object has an OrderLine attribute that contains a multiple-cardinality child business object, OrderLine. The OrderLine business object has a DeliverySchedule attribute that contains a multiple-cardinality child business object, DelSched.
This figure shows the Order object on the top row associated with three Orderline business objects and each Orderline object associated with three DelSched business objects on the bottom row.

Figure 20. Source business object with multiple-cardinality child business object

Some conditions that can be written in the map for Order can:

Steps for specifying a Submap transformation

Perform the following steps to specify a Submap transformation:

  1. Create the map that you want to use as a submap.

    Recommendation: You do this in the same way that you create and save any other map. IBM naming conventions suggest that submap names begin with the string "Sub_".

  2. Save the submap to the project in System Manager and compile the submap.
  3. Specify the Submap transformation on the attribute in the parent business object that needs to call the submap. This source attribute contains a child business object that is mapped to a destination attribute that contains a child business object.

    You specify that a submap needs to be called with the Submap dialog, shown in Figure 21.. Display the Submap dialog in one of the following ways:

  4. Through the Submap dialog, you specify the name of the submap to call. The Submap dialog provides the following functionality:

Result: Map Designer generates the Java code to call the specified submap. It automatically creates a call to the runMap() method to call the submap.

Note:
In any attribute's code, you can use Expression Builder to insert a map execution call. For more information, see "Using Expression Builder to call a submap".
Reminder:
If you have saved a transformation rule using custom Java code, you will need to manage any object dependencies that are used in the custom Java code manually. For example, if the custom Java code calls a submap, then you will need to manually deploy the submap to the server.

Cross-referencing identity relationships

In some cases, the source attribute may need to reference a relationship table to find out what value to set in the destination attribute. This can be done using a Cross-Reference transformation.

Steps for specifying a Cross-Reference transformation

Perform the following steps to specify a Cross-Reference transformation:

  1. Select the source and destination attributes in any of the ways previously described for other transformations. Both have to be business objects.
  2. Select Cross-Reference in the corresponding transformation cell.

    Result: The Cross-Reference dialog appears:
    This figure shows the Cross-Reference dialog with one cross-reference selected in the Name field.

    Figure 22. Cross-Reference dialog

  3. In this dialog, select the relationship name from the list.

    Result: The Participant combo box will be populated with all participants from the selected relationship. The Business Object combo box, by default, will be populated according to the mapping role defined in the map property. You can change the combo boxes.

Creating a Custom transformation

In a Custom transformation, you use Activity Editor to customize the activity for the transformation graphically or to enter the Java code to transform the source attribute to the destination attribute.

Tip: If you want to use only one standard function block in a custom transformation, you can configure the function block in the Preferences dialog for direct use in Map Designer. For more information, see Tip: Using function blocks directly in Map Designer

Steps for specifying a Custom transformation

Perform the steps from one of these map tabs to define a Custom transformation:

Tip: You can customize the key sequence used to initiate a Custom transformation from the Key Mapping tab of the Preferences dialog. For more information, see "Specifying Key Mapping".

Result: Map Designer displays Activity Editor with a graphical view. For more information on Activity Editor, see Overview of Activity Editor.

Reminder:
If you have saved a transformation rule using custom Java code, you will need to manage any object dependencies that are used in the custom Java code manually. For example, if the custom Java code calls a submap, then you will need to manually deploy the submap to the server.

Table 15 lists information in this guide that is useful in defining a custom transformation.

Table 15. Defining custom transformations

Information provided For more information
How to use Activity Editor to customize transformation code "Customizing a map"
How to create relationships for relationship attributes For a general introduction to relationships, see Introduction to relationships.
1. Use Map Designer to create the map for the business objects that contain relationships. Creating maps
2. Use Relationship Designer to define the relationship. Creating relationship definitions
3. Return to Map Designer to code the relationship between the attributes. Implementing relationships
More complex transformations you can perform: "More attribute transformation methods"

Content-based logic "Content-based logic"

Date formatting "Date formatting"

String processing "Using Expression Builder for string transformations"

Note:
You can also customize an existing transformation by modifying the generated code from Activity Editor. If you modify code in auto-update mode, Activity Editor prompts for a confirmation. If you confirm the change, Activity Editor saves the customized code. The label of the transformation icon in the Transformation Rule column of the Table or Diagram tab changes from displaying in black, normal text to displaying in blue, italic text. These blue icon labels help you distinguish between code that is in auto-update mode (generated by Map Designer) and code you have customized.

You can tell Activity Editor not to confirm by changing the setting in the Preferences dialog.

Saving maps

To preserve the map definition for use at a later time, you must save the map. Before Map Designer saves a map, it first validates the map. For more information, see "Validating a map".

Map Designer provides two ways to save the current map:

Important:
For Map Designer to be able to save a map, a map must currently be open.

Saving a map to a project

A map definition stores map information in a project in System Manager. This map definition contains the following information for a map:

To save a map to a project in System Manager, you can perform any of the actions shown in Table 16.

Table 16. Saving a map to the project

If you want to . . . Then . . .
Save the map definition to the name of the currently open map.

Do one of the following:

  • Select To Project from the File > Save submenu.
  • Use the keyboard shortcut of Ctrl+S.
  • In the Standard toolbar, click the Save Map to Project button).

Save the map definition to a name different from the currently open map.

Do one of the following:

  • Select To Project from the File > Save As submenu.
  • Use the keyboard shortcut of Ctrl+Alt+S.

Result: Map Designer displays the Save Map As dialog in which you can specify the map name.


This figure shows the Save Asdialog with the Project, Map selected and the Map Name typed in the Name field.

Figure 23. Save As dialog

When you save the map, Map Designer saves the map definition and map content to the project in System Manager. It saves the map content as XML data.

Note:
You can specify whether Map Designer automatically saves a map to the project in System Manager before compiling the map with the option Compile Map: save map before compile. By default, this option is enabled. You can change the setting of this option on the General tab of the Preferences dialog. For more information, see "Specifying General Preferences".
Tip:
To rename an existing map, select To Project from the File > Save As submenu.

Saving a map to a file

A map definition can be stored as text in an operating-system file, called a map definition file. A map definition file contains the complete map definition; that is, this file uses Extended Markup Language ( XML) format to represent the following parts of a map definition:

Recommendation: Map Designer creates a map definition file with a .cwm extension. You should follow a naming convention for your map definition files, such as. using the file extension (.cwm) to distinguish them.

You import a map definition into Map Designer by opening an existing map definition file. For more information, see Steps for opening a map from a file.

You can save the currently open map to a map definition file in any of the ways shown in Table 17.

Table 17. Saving a map to a map definition File

If you want to . . . Then . . .

Save the map to the name of the currently open map in the format:

MapName.cwm

(where MapName is the name of the currently open map)

Note:
Map Designer will always open the File Save dialog if you do not open the currently opened map from file.

Do one of the following:

  • Select To File from the File > Save submenu.
  • Use the keyboard shortcut of Ctrl+E.
  • In the Standard toolbar, click the Save Map to File button (see Figure 23).

Save the map to a specified map definition file. Map Designer displays a dialog box to allow you to select the file name.

Do one of the following:

  • Select To File from the File > Save As submenu.
  • Use the keyboard shortcut of Ctrl+Alt+F.

Note:
When you select the To File option from the File > Save or File > Save As menus, Map Designer displays a dialog box to allow you to select the file name. This file name identifies the file. It is not necessarily the name of the map.

Example: You can save MapA in a file named fileA.cwm. This fileA file contains the map definition for MapA. When Map Designer opens the fileA map definition file, it displays the MapA map definition.

Tip: Exporting a map copies only the map.

Checking completion

When you are mapping two large business objects, it is easy to overlook some required attributes. You can search for attributes that are not yet mapped to make sure that you have specified all desired transformations. Such attributes are called unlinked attributes.

Perform the following step to check completion:

Note:
Once the code is completed, you must compile and test it. For information on compiling a map, see "Compiling a map". For information on testing a map, see "Testing maps"..

Copyright IBM Corp. 1997, 2004