Defining server-side error messages for validation errors

When server validation fails for a Management Center object, you can display an error message to provide more details about the error to users. To display the server-side error message, you must create or change the validation error mapping by defining error reason codes for the validation errors that can occur for a Management Center object. You can then define an error message for the reason codes to provide users with details about the validation errors and potential solutions.

About this task

If a request cannot be processed because of business logic validation errors, the BOD response contains error information in the change status element of the verb. The change status contains a reason code element that consists of a unique string that represents the application error. In most cases, these unique reason codes correspond to the property of a Management Center object. By creating or updating the validation error mapping, each Management Center object property that is validated can be associated with an error reason codes. By associating error response with particular properties, the messages that display when a validation error occurs can better indicate the properties that are causing errors.

Procedure

  1. Open IBM WebSphere Commerce Developer.
  2. In the Enterprise Explorer view, expand LOBTools > WebContent > WEB-INF > config > com.mycompany.commerce.component-ext, where mycompany is the name of your company and component is the name of the component for the object that you want to map to an error code.
    If the com.mycompany.commerce.component-ext directory does not exist, you must create this directory.
  3. Open your custom wc-component-clientobjects-ext.xml configuration file for the component. If the file does not exist, you must create the file. Use the file that is provided by WebSphere Commerce for the component as a model for creating your file.
    Note: If you are creating a custom wc-component-clientobjects-ext.xml, register the file within the Spring framework. The spring-extension.xml file is the extension point for the Spring framework in WebSphere Commerce. To use your new validation error mapping, your file must be registered within this file.
    1. Expand LOBTools > WebContent > WEB-INF.
    2. Open the spring-extension.xml file for editing.
    3. Add a bean definition to include your custom file. Include the definition within a <bean> element within the top-level <beans> element. Your configuration can resemble the following code snippet.
      
<bean class="com.ibm.commerce.foundation.client.facade.bod.servlet.spring.BusinessObjectDocumentConfiguration">
  <property name="config" value="/WEB-INF/config/com.mycompany.commerce.component/wc-component-clientobjects.xml" />
</bean>
  4. In the error definition configuration section of the file, identify the error configuration for the object. If the configuration for the object does not exist, create the configuration. Use the configuration in the file that is provided by WebSphere Commerce as a template.
    The error definitions for an object must be included within an <_config:ErrorGroup element within the parent <_config:ErrorDefinition element.
    For example, the following code snippet shows the error definitions for the catalog identifier property and catalog entry partnumber property. 
    
<_config:ErrorDefinitions
  primaryResourceBundle="com.ibm.commerce.catalog.client.lobtools.properties.CatalogLOBErrorMessages"
  alternateResourceBundle="extensions.com.ibm.commerce.catalog.client.lobtools.properties.CatalogLOBErrorMessages">
	
  <_config:ErrorGroup name="Catalog">		
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATALOG_MISSING_IDENTIFIER"
      parameterName="identifier" />
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_DELETE_OR_UPDATE_NON_EXIST_CATALOG"
      parameterName="identifier" />
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATALOG_DELETE_WITH_TOP_CATEGORY"
      parameterName="identifier" />
  </_config:ErrorGroup>
		
  <_config:ErrorGroup name="CatalogEntry">
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATENTRY_DUPLICATE_EXTERNAL_IDENTIFIER_FOR_CHANGE"
      parameterName="partnumber" />		
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATENTRY_DUPLICATE_PART_NUMBER_FOR_CATENTRY_CREATE"
      parameterName="partnumber" />
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATENTRY_MISSING_PART_NUMBER_FOR_CHANGE"
      parameterName="partnumber" />
    <_config:ReasonCodeParameterAssociation
      reasonCode="_ERR_CATENTRY_MISSING_PART_NUMBER_FOR_CREATE"
      parameterName="partnumber" />
  </_config:ErrorGroup>	
</_config:ErrorDefinitions>
  5. Add or change the ReasonCodeMapping element for the object property to identify the service reason code to associate with the property.
    If you are adding a reason code, use a <_config:ReasonCodeParameterAssociation> element to define the reason code.
    • The value for the reasonCode attribute must be the same as the key for the error message text that you add to your custom properties file.
    • The value for the parameterName attribute must be the same as the value for the propertyName attribute for the property in the object defintion file.
  6. If your reason code does not map to an existing error message, define the error message for the validation code.
    1. Expand LOBTools > Java Resources > src > com.mycompany.component.client.lobtools.properties. If this directory does not exist, create the directory.
    2. Open your custom componentLOBErrorMessages.properties and componentLOBErrorMessages_locale.properties files for editing, where locale is the language code, such as en_US. If these files do not exist, create the files.
      The file name for the base componentLOBErrorMessages.properties file must match the name of the file that is configured as the resource bundle or alternate resource bundle within your custom wc-component-clientobjects-ext.xml file.
    3. Add the properties file entry for the validation error reason code. Use the format reasonCode=messageText.
      For example, the entry for the "_ERR_CATENTRY_DUPLICATE_EXTERNAL_IDENTIFIER_FOR_CHANGE" reason code resembles the following properties file entry.
      CatalogEntry._ERR_CATENTRY_DUPLICATE_EXTERNAL_IDENTIFIER_FOR_CHANGE=The specified code is already in use. Type in a new catalog entry code.
    4. Save and close the files.