Tutorials > Contracts


Tutorial: Customizing a contract (Rebate scenario)

In this example scenario, a flat rate rebate is created. Since the advanced B2B starter store includes neither a term and condition nor a policy type that matches the rebate scenario, these must be created. Additionally, a new business policy must be created, as well as a database table to store the rebate codes.


Procedure

  1. Create the XREBATECODE database table and a corresponding XRebateCodeBean entity bean that is used to access information from this table.

    Since the existing database schema does not include the specification of a rebate amount and code, a new table must be created. In general, when a new table is created, a new entity bean is also created that is used to when accessing information contained in this table.

    For the purpose of this example, assume that the following XREBATECODE database table is created.

    XREBATECODE database table
      Column name
    REBATECODE_ID AMOUNT CURRENCY
    Sample data 201 5 CAD
    202 10 CAD

    Additionally, a new CMP entity bean (XRebateCodeBean) would be created.

  2. Create a new 5DollarRebate business policy. This includes the following sub-tasks:

    1. Create the corresponding new business policy type. This defines the interface (RebatePolicyCmd) that the new business policy command will implement.

      1. Create the new business policy type interface. This is the RebatePolicyCmd interface that the CalculateRebateCmdImpl will implement.

      2. Create the new CalculateRebateCmdImpl business policy command.

      3. Register the new business policy and business policy command in the database.

    2. Create the new CalculateRebateCmdImpl business policy command.

      Since there is not an existing business policy type that corresponds to rebates, a new one must be created. Creating a new business policy type involves defining and registering a policy type in the database. The following tables must be updated:

      For this scenario, to create the new REBATE policy type, the following SQL statements would be used: 

      insert into POLICYTYPE (POLICYTYPE_ID) values ('Rebate'); insert into PLCYTYCMIF (POLICYTYPE_ID, BUSINESSCMDIF) 
   values ('Rebate', 
   'com.mycompany.mybusinesspolicycommands.RebatePolicyCmd'); insert into  PLCYTYPDSC (POLICYTYPE_ID, LANGUAGE_ID, DESCRIPTION) 
   values ('Rebate', -1, 
   'Rebate policy type.');

      As a result, the following table shows the relevant columns of the PLCYTYCMIF table that shows the relationship between the policy type and the business policy command to which it is related.

      Updates made to the PLCYTYCMIF table
        Column name
      POLICYTYPE_ID BUSINESSCMDIF
      Sample data Rebate com.mycompany.mybusinesspolicycommands. RebatePolicyCmd

      You must also code the new RebatePolicyCmd interface. This interface must extend the com.ibm.commerce.command.BusinessPolicyCommand interface. As suggested by the previous table, package this interface into your own package.

    3. Register the new business policy command and business policy type in the database.

      To create the new business policy command, create a new command called CalculateRebateCmdImpl that extends the com.ibm.commerce.command.BusinessPolicyCommandImpl implementation class. This URL should implement the RebatePolicyCmd interface created in the previous step.

      Note that in this example, the interface name and the command name are dissimilar. These names were chosen to intentionally show that there may be many business policy commands that implement the rebate type of business policy. Each implementation (that is, each business policy command) would then implement the rebate in a unique manner.

      The logic of the command depends upon the particular implementation of how the customer is to pick up the goods. Additionally, this CalculateRebateCmdImpl should be invoked by a separate controller or task command in the application.


      Register the new business policy and new business policy command

      The new business policy must be registered in the database. You must also register the relationship between the new business policy and the new business policy command.

      To register this information, you can use the com.ibm.commerce.contract.commands.PolicyAddCmd command. The following shows an example usage of the PolicyAdd command for this scenario: 

      http://localhost:8080/webapp/wcs/stores/servlet/PolicyAdd?
   type=Rebate&name=5DollarRebate&plcyStoreId=-1
   &cmd_1=com.mycompany.mybusinesspolicycommands.CalculateRebateCmdImpl
   &startDate=2002-05-08%2000:00:00&endDate=2003-05-09%2000:00:00
   &commonProps=rebatecode_id%3D501&URL=aRedirectURL

      Note that URL reserved characters must be replaced by their ASCII codes for input properties. As such, the typical = (equals) symbol is replaced with "%3D", the & (ampersand) is replaced by "%26", and the space character is replaced by "%20". The date format used in the preceding example is yyyy-mm-dd hh:mm:ss, with ASCII code replacing URL reserved characters.

      The following tables show the relevant columns of the affected database tables, after performing the updates.

      Updates made to the POLICY table
        Column name
      POLICY _ID POLICY NAME POLICYTYPE _ID STOREENT _ID PROPERTIES
      Sample data 301 5Dollar Rebate Rebate -1 rebatecode_id= 201

      Note that it is also presumed that the start date and end date values are set to null.

      Updates made to the POLICYCMD table
        Column name
      POLICY _ID BUSINESS CMDCLASS PROPERTIES
      Sample data 301 com.mycompany. mybusinesspolicycommands. CalculateRebateCmdImpl null

      As a result, you now have a new business policy called "5DollarRebate" that is related to the CalculateRebateCmd business policy command.

  3. Create a new term and condition (RebateTC) for the rebate.

    1. Register the RebateTC term and condition in the database.

      When you are creating a new terms and condition object, update the database schema to include this object. The database tables that must be updated are TCTYPE and TCSUBTYPE.

      The following SQL statement shows an example of how to register the RebateTC in the database: 

      insert into TCTYPE (TCTYPE_ID) values ('RebateTC'); insert into TCSUBTYPE (TCSUBTYPE_ID, TCTYPE_ID, ACCESSBEANNAME, 
   DEPLOYCOMMAND) 
values ('RebateTC', 'RebateTC', 
   'com.ibm.commerce.contract.objects.RebateTCAccessBean', 
   null);

      The following tables show an extract of the relevant columns in the TCTYPE and TCSUBTYPE tables.

      Updates made to the TCTYPE table
        Column name
      TCTYPE_ID
      Sample data RebateTC

      Updates made to the TCSUBTYPE table
        Column name
      TCSUBTYPE _ID TCTYPE _ID ACCESSBEAN NAME DEPLOY COMMAND
      Sample data RebateTC RebateTC com.ibm.commerce. contract.objects. RebateTCAccessBean null


      Register the rebate term and condition in the contract document type definition

      To make the rebate term and condition available in contracts, create a new XSD file that defines the new term and condition. You must also update the Package.xsd file to include the new XSD file.

    2. Update the XSD files to reflect the new RebateTC.

      1. Navigate to the following directory:

        where instance is the name of your WCS instance.

      2. In this directory, create a new XSD file. The following shows the XSD that would be used for the example RebateTC. The file is RebateCustomizedBuyerContract.xsd: 

        <?xml version="1.0"?>
<schema targetNamespace="http://www.ibm.com/WebSphereCommerce"
        xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:wc="http://www.ibm.com/WebSphereCommerce"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified">         
 
<!-- include basic trading agreement xsd --> 
 
<include schemaLocation="BuyerContract.xsd" />  
<complexType name="RebateTCType">        
<complexContent>            
<extension base="wc:TermConditionType"/>        
</complexContent>    
</complexType>    
<element name="RebateTC" substitutionGroup="wc:AbstractCustomizedTC">        
<complexType>            
<complexContent>                
<extension base="wc:RebateTCType">                    
<sequence>                        
<element ref="wc:RebatePolicyRef"/>                    
</sequence>                
</extension>            
</complexContent>        
</complexType>    
</element>  
   
<element name="RebatePolicyRef" type="wc:BusinessPolicyRef" />          
</schema>

      3. Save the new file.

      Next, update the Package.xsd to remove the BuyerContract.xsd and instead include the RebateCustomizedBuyerContract.xsd,...

      1. Navigate to the following directory:

        where instanceName is the name of the WebSphere Commerce instance.

      2. Open the Package.xsd file in a text editor.

      3. Locate the section about the BuyerContract.xsd and modify it as follows: 

        <!--include schemaLocation="BuyerContract.xsd"/-->
<include schemaLocation="RebateCustomizedBuyerContract.xsd"/>

    3. Create a new enterprise bean for the RebateTC.

      You must create a new enterprise bean for the new RebateTC. This new bean should inherit from the WebSphere Commerce TermCondition bean.

      A new enterprise bean for a term and condition is typically named after the subtype. Note that in this case, the term and condition subtype is the same as the term and condition type, and as such, the name of the bean is the same as the term and condition type.

      The following table shows some of the general information about the new bean that must be created. For more details about the bean, including which methods to override, refer to Create a new CMP enterprise bean for the term and condition.

      Attribute Value
      EJB Project Enablement-RelationshipManagementData
      Bean type Entity bean with container-managed persistence fields
      Bean name RebateTC
      Package com.ibm.commerce.contract.objects
      Bean supertype TermCondition
      Bean class RebateTCBean

      In the new bean, create three CMP fields that are used for the following values:

      • rebate code ID

      • amount

      • currency

    4. Update WebSphere Commerce Accelerator to reflect the new RebateTC.

      Once you have created new terms and conditions, you can update WebSphere Commerce Accelerator so that it can be used to create new contracts that include those new terms and conditions. For information about how to update this tool, refer to Update WebSphere Commerce Accelerator to use a new term and condition.

      You must create a new contract that includes the "RebateTC" term and condition and that refers to the "5DollarRebate" business policy. Use either the WebSphere Commerce Accelerator or XML to create a new contract.

      The following tables show the updates to the relevant columns of the TERMCOND and POLICYTC database tables, after the contract has been created.

      Updates made to the TERMCOND table
        Column name
      TRADING _ID TERMCOND _ID TCSUBTYPE _ID
      Sample data 25 901 RebateTC

      Updates made to the POLICYTC table
        Column name
      POLICY _ID TERMCOND_ID
      Sample data 301 901

  4. Integrate the new business policy into the shopping flow.

    In this scenario, it is presumed that a new page is added to the store that allow customers to log on and claim their rebates. When the customer would click to claim the rebate, a command that invokes the new RebatePolicyCmd interface should be invoked. For example, there could be a new ClaimRebateCmd controller command that invokes the RebatePolicyCmd. The correct business policy is then found and (in this case) the "5DollarRebate" business policy is applied.


+

Search Tips   |   Advanced Search