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
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.
- .LZX files that are not contained within a
- 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.<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.<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.
<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.<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.<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.<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.