Maintenance and migration considerations for Management Center

Before you customize Management Center, consider how WebSphere Commerce will apply maintenance or upgrades to a later release of WebSphere Commerce. By following the correct approach, you can ensure that you will not lose any of your customizations when upgrading to a later release.

Customization best practices

Before you customize Management Center, ensure that your customization applies the following best practices so that the customizations will be migrated correctly:

Refer to the customization tutorials. These tutorials provide example customization scenarios that help you further understand the Management Center framework.
Use the documented OpenLaszlo API classes only for the Management Center framework; do not use classes that are marked private. Do not change restricted API files. For more information about the OpenLaszlo source files, see OpenLaszlo API.
Do not change restricted Management Center definition files. For more information about Management Center definition files, see Management Center definitions.
Always use WebSphere Commerce Developer for development. This development environment is designed to make your customization and future migration easier. Applications developed using other tools cannot be maintained or migrated properly.
Always use designed extension points. The OpenLaszlo API classes include these extension points. For more information about these extension points, see Predefined extension points.
Always follow the recommended deployment procedure. In particular, when you deploy, ensure that you export the entire WAR file from the LOBTools project, including all source code, since the entire ManagementCenter.swf file must be recompiled when maintaining or upgrading.

OpenLaszlo source files

The OpenLaszlo source files used with Management Center fall into two groups: restricted files and customizable files. Consider the type of files you change when you customize Management Center:

Restricted files

Restricted files contain class definitions for the basic functionality that is common to all tools within Management Center. Since files within the restricted directories are replaced when you install WebSphere Commerce fixes, or migrate to the next release, do not change these files when customizing Management Center.

Restricted files can be replaced in a WebSphere Commerce fix pack. If you store your development workspace files in a source control management system, ensure you synchronize your workspace with your source control management system after applying a fix pack.

Customizable files

Customizable files describe the objects within a Management Center tool and how to display them. When you install WebSphere Commerce fixes, or migrate to the next release, your customization is maintained in these files. You can use, extend, or change the classes within customizable files when customizing Management Center.

Clearly separate your code from the base IBM code. If you create new classes, place them in your own file to avoid complicating the migration process.

Avoid moving instances of a class from one parent to another. Changing parents is treated as adding and deleting, and there is no method to associate the two. The instances under the new parent are treated as your custom assets. No WebSphere Commerce fixes or enhancements will be applied to them.

Avoid deleting IBM code. Classes in search definitions and object definitions do not affect anything if you do not call them. This means that if you install WebSphere Commerce fixes, or migrate to the next release, you automatically receive the updated classes. Likewise, most Management Center widgets can be hidden from the Management Center user interface so that a business user does not see them. This is done by changing the visibility flag to false. Similar to classes for search definitions and object definitions, if you leave these in place, you will receive enhancements when applying fixes or migrating.

If the classes within OpenLaszlo files do not already include the following tags, avoid adding these tags to the classes when you customize them:

method
handler
setter
state
attribute

Using these tags in your customization might introduce migration issues.

Definition files

The definition files used with Management Center fall into two groups: restricted files and customizable files. Consider the type of files you change when you customize Management Center:

Restricted files: A small number of definition files are identified as restricted definition files and contain definitions that you cannot customize. Since files within the restricted directories can be replaced when you install WebSphere Commerce fixes, or migrate to the next release, do not change these files when customizing Management Center.
Restricted files can be replaced in a WebSphere Commerce fix pack. If you store your development workspace files in a source control management system, ensure you synchronize your workspace with your source control management system after applying a fix pack.
Customizable files: Customizable files (those that are not found in restricted directories) contain definitions that can be changed. When you install WebSphere Commerce fixes, or migrate to the next release, your customizations are maintained in these files.
Clearly separate your code from the base IBM code. If you create new definitions, place them in your own file to avoid complicating the migration process.

Predefined extension points

There are two kinds of customization assets: files you can directly change, and configuration files that you can create at predefined customization locations.

Files that you can directly change

You can change any of the following files:

.LZX files that are not contained within a restricted directory.
Definition files within the WCDE_installdir\LOBTools\WebContent\config directory that are not contained within a restricted directory.
The struts-extension.xml file within the WCDE_installdir\LOBTools\WebContent\WEB-INF directory.

Files that you can create

You can create files at predefined customization locations. At runtime, your configuration is merged with the configuration predefined by IBM. Your configuration takes precedence. You can create any of the following files:


File	Location
wc-objectrelational-metadata.xml	`WC_installdir`/xml/config/com.ibm.commerce.`component`-ext
wc-business-object-mediator.xml	`WC_installdir`/xml/config/com.ibm.commerce.`component`-ext
get-data-config.xml	`WCDE_installdir`\LOBTools\WebContent\WEB-INF\config\com.ibm.commerce.`component`-ext
wc-`component`-clientobjects.xml	`WCDE_installdir`\LOBTools\WebContent\WEB-INF\config\com.ibm.commerce.`component`-ext

OpenLaszlo example customization

The following code snippets provide an example of a customization done improperly and explanations on why.

Here is the original IBM code:

<wcfPropertyPane>
	<wcfPropertyGroup collapsable="false">
		<wcfPropertyInputText propertyName="name" required="true" 
			promptText="${mktMarketingResources.name.string}" />
		<wcfPropertyInputText propertyName="owner" 
			promptText="${mktMarketingResources.owner.string}" 
			helpText="${mktMarketingResources.help_campaign_owner.string}"/>
	</wcfPropertyGroup>
</wcfPropertyPane>

In this original code, there is an instance of wcfPropertyPane, with an instance of wcfPropertyGroup (containing several input text widgets), within it.

Here is the customized version:

<class name="myPropertyGroup" extends="wcfPropertyGroup" collapsable="false">
	<wcfPropertyInputText propertyName="name" required="true" 
		promptText="${mktMarketingResources.name.string}" />
	<wcfPropertyInputText propertyName="owner" 
		promptText="${mktMarketingResources.owner.string}" 
		helpText="${mktMarketingResources.help_campaign_owner.string}"/>
</class>

In the customized version, the code has been changed to accomplish the same task, but it is coded poorly. The code defines a class that extends wcfPropertyPane, and the input text widgets are placed here.

In addition, the customized code includes:

<wcfPropertyPane>
	<myPropertyGroup />
</wcfPropertyPane>

wcfPropertyPane was updated to use an instance of the customized class.

This customized code complicates migration. If IBM needs to update the input text widgets, the migration tooling used to compare the differences between the files cannot associate the original input text widgets with the customized ones. The classes should not be changed; instead, customize (by adding or changing) the input text widgets within the existing instance of wcfPropertyGroup.

Definition file example customization

The following code snippets provide an example of a definition file customization done improperly and explanations on why.

Here is the original IBM code:

<PropertyPane>
   <PropertyGroup groupTitle="${mktMarketingResources.campaignProperties}"
         hideHeaderWhenOnlyGroup="true" name="group" open="true">
      <PropertyInputText helpText="${mktMarketingResources.help_campaign_name}"
            promptText="${mktMarketingResources.objectName}" propertyName="name"
            required="true"/>
      <PropertyInputText helpText="${mktMarketingResources.help_campaign_owner}"
            promptText="${mktMarketingResources.owner}" propertyName="owner"/>
   </PropertyGroup>
</PropertyPane>

In this original code, there is an instance of wcfPropertyPane, with an instance of wcfPropertyGroup (containing several input text widgets), within it.

Here is the customized version:

<PropertyGroup definitionName="myPropertyGroup"
      groupTitle="${mktMarketingResources.campaignProperties}"
      hideHeaderWhenOnlyGroup="true" name="group" open="true">
   <PropertyInputText helpText="${mktMarketingResources.help_campaign_name}"
         promptText="${mktMarketingResources.objectName}" propertyName="name"
         required="true"/>
   <PropertyInputText helpText="${mktMarketingResources.help_campaign_owner}"
         promptText="${mktMarketingResources.owner}" propertyName="owner"/>
</PropertyGroup>

In the customized version, the code has been changed to accomplish the same task, but it is coded poorly. The code defines a new definition that extends wcfPropertyGroup, and the input text widgets are placed here.

In addition, the original property pane has been changed to refer to the new definition:

<PropertyPane>
	<PropertyGroup baseDefinitionName="myPropertyGroup"/>
</PropertyPane>

This customized code complicates migration. If IBM needs to update the input text widgets, the migration tooling used to compare the differences between the files cannot associate the original input text widgets with the customized ones. The definitions should not be changed; instead, customize (by adding or changing) the input text widgets within the existing instance of wcfPropertyGroup.