Table 13 provides an overview of the 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 Express. | 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 |
Map Designer Express 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:
Result: Map Designer Express displays the first window of the New Map wizard.
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.
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.
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 Express 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.
Result: Map Designer Express displays the new map's information in its Diagram tab.
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.
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.
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.
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.
From the Diagram tab, you can add a source or destination business object to a map. Perform the following steps to do this:
Figure 15 shows the source and destination business objects in the map workspace.
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 Express 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:
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 15), 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.
You can specify several standard attribute transformations interactively in Map Designer Express while writing little or no Java code. Table 14 shows the standard transformations that you can specify in Map Designer Express.
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:
|
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.
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 16.
Steps for specifying a Set Value transformationPerform the following steps to specify a Set Value transformation:
Result: Map Designer Express opens Activity Editor in Java view, containing a sample of the transformation code in read-only mode for the destination attribute. To make changes to the transformation code, click Edit Code in Activity Editor. For more information, see Overview of Activity Editor.
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 transformationPerform the steps from one of these map tabs to specify a Move transformation:
Result: Map Designer Express creates a blue arrow from the source to the destination object. If the transformation involves a single source attribute that is not a child business object, Map Designer Express assumes that the transformation is a Move and automatically assigns Move to the Rule column of the destination attribute.
Tip: You can customize the key sequence used to initiate a Move transformation in the Diagram tab from the Key Mapping tab of the Preferences dialog. For more information, see Specifying Key Mapping.
Result: Map Designer Express 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 Express 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 Express 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.
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.
You join multiple source attributes into one destination attribute with the Join dialog, shown in Figure 17.
Steps for specifying a Join transformationPerform the following steps to specify a Join transformation:
Tip: You can click Multiple Attributes in the combo box to display the Multiple Attributes dialog. In this dialog, you can select multiple source attributes. To locate a particular business object, enter its name in the Find field. The up and down arrows scroll through the business object list. Once you have selected the source attributes, click OK to close the dialog.
Result: If the transformation involves more than one source attribute, Map Designer Express assumes that the transformation is a Join. It automatically assigns Join to the Rule column of the destination attribute and displays the Join dialog.
Tip: You can customize the key sequence used to initiate a Join transformation in the Diagram tab from the Key Mapping tab of the Preferences dialog. For more information, see Specifying Key Mapping.
Result: Map Designer Express opens Activity Editor in Java view, containing a sample of the transformation code in read-only mode for the destination attribute. To make changes to the transformation code, click Edit Code in Activity Editor. For more information, see Overview of Activity Editor.
Result: Map Designer Express generates the code to join the source attributes. If any source attribute is of a different data type from the destination attribute, Map Designer Express makes the necessary calls to methods in the DtpDataConversion class to convert the types.
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 18.
Steps for specifying a Split transformationPerform the following steps to specify a Split transformation:
Result: If the transformation involves more than one destination attribute, Map Designer Express assumes that the transformation is a Split. It automatically assigns Split to the Rule column of the destination attribute and displays the Split dialog.
Tip: You can customize the key sequence used to initiate a Split transformation in the Diagram tab from the Key Mapping tab of the Preferences dialog. For more information, see Specifying Key Mapping.
Result: Map Designer Express opens Activity Editor in Java view, containing a sample of the transformation code in read-only mode for the destination attribute. To make changes to the transformation code, click Edit Code in Activity Editor. For more information, see Overview of Activity Editor.
Result: Map Designer Express generates the transformation code for the destination attribute. The generated code uses methods from the DtpSplitString() class to parse the source attribute into segments.
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 submapsYou can call a submap to obtain a value for any destination attribute, but submaps are most commonly used for the following:
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 19 illustrates how a submap, MyAddrToGenAddr, can be reused by two different maps.
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 20 illustrates the use of submaps for an Employee business object and its child business array that contains instances of EmployeeAddress.
A submap can be associated with a conditional statement that governs whether it executes. For example, consider Figure 21: 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.
Some conditions that can be written in the map for Order can:
Perform the following steps to specify a Submap transformation:
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_".
You specify that a submap needs to be called with the Submap dialog, shown in Figure 22. Display the Submap dialog in one of the following ways:
If the transformation involves a source attribute that is a child business object, Map Designer Express assumes that the transformation is a Submap. It automatically assigns Submap to the Rule column of the destination attribute and displays the Submap dialog.
Tip: You can customize the key sequence used to initiate a Submap transformation in the Diagram tab from the Key Mapping tab of the Preferences dialog. For more information, see Specifying Key Mapping.
Tip: To locate a particular submap, enter its name in the Find field. The up and down arrows scroll through the business object list.
Result: Map Designer Express opens Activity Editor in Java view, containing a sample of the transformation code in read-only mode for the destination attribute. To make changes to the transformation code, click Edit Code in Activity Editor. For more information, see Overview of Activity Editor.
Result: Map Designer Express generates the Java code to call the specified submap. It automatically creates a call to the runMap() method to call the submap.
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 transformationPerform the following steps to specify a Cross-Reference transformation:
Result: The Cross-Reference dialog appears:
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.
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 Express. For more information, see Tip: Using function blocks directly in Map Designer Express.
Steps for specifying a Custom transformationPerform 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 Express displays Activity Editor with a graphical view. For more information on Activity Editor, see Overview of Activity Editor.
Table 15 lists information in this guide that is useful in defining a custom transformation.
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 Express to create the map for the business objects that contain relationships. | Creating maps |
2. | Use Relationship Designer Express to define the relationship. | Creating relationship definitions |
3. | Return to Map Designer Express 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 |
You can tell Activity Editor not to confirm by changing the setting in the Preferences dialog.
To preserve the map definition for use at a later time, you must save the map. Before Map Designer Express saves a map, it first validates the map. For more information, see Validating a map.
Map Designer Express provides two ways to save the current map:
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.
When you save the map, Map Designer Express saves the map definition and map content to the project in System Manager. It saves the map content as XML data.
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 Express 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 Express 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.
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 Express will
always open the File Save dialog if you do not open the currently opened
map from file. |
Do one of the following:
|
Save the map to a specified map definition file. Map Designer Express displays a dialog box to allow you to select the file name. |
Do one of the following: |
Example: You can save MapA in a file named fileA.cwm. This fileA file contains the map definition for MapA. When Map Designer Express opens the fileA map definition file, it displays the MapA map definition.
Tip: Exporting a map copies only the map.
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:
Result: Map Designer Express displays a list of attributes for which there is no transformation code. For more information, see Finding information in a map.