Predefined properties for transformations

When you create a transformation, you can enable features or set values for properties by defining the corresponding property in the plugin.xml file of the plug-in that contains the transformation. Depending on how frequently the value changes, you can also update properties in the transformation context by using the transformation application programming interface (API).

The transformation core defines several properties. You can create and set the value for a property in the following ways:

In the plugin.xml file of the project that contains the transformation, you can add the property and set its values as described in the table at the end of this topic.
You might use this method if the value of the property does not change often.

For some properties, you create a <Property> element in the <Transformation> element; for others, you add the property as an attribute in the <Transformation> element. See the following table for more information.
The following code fragment shows how to add a property named myProperty by creating a <Property> element in the <Transformation> element:
```
<Transformation
	groupPath="myExampleTransformation"
	id="myExampleTransformation.transformation"
	name="Transformation"
	sourceModelType="UML2"
	targetModelType="resource"
	version="1.0.0"/>
	<Property
		readonly="true"
		metatype="boolean"
		name="myProperty"
		value="true"
		id="myProperty">
	</Property>
</Transformation>
```
You must specify a value for the name attribute. The value that you specify should be descriptive enough so that the purpose of the attribute is obvious to users. For example, if the identifier, or id attribute of the property is set to my.transformation.myApp.myTransformation.mergeOption, you might set the name attribute to "Merge Option".
In the source code of a transformation, within a transformation element such as a rule, extractor, or transform, you can add code that invokes the methods of the com.ibm.xtools.transform.core.ITransformContext interface.
You might use this method if the value of a property changes often.

For more information about this interface and a description of the transformation context, see the Rational® Transformation Developer Guide.

Setting the value of a Boolean property to false is equivalent to omitting that property from the plugin.xml file.

The following table lists the predefined properties that you can update for a transformation. As a transformation author, you can also create custom properties for a transformation; see the related task topic at the end of this topic.

Property ID	Characteristics and Description	Location
createSourceToTargetRelationships	Metatype: Boolean Value: By default, the value of this property is set to `true` Read-only: `false` This property specifies that the transformation supports creating trace relationships from the source elements to the target elements. Set this property to `true` to display a check box on the Main page of the transformation configuration editor. A transformation user selects this check box to specify that this instance of the transformation creates trace relationships.	In the plug-in.xml file of the transformation, create a `<Property>` element in a `<Transformation>` element, as shown in the code fragment at the beginning of this topic.
MAIN_TAB_CSHELP	Metatype: String Value: The identifier (ID) of the plug-in that contributes the configuration page to embed in the Main page of the transformation configuration editor, followed by the context ID of the context-sensitive help, as in the following example: `com.myCompany.myTransformation.cshelpID` Read-only: `true` This property specifies information that the transformation core uses to display context-sensitive help for pages that are embedded in the Main page of the transformation configuration editor. To provide context-sensitive help for a configuration page that is embedded in the Main page, a transformation author must set the value of this property.
PROGRESS_MONITOR_INCREMENT	Metatype: Positive integer Value: Defined by the transformation author Read-only: See the description in the Location column. This property specifies the number of work units to increment the progress bar of the progress window.	If the value of this property does not change when the transformation runs, you can specify this property and its value in the plugin.xml file of the project that contains the transformation, and set its `readonly` attribute to `true`. If the value of this property changes often when a transformation runs, you can specify and update its value by invoking the setPropertyValue method in the com.ibm.xtools.transform.core.ITransformContext interface. See the information in the Location column of the PROGRESS_MONITOR_TASK_NAME property. If you use this method to update the property, you do not have to specify it in the plugin.xml file.
PROGRESS_MONITOR_TASK_NAME	Metatype: String Value: Defined by the transformation author Read-only: `false` This property specifies the text that displays below the progress bar in the progress window. The value that you specify should be descriptive enough so that the purpose of the attribute is obvious to users, as in the following example: "Processing classes in the source model".	A transformation element such as a rule, extractor, or transform sets this context variable before the transform runs an instance of the com.ibm.xtools.transform.core.UpdateProgressMonitorRule rule, as in the following example: private AbstractTransform createClassTransform(ITransformationDescriptor desc) { Transform classTransform = new Transform(desc); // Add the transform elements that read the source classes. // One of these elements must set the following transform // context variables by invoking the setPropertyValue method in the //com.ibm.xtools.transform.core.ITransformContext interface: // -PROGRESS_MONITOR_INCREMENT // -PROGRESS_MONITOR_TASK_NAME // Add the rule to update the progress monitor. classTransform.add(new UpdateProgressMonitorRule("myRuleId", "myRuleName")); return classTransform; }
PROGRESS_MONITOR_WORK_UNITS	Metatype: Positive integer Value: Defined by the transformation author Read-only: `true` This property specifies that the transformation, and not the transformation core, updates the progress bar in the progress window while the transformation runs. The value of this property indicates the number of work units in the transformation. To determine a value for this property, you might use one of the following methods: Determine the number of files that the transformation generates, and at various locations in the transformation code, update the progress bar with the number of work units divided by the number of files that the transformation has generated. Select a positive integer, and allocate some work units to parse the transformation source, and the remaining work units to generate the target artifacts. When each task is complete, update the progress bar with the percentage of completed work units. For more information about updating the progress bar, see the related task topic at the end of this topic.	In the plug-in.xml file of the transformation, create a `<Property>` element in a `<Transformation>` element, as shown in the code fragment at the beginning of this topic.
replaceUML	Metatype: Boolean Value: By default, this property is set to `true` Read-only: `true` This property specifies whether the transformation supports the utility named "Replace UML elements." Set this property to `true` to display the Mixed Modeling protocol as an option in the transformation configuration editor or wizard.
supportsSilentMode	Metatype: Boolean Value: By default, this property is set to `true` Read-only: `true` This property specifies whether the transformation can run in silent mode, which means that when the transformation runs, the transformation user is not prompted for information that affects its output. Set this property to `true` to display a check box on the Main page of the transformation configuration editor. A transformation user selects this check box to run the transformation in silent mode.	Add these properties to a `<Transformation>` element in the plugin.xml file, as in the following example: `<Transformation ... supportsSilentMode="true" supportsSourceOverride="false" targetModelType="resource" version="1.0.0/> ... </Transformation>`
supportsSourceOverride	Metatype: Boolean Value: By default, this property is set to `true` Read-only: `true` This property specifies whether the transformation supports overriding the transformation source that a user specifies in a transformation configuration. Set this property to `true` to enable pop-up menus that provide additional options for running this instance of the transformation. If a transformation user overrides the transformation source by right-clicking the object that represents the transformation source in the Project Explorer view or a UML diagram, the Eclipse workbench displays the pop-up menus.
usesMapping	Metatype: Boolean Value: By default, this property is set to `true` Read-only: `true` This property specifies whether the transformation uses the transformation mapping utility. Set this property to `true` to display the Mapping page in the transformation configuration editor. By displaying this page, transformation users can create and edit mapping models.	In the plug-in.xml file of the transformation, create a `<Property>` element in a `<Transformation>` element, as shown in the code fragment at the beginning of this topic.
usesReporting	Metatype: Boolean Value: By default, this property is set to `true` Read-only: `true` This property specifies whether the transformation reports issues in the error log by using the reporting tool. Set this property to `true` to display the following options on the Main page of the transformation configuration editor: Open the Report dialog box when the transformation is complete Show warnings in the Report dialog box The first option specifies whether the transformation opens a window that displays the problems that occurred when the transformation ran. The second option specifies whether the transformation shows warnings in the Report dialog box; by default, the window displays only errors.

Feedback