Management Center customization best practices and modeling guidelines

To customize Management Center, you can change some files that are provided by WebSphere Commerce and create your own custom configuration files to define custom objects or features for your store. Before you begin customizing Management Center, consider how WebSphere Commerce provided maintenance fixes or upgrades can affect your custom objects and changes. By following the correct customization approach, you can ensure that fixes and upgrades do not overwrite your customizations when you install a maintenance fix or upgrade to a later release.

Best practices

Ensure that your planned customization follows these best practices:

Use only the Management Center classes that are documented when you are customizing Management Center. Do not use classes that are marked private and do not change restricted files.
Always use IBM WebSphere Commerce Developer for development. This development environment is designed to make your customization and future migration easier. Applications that you develop with other tools cannot be maintained or migrated properly.
Always use designed extension points. The documented Management Center classes include these extension points.
Always follow the recommended deployment procedure. For more information, see WebSphere Commerce Build and Deployment tool.
When you are customizing Management Center, you can directly change any of the following files that are provided by WebSphere Commerce:
- All of the definition XML files that are in the WCDE_installdir\LOBTools\WebContent\WEB-INF\src\xml directory. Do not add or modify files within a restricted directory.
- The spring-extension.xml file within the WCDE_installdir\LOBTools\WebContent\WEB-INF directory.
For the restricted files that you are not to change, you can create custom versions of any of the files within your own custom directories. At run time, your custom files are merged with the files that are provided by WebSphere Commerce. The configurations or definitions in your custom files takes precedence.
Keep a consistent directory structure if you plan to migrate to a later release or require assistance from IBM support with your customizations. When you add files to the Management Center framework, follow the same directory structure as the default files that are provided, with the following exceptions:
- Use your own company name for the commerce directory in your directory structure. For example, instead of using the workspace_dir\LOBTools\WebContent\WEB-INF\src\xml\commerce\component directory structure, use workspace_dir\LOBTools\WebContent\WEB-INF\src\xml\mycompany\component
- You do not need a restricted directory in your mycompany directory structure. The restricted directories that are within the commerce directory indicate directories that are replaced when you install WebSphere Commerce fixes or when you migrate to a later release.
  Note: If you use a source control management system to store files, do not check file that are in restricted directories into your source control management system.

Tip: To help you better understand how to customize Management Center, follow the provided Management Center customization tutorials. These tutorials provide example customization scenarios for customizing the Management Center framework. For more information, see Management Center customization tutorials.

Definition file modeling guidelines

Management Center definition files can be restricted or customizable.

Restricted files

Restricted files include class definitions for the basic functionality that is common to all tools within Management Center. Since these restricted files can be replaced when you install maintenance fixes or upgrade WebSphere Commerce, do not change these files.

Customizable files

Customizable files describe the objects that are managed within a Management Center tool and defines how to display the objects. When you install maintenance fixes or upgrade WebSphere Commerce, your customization files are maintained. You can use, extend, or change the classes within customizable files when you are customizing Management Center. When you are working with customizable files, follow these guidelines:

Notes:

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.
Do not move instances of a class from one parent class to another parent class. Changing the parent class for a class is considered adding and deleting a parent. There is no method to associate the two operations. The instances of a class under the new parent are considered to be custom assets and they are not updated when you apply maintenance or upgrade WebSphere Commerce.
Do not delete IBM code. Classes in search definitions and object definitions do not affect anything if you do not call the classes. When you apply maintenance fixes or upgrade WebSphere Commerce, you automatically receive the updated classes. You can hide most Management Center widgets from displaying in the user interface when a widget is not needed by changing the visibility flag for the widget to false.
If a definition file does not include the following elements, avoid introducing the elements into the file. By adding these elements to the file, you might encounter problems when you apply maintenance or upgrade WebSphere Commerce.
- <method>
- <handler>

Note: If you add or change definition files in the workspace_dir\LOBTools\WebContent\WEB-INF\src\xml directory, you do not need to restart your WebSphere Commerce server. The new definitions are automatically detected by the AMD module servlet by checking the last modified data of the definition files. You do need to restart Management Center by closing the Management Center browser window and clearing the browser cache.

You can use object paths in definitions to instruct the Management Center framework to search through child objects of a selected object to locate an object to use. An object path is a list of object types that are separated by a forward slash "/". The framework searches recursively for the child objects that match the specified object types. As an example, the object path objectPath="CatentryDescription" causes Management Center to search the current object for a child object with an object type that matches "CatentryDescription". Any of the object types in an object path can be replaced by an object group. For example, if a Catentry object group is defined to include the object types Product, Bundle, Kit, or SKU, then the object path of Catentry matches objects with the object type of Product, Bundle, Kit, or SKU. Object types in an object path can be qualified with a property name and value by using Xpath-like syntax, such as [prop=value]. The following Management Center classes accept object paths:

cmc/foundation/ChildListEditor
cmc/foundation/GridCellDescriptor
cmc/foundation/GridColumn
cmc/foundation/ObjectPathFilter
cmc/foundation/ObjectPropertyFilter
cmc/foundation/PreviewFileClientAction
cmc/foundation/PropertiesComponent
cmc/foundation/PropertyValuesFilter
cmc/foundation/NumericPropertyComparator
cmc/foundation/RequiredChildObjectValidator
cmc/foundation/RequiredSpecificValueForChildObjectPropertyValidator
cmc/foundation/UniqueValueForChildObjectPropertyValidator
cmc/foundation/ValueResolver

Business object editor modeling guidleines

The Business Object Editor, cmc/foundation/BusinessObjectEditor, class is the base class for all Management Center tools. The Business Object Editor includes support for the Management Center menu, toolbar, search widget, explorer view, and utilities view. This editor is responsible for managing all user interactions that allow the user to edit the business objects that are declared with the editor. Do not instantiate instances of this class directly. Register instances of this class by adding an instance of "cmc/foundation/ApplicationMenu" to "cmc/foundation/ApplicationMenuItems".

Creating an instance of the Business Object Editor class primarily involves declaring the objects that are to be authored (that is, created, changed, or removed). To ensure that the Business Object Editor can consume object definitions and provide an effective authoring tool for different object domains, the objects must be declared consistently. To create a business object model that can be successfully consumed by the Business Object Editor, follow these guidelines:

Include a top object definition within the declaration of the business object editor. The top object definition describes the root object of the explorer tree. The top object is a client-side organizational object that is not returned by a service call. The top object is not visible, but its children display as top-level explorer tree nodes below the Active Work node. When the top object instance is instantiated, any child objects that are declared as part of the object definition template are created. In addition, any declared instances of the GetChildrenService class are invoked to retrieve more child objects from the WebSphere Commerce server.
If one or more top-level explorer tree nodes are required as organizational elements, they must be declared as organizational object definitions. They can be instantiated only as elements of another object definition’s template declaration.
All business object types that can be created, updated, or deleted must be declared as primary object definitions or as child object definitions of a primary object definition.
If a business object only exists within the context of another object and cannot be referenced or searched for without searching for its parent, that object type must be declared as a child object definition in a primary object definition or in another child object definition.
Primary business objects must not have another primary business object as a direct child. An intermediate object, which is called a reference object, is required to describe the nature of the relationship between the two primary objects. This intermediate object type must be declared as a reference object definition.
All business objects are made up of a list of uniquely named simple properties. If an object contains a variable list of similar child properties, that property must be modeled as a separate child object type.
A business object must be uniquely identifiable by the value of one of the properties (identified as the ID property). The ID value of objects that are described by child object definitions or reference object definitions are only required to be unique within the set of objects that have the same parent. Primary objects of the same type must all have a unique ID value.
All primary objects must have a display identifier as the value of one of the object's properties (identified as the display name property). Any object definition can declare a displayNameProperty, but it is only required for primary objects. This display name is used as the text on a user interface widget that represents object instance. While it is preferred, there is no requirement for this value to be unique. Avoid translatable properties when you are choosing the display name property.
If two business objects require different properties view declarations, they must be modeled as two separate object types. Model products and SKUs as different object types, not as a single object type for catalog entries.

Extended site store modeling guidelines

If your store uses extended sites stores, ensure that your tool is modeled to support extended sites, by following these guidelines:

Objects within an extended sites-enabled tool can be local or inherited. A local object is an object that is owned by the currently selected store and an inherited object is an object that is owned by a referenced asset store. To distinguish between local and inherited objects, the Management Center requires two object definitions - one for the local object and one for the inherited object. Since local primary business objects and inherited primary business objects are modeled as two separate object definitions in the extended sites store, you must duplicate all object definitions that are inherited from your asset store.
If you are creating a base object definition to create a common ancestor for all object types, set both the base and inherited object definitions to createable="false" so that the user interface prevents you from creating objects of that type.
If you are modeling object definitions for extended sites objects that are managed with a Management Center a tool, follow these guidelines:
- Move all store-dependent object definitions to a base definition and name the objectType baseABC. To determine whether a property is store-dependent, consider whether it needs to be overridden at the extended site level. For example, product descriptions are currently store-independent, which means that every store that has access to a product sees the same product description. You can customize WebSphere Commerce to make the product description store-dependent by moving the object definition for the product description into the base definition.
  Note: The underlying schema must also support store-dependent properties. For example, since the current database table that stores merchandising associations (MASSOCCECE) includes a column for the store ID, products can have different merchandising associations in different stores. You can also track a store-specific merchandising association for a product.
- Duplicate all reference business object definitions for the references that are store-dependent and clearly mark them as inherited objects. Name the objectType of the inherited reference object definitions to indicate that they are inherited. When you are creating this type of object, determine whether the reference itself needs to be store-dependent.
  For example, a merchandising association is a reference business object that creates a reference between a source product and a target product. If both the source product and the target product are from an asset store, you need to determine whether the user needs to create a merchandising association on the asset store or on an extended site that inherits from that asset store. In the first case, all extended sites that inherit from that asset store has the merchandising association. In the second case, only the extended site on which the merchandising association was created has the merchandising association. To support both of these scenarios, the merchandising association reference business object must be store-dependent.
- Set compatibleObjectTypes to the objectType of the extended site store business object. When the object is copied, the newly created object is marked as an extended site store business object as opposed to an inherited business object.
```

<PrimaryObjectDefinition baseDefinition="cmc/catalog/BaseKitPrimaryObjectDefinition" 
  compatibleObjectTypes="Kit" 
  definitionName="cmc/catalog/InheritedKit" displayName="${catalogResources.inheritedKit_DisplayName}" 
  headerIcon="inheritedKitHeaderIcon" icon="inheritedKitIcon" 
  objectType="InheritedKit">
<dependency localName="catalogResources" moduleName="cmc/catalog/CatalogResources"/>
```
- Add a false enablement condition element as a child of your inherited primary business objects.
```

<EnablementOrCondition baseDefinition="cmc/catalog/StoreTypeCatalogObjectCreationRestriction"/>
```
  Typically, inherited objects cannot be created by the framework. However, there are two exceptions. Although you can create inherited merchandising associations and prices in the extended site, both objects are reference objects, not primary objects. Inherited primary objects are never created in the extended site. In addition, inherited objects cannot have enablement conditions, while local objects can have enablement conditions. Define an enablement condition with the list of storeTypes where the creation of these objects is allowed. Use this attribute for primary business objects in extended sites that need to prevent creating and copying objects by store type.
- Update the response JSP page to return the object store ID if you created your own inherited object and want users to be able to create the object at the asset store level when they are logged in to an extended sites store.
  When you invoke the create service, the Management Center user interface invokes a create request and the appropriate response JSP page creates the response for the request. This response contains the information that is related to the result of the request, including any changed information that the Management Center requires as a result of the request. When the object is inherited from the asset store, you must add the following line to the response JSP to return the objectStoreId: <objectStoreId>.{param.storeID}</objectStoreId>
- Declare the create service only in the local object definition to prevent the inherited object from being created.
```

<CreateService sendDefaultLanguageProperties="true" url="/cmc/CreateCatalogGroup">
  <ServiceParam name="storeId"/>
  <ServiceParam name="masterCatalogId"/>
  <ServiceParam name="defaultLanguageId" parameterName="languageId"/>
  <ServiceParam name="isTopCategoryTrue" optional="false" parameterName="isTopCategory" value="true">
    <EnablementCondition checkObjectDefinition="true" conditionId="objectTypeCondition" 
     enablementValue="CatalogAlias" parentProperty="true" propertyName="objectGroups"/>
  </ServiceParam>
  <ServiceParam name="isTopCategoryFalse" optional="false" parameterName="isTopCategory" value="false">
    <EnablementCondition checkObjectDefinition="true" conditionId="objectTypeCondition" 
     enablementValue="CatalogAlias" negate="true" parentProperty="true" propertyName="objectGroups"/>
  </ServiceParam>
  <ServiceParam name="catalogId" optional="false" parentProperty="true" parentType="CatalogAlias" propertyName="catalogId"/>
  <ServiceParam name="catalogIdentifier" optional="true" parentProperty="true" parentType="CatalogAlias" propertyName="identifier"/>
</CreateService>
```

language-sensitive objects modeling guidelines

Language-sensitive objects are business objects that contain translatable information. Translatable information is information that can be translated into multiple languages. For example, product names and descriptions that are offered in multiple languages are language-sensitive objects.

Model translatable information with instances of the ChildObjectDefinition class definition that has the languageSensitive attribute set to true. Language-sensitive object definitions must set the idProperty to languageId. The Management Center framework uses the value of the languageId property to determine which language to load.

If a business user selects multiple input languages from the Select Input Language dialog, the Management Center framework loads and creates instances of the language-sensitive objects, as required.

Resource access control

Some objects that are loaded by the Management Center framework should not be edited by a business user. Mark these objects as read-only by adding readonly="true" to the serialized object. For example, active promotions can be viewed, but cannot be changed by business users.

The read-only state of a child object is inherited from its parent object, but you can override this inheritance if the child object has a different read-only state from its parent. Primary objects do not inherit the read-only state of the reference objects that reference them.