Creating an extended term and condition type for contracts and accounts

You can create an extended term and condition (term) type for contracts and accounts. Create a term type when you need to supplement the default term types that are provided by HCL Commerce. For instance, when you have a preferred customer that you want to waive the application of a surcharge, or perhaps provide a different surcharge. A flexible surcharge waiver term is not provided by default, so to provide that term, you can create an extended term type.

Procedure

Define the new term type in the TCConfigurationExt.xml file, which you create.

Using this new approach, you define contract terms in the TCConfigurationExt.xml file. For details of the attributes that are mentioned in these steps, see Attributes for a new extended term contract.

If the workspace_dir/WC/xml/trading/xml/TCConfigurationExt.xml file does not exist, create it by copying and pasting the following XML code:


<?xml version="1.0" encoding="UTF-8"?>
<TCConfiguration
xmlns="http://www.ibm.com/xmlns/prod/commerce/9/contract"
xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore"
xmlns:oa="http://www.openapplications.org/oagis/9"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/9/contract TCConfiguration.xsd"
resourceBundle="contract.customTCRB">
        <!-- Add extended term definitions here; see Step 2.  -->
</TCConfiguration>

Add extended term types to this file by inserting the types after the line:


<!-- Add extended term definitions here. -->

For example, your new term types can resemble the following code:

<TCDefinition 
      type="SurChargeTC" 
      existing="false" 
      usage="Contract" 
      display="true">
    <Display 
     displayNameKey="SurChargeTC" 
     descriptionKey="SurChargeTCDescription"/>
        <Property 
          name="waiveSurCharge" 
          column="INTEGERFIELD1" 
          required="true" 
          changeable="true">
              <Display 
              displayNameKey="waiveSurCharge" 
              descriptionKey="waiveSurChargeDescription"/>
        </Property>
        <Property 
        name="surChargeAmount" 
        column="FLOATFIELD1" 
        required="false" 
        changeable="true">
                <Display 
                displayNameKey="surChargeAmount" 
                descriptionKey="surChargeAmountDescription"/>
        </Property>
</TCDefinition>

The value of the type attribute for the TCDefinition element must not be "TermCondition" or the same as subtypes of existing terms.
The value of the "usage" attribute is "Contract". The value indicates that this new term type applies only to contracts. If you also want to apply the new term type to accounts, you can change its value to "All".

Save and close the file.

Set the display properties in the resource bundle to resolve names into labels and descriptions for displaying on the HCL Commerce Accelerator in different languages.
You must provide values for the displayable identifiers in the previous section (such as waiveSurCharge) in all languages that you must support for the business users. In the resource bundle, you must provide the displayable values for the term types, in the form name=value. You must create your own resource bundle so that the content is not overwritten when service updates are applied.
You must create the resource bundle in the workspace_dir/WC/properties/com/ibm/commerce/tools/contract/properties folder to associate it with the "contract" namespace. The name of the resource bundle is your choice, however, ensure that the name does not collide with any existing resource bundle names. In the previous example of the TCConfigurationExt.xml file, the resource bundle is identified by the attribute resourceBundle="contract.customTCRB". The file name that would be used is customTCRB.properties. Continuing with the previous example, the content of the customTCRB.properties file would be:
```
# -- customized contented defined for each extended tc
SurChargeTC=Surcharge TC
SurChargeTCDescription=Surcharge Term and Condition is used for
specifying the settings related to surcharge
waiveSurCharge=Waive Surcharge
waiveSurChargeDescription=Whether to waive the charge
surChargeAmount=Surcharge Amount
surChargeAmountDescription=The amount of the surcharge
```
More languages can be supported for your business users by translating the property values (not the names) and storing them in resource bundles such as customTCRB_fr_CH.properties. The name is composed of the base name (customTCRB), followed by an underscore (_), the ISO 639-1 language code (fr), another underscore, then the ISO 3166-1 country code (CH). The name customTCRB_fr_CH.properties is the file to be used when the locale is specified for the French language (fr) in Switzerland (CH). Finally, the resource bundle must be registered in the resource.xml file in the workspace_dir/WC/xml/tools/contract folder by adding the following entry, replacing customTCRB with the name you used:
```
<resourceBundle name="customTCRB" bundle="com.ibm.commerce.tools.contract.properties.customTCRB" /> 
```
The changes in the resource.xml file might be overwritten when service updates are completed. You might need to redo this change to resource.xml after a service update is applied.
Register the new term type.
Extended terms fit into the existing contract model, and you must define a new term type by inserting a record into the TCTYPE table. You can define a single term type for all extended terms to use, or define multiple term types. Run the following SQL command to create a single new TCTYPE called 'ExtendedTC':
```
Insert into TCTYPE (TCTYPE_ID) values ('ExtendedTC');
```
The value ExtendedTC can be any unique name that is not already in use in the TCTYPE column.
For each term and condition that is found in the TCConfigurationExt.xml file, you must define a new term condition subtype. Define the term condition by inserting a record into the TCSUBTYPE table.
- To register the new extended term type in the TCSUBTYPE table, run the following SQL command:
```
Insert into tcsubtype(TCSUBTYPE_ID,TCTYPE_ID)
Values ('SurChargeTC', 'ExtendedTC');
```
  Leave the value for the ACCESSBEANNAME column as null. You can also leave the DEPLOYCOMMAND column as null when you do not have custom deployment logic for the term.
  - If the ACCESSBEANNAME column is null, the default access bean (ExtendedTermConditionAccessBean) is used when you create and update the extended term conditions. The calling method can use the getProperty and setProperty methods of ExtendedTermConditionAccessBean to get and set the properties on the term and condition.
  - If the DEPLOYCOMMAND column is null, the terms with this type is ignored during deployment.
- To register with a custom deployment command, run this SQL command:
```
Insert into tcsubtype(TCSUBTYPE_ID, TCTYPE_ID, ACCESSBEANNAME,
DEPLOYCOMMAND)
Values ('SurChargeTC', 'ExtendedTC', null, 
YourDeployCommandName);
```
Where:

YourDeployCommandName

The name of your custom deployment command. The default value is 'com.ibm.commerce.contract.commands.DeployExtendedTCCmd.'
The default access bean 'com.ibm.commerce.contract.objects.ExtendedTermConditionAccessBean' is used for handling all extended terms. The name 'SurChargeTC' shown here is an example. Enter the same value that is used in the type attribute of the TCDefinition element that is shown previously. In addition, ensure that the value for TCTYPE_ID matches the value in the TCTYPE table.

You do not typically have to define your own deployment command. You can leave yourDeployCommandName as null. However, if you want to have your own deployment logic, you must replace yourDeployCommandName with the name of your own deployment command.
Refresh the Terms and Conditions Mapping.
Note: All the steps mentioned here are only applicable for versions prior to V9.1.9.0. From HCL Commerce version 9.1.10 onwards, registry is updated through the Management Center.

To use the new terms in the HCL Commerce Accelerator user interface or the HCL Commerce runtime environment, the values must be propagated to the Registry. The Terms and Conditions Mapping is new with this release, and is found along with the other HCL Commerce registries.

If you restart the server, the registry is updated automatically. Otherwise, to update the registry:
1. Start the HCL Commerce Server.
2. Open the Administration Console.
3. Select Site and click OK.
4. Select Configuration > Registry.
5. From the Registry list, select Terms and Conditions Mapping and click the Update button.
6. After you complete the update, log out of the Administration Console.
Note: From HCL Commerce version 9.1.10 onwards, registry can be updated through the Management Center.

To use the new terms in the Management Center user interface or the HCL Commerce runtime environment, the values must be propagated to the Registry. The Terms and Conditions Mapping is new with this release, and is found along with the other HCL Commerce registries.

If you restart the server, the registry is updated automatically. Otherwise, to update the registry:
1. Start the HCL Commerce Server.
2. Open Management Center Tools.
3. From the hamburger menu, select System Administration > Registries.
4. In the Search field, enter TCMappingRegistry.
5. From the Actions menu, click on Update registry icon.
6. Once you complete the update, log out of the Management Center.

Results

After you create the term type, you can add it to contracts or accounts. Before that term type can have any effect, however, you must provide logic to handle it. Providing this logic is similar to previous releases, except that previously the custom code used the TermConditionAccessBean to access the terms. Now, the custom code uses ExtendedTermConditionAccessBean to access the extended term. A sample follows.

Long contractId = new Long(23504); 
ExtendedTermConditionAccessBean etcAB = new ExtendedTermConditionAccessBean(); 
Enumeration etcABs = etcAB.findByTradingAndTCSubType(contractId, "SurChargeTC"); 
if (etcABs.hasMoreElements()) 
{ 
  etcAB = (ExtendedTermConditionAccessBean)etcABs.nextElement(); 
  Integer waiveSurCharge = (Integer)etcAB.getProperty("waiveSurCharge"); 
  Double surChargeAmount = (Double)etcAB.getProperty("surChargeAmount"); 
}