State and City Tax Extended Attribute Technical Specification

Jira Tasks

• KITT-130@Jira

Revision History

Version	Date	User	Description
1.0	02/02/2009	Heather Lo	Initial Spec
2.0	02/16/2009	Heather Lo	Final Spec (that describes steps completed)
2.1	02/24/2009	Heather Lo	Final Spec (that includes code)
2.2	03/26/2009	Heather Lo	Final Spec (that includes modified code)

Technical Description

Two vendor-related fields exist in FRS, but not in KFS. Two extended attributes will represent the AZ Sales Tax License Number and the Tucson Sales Tax License; they need to be added to the Vendor business object. These two attributes will need to be displayed on the Vendor inquiry screen.

Details

• Database Requirements
  1. AZ Sales Tax License Number: varchar2(9), optional, not validated
  2. Tucson Sales Tax License: varchar2(7), optional, not validated
• UI Design
  1. New "Extended Attributes" tab under the "Address" tab
  2. Two free form fields appear on Vendor inquiry screen in the "Extended Attribute" tab: "Arizona Sales Tax License Number" and "City of Tucson Sales Tax License"
• Development Checklist
  1. Write SQL script to create extension table (extends PUR_VNDR_DTL_T).
  2. Create edu.arizona.kfs.vnd in Eclipse.
  3. Create POJO for both attributes (VendorTaxExtension.java) that extends PersistableBusinessObjectExtensionBase.
  4. Create ojb-vnd.xml file to include the base business object (b.o.) and the extension b.o. The class-descriptor for base b.o. includes reference-descriptor for extension.
  5. Update data dictionary.
     • Create new data dictionary file for extended attribute (VendorTaxExtension.xml). Copy base b.o. data dictionary file and include your extension.
     • Create new data dictionary file for the base b.o. (VendorDetail.xml). Copy the original file and modify to include extended attributes.
  6. Create maintenance document data dictionary (VendorDetailMaintenanceDocument.xml) to include the original file and the new extended attributes.
  7. Modify the tags file for the Vendor channel on the maintenance menu.
  8. Create or modify the spring file (spring-vnd.xml) to override the Vendor module definition and pull in the new files.
  9. Create JSP tag that is referenced from vendor jsp file.

Development Steps Completed

1. Created a package in Eclipse to store our institution's files. (edu.arizona.kfs.vnd)
2. Wrote SQL script to create a new table called PUR_VNDR_DTL_EXT_T and added it to kfs.work.db.scripts.arizona.schema-oracle.sql. It includes:
   • Primary keys in the table that we are extending (PUR_VNDR_DTL_T)
   • Version number and object id which should be in every table
   • Our new fields that we are adding to the table
3. Created a business object (POJO) named VendorDetailExtension.java which includes:
   • The primary keys and the new fields we are adding
   • The toStringMapper method that overrides org.kuali.rice.kns.bo.PersistableBusinessObjectExtensionBase.toStringMapper
4. Created ojb-vnd.xml file that maps the column names in the database to the names in our POJO:
   • Created a class-descriptor for our new table mapping
   • Copied the class-descriptor for the PUR_VNDR_DTL_T table in the delivered obj.vnd.xml file so we could add a reference-descriptor of the name "extension"
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/ojb-vnd.xml

     <descriptor-repository version="1.0">
     
     <class-descriptor class="edu.arizona.kfs.vnd.businessobject.VendorDetailExtension" table="PUR_VNDR_DTL_EXT_T">
         <field-descriptor name="vendorHeaderGeneratedIdentifier" column="VNDR_HDR_GNRTD_ID" jdbc-type="INTEGER" primarykey="true" index="true"/>
         <field-descriptor name="vendorDetailAssignedIdentifier" column="VNDR_DTL_ASND_ID" jdbc-type="INTEGER" primarykey="true" index="true"/>
         <field-descriptor name="objectId" column="OBJ_ID" jdbc-type="VARCHAR" index="true"/>
         <field-descriptor name="versionNumber" column="VER_NBR" jdbc-type="BIGINT" locking="true"/>
         <field-descriptor name="azSalesTaxLicense" column="AZ_SALES_TAX_LIC" jdbc-type="VARCHAR" />
         <field-descriptor name="tucSalesTaxLicense" column="TUC_SALES_TAX_LIC" jdbc-type="VARCHAR" />
     </class-descriptor>
     
     <class-descriptor class="org.kuali.kfs.vnd.businessobject.VendorDetail" table="PUR_VNDR_DTL_T">
         <!-- include delivered field-descriptor, reference-descriptor, and collection-descriptor properties -->    
     
         <reference-descriptor name="extension" class-ref="edu.arizona.kfs.vnd.businessobject.VendorDetailExtension" auto-retrieve="true" auto-update="object" auto-delete="object" proxy="false">
         <foreignkey field-ref="vendorHeaderGeneratedIdentifier" />
         <foreignkey field-ref="vendorDetailAssignedIdentifier" />
         </reference-descriptor>    
     </class-descriptor>
     
     </descriptor-repository>

5. Created a new data dictionary file for the extended attribute named VendorDetailExtension.xml. Added attribute definitions for the following attributes:
   • Primary keys
   • The fields we are adding
   • Version number
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetailExtension.xml

     <bean id="VendorDetailExtension" parent="VendorDetailExtension-parentBean" />
     <bean id="VendorDetailExtension-parentBean" abstract="true" parent="BusinessObjectEntry">
     	<property name="businessObjectClass" value="edu.arizona.kfs.vnd.businessobject.VendorDetailExtension" />
     	<property name="objectLabel" value="Vendor" />
     	<property name="attributes">
     		<list>
     			<ref bean="VendorDetailExtension-versionNumber" />
     			<ref bean="VendorDetailExtension-azSalesTaxLicense" />
     			<ref bean="VendorDetailExtension-tucSalesTaxLicense" />
     			<ref bean="VendorDetailExtension-vendorHeaderGeneratedIdentifier" />
     			<ref bean="VendorDetailExtension-vendorDetailAssignedIdentifier" />
     		</list>
     	</property>
     </bean>
     <bean id="VendorDetailExtension-vendorHeaderGeneratedIdentifier" parent="VendorDetail-vendorHeaderGeneratedIdentifier-parentBean" />
     
     <bean id="VendorDetailExtension-vendorDetailAssignedIdentifier" parent="VendorDetail-vendorDetailAssignedIdentifier-parentBean" />
     
     <bean id="VendorDetailExtension-azSalesTaxLicense" parent="VendorDetailExtension-azSalesTaxLicense-parentBean" />
     
     <bean id="VendorDetailExtension-azSalesTaxLicense-parentBean" abstract="true" parent="AttributeDefinition">
     	<property name="name" value="azSalesTaxLicense" />
     	<property name="forceUppercase" value="false" />
     	<property name="label" value="Arizona Sales Tax License Number" />
     	<property name="shortLabel" value="AZ Tax#" />
     	<property name="maxLength" value="9" />
     	<property name="control">
     		<bean parent="TextControlDefinition" p:size="22" />
     	</property>
     </bean>
     
     <bean id="VendorDetailExtension-tucSalesTaxLicense" parent="VendorDetailExtension-tucSalesTaxLicense-parentBean" />
     
     <bean id="VendorDetailExtension-tucSalesTaxLicense-parentBean" abstract="true" parent="AttributeDefinition">
     	<property name="name" value="tucSalesTaxLicense" />
     	<property name="forceUppercase" value="false" />
     	<property name="label" value="City of Tucson Sales Tax License Number" />
     	<property name="shortLabel" value="Tuc City Tax#" />
     	<property name="maxLength" value="7" />
     	<property name="control">
     		<bean parent="TextControlDefinition" p:size="22" />
     	</property>
     </bean>
     
     <bean id="VendorDetailExtension-versionNumber" parent="AttributeReferenceDummy-versionNumber-parentBean" />

6. Created VendorDetail.xml data dictionary file that adds to and overwrites parts of the delivered VendorDetail.xml file.
   • Added our new fields to the attributes list of the VendorDetail bean using the merge="true" attribute
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetail.xml

     <bean id="VendorDetail" parent="VendorDetail-parentBean">
     	<property name="attributes">
     		<list merge="true">
     			<ref bean="VendorDetail-azSalesTaxLicense" />
     			<ref bean="VendorDetail-tucSalesTaxLicense" />
     		</list>
     	</property>
     </bean>

   • Defined beans for each new field which points to extension.newFieldName
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetail.xml

     <bean id="VendorDetail-azSalesTaxLicense" parent="VendorDetail-azSalesTaxLicense-parentBean" />
     <dd:boAttributeRef id="VendorDetail-azSalesTaxLicense-parentBean"
     	abstract="true" parent="VendorDetailExtension-azSalesTaxLicense-parentBean"
     	attributeName="extension.azSalesTaxLicense" />
     
     <bean id="VendorDetail-tucSalesTaxLicense" parent="VendorDetail-tucSalesTaxLicense-parentBean" />
     <dd:boAttributeRef id="VendorDetail-tucSalesTaxLicense-parentBean"
     	abstract="true" parent="VendorDetailExtension-tucSalesTaxLicense-parentBean"
     	attributeName="extension.tucSalesTaxLicense" />

   • Copied/redefined the InquirySectionDefinition for VendorDetail-inquiryDefinition-parentBean because 1) our new fields are going on a new tab on the screen in a specific place and 2) InquirySectionDefinition doesn't have an id defined, so we can't extend it (i.e. can't say merge="true").
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetail.xml

     <bean id="VendorDetail-inquiryDefinition" parent="VendorDetail-inquiryDefinition-parentBean" />
     
     <bean id="VendorDetail-inquiryDefinition-parentBean" abstract="true" parent="InquiryDefinition">
     	<property name="title" value="Vendor Inquiry" />
     	<property name="inquirySections">
     		<list>
     			<!-- include delivered InquirySectionDefinition bean for Vendor Detail -->
     			<bean parent="InquirySectionDefinition">
     				<property name="title" value="Additional Attributes" />
     				<property name="numberOfColumns" value="1" />
     				<property name="inquiryFields">
     					<list>
     						<bean parent="InquirySubSectionHeaderDefinition" p:attributeName="Vendor Sales Tax License Information" />
     						<bean parent="FieldDefinition" p:attributeName="extension.azSalesTaxLicense" />
     						<bean parent="FieldDefinition" p:attributeName="extension.tucSalesTaxLicense" />
     					</list>
     				</property>
     			</bean>
     			<!-- include delivered InquirySectionDefinition beans for other inquiry sections in Vendor -->
     		</list>
     	</property>
     	<property name="inquirableClass" value="org.kuali.kfs.vnd.businessobject.inquiry.VendorInquirable" />
     </bean>

7. Created maintenance document data dictionary (VendorMaintenanceDocument.xml).
   • Added a reference bean for our "Additional Attributes" tab to the maintainableSections of the VendorMaintenanceDocument bean using the merge="true" attribute
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetailMaintenanceDocument.xml

     <bean id="VendorMaintenanceDocument" parent="VendorMaintenanceDocument-parentBean">
     	<property name="maintainableSections">
     		<list merge="true">
     			<ref bean="VendorMaintenanceDocument-ExtendedAttributes" />
     		</list>
     	</property>
     </bean>

   • Added a section to define the new maintainableSection that refers to extension.newFieldNames
     excerpt from kfs/work/src/edu/arizona/kfs/vnd/businessobject/datadictionary/VendorDetailMaintenanceDocument.xml

     <bean id="VendorMaintenanceDocument-ExtendedAttributes" parent="VendorMaintenanceDocument-ExtendedAttributes-parentBean" />
     
     <bean id="VendorMaintenanceDocument-ExtendedAttributes-parentBean" abstract="true" parent="MaintainableSectionDefinition">
     	<property name="id" value="ExtendedAttributes" />
     	<property name="title" value="Additional Attributes" />
     	<property name="maintainableItems">
     		<list>
     			<bean parent="MaintainableSubSectionHeaderDefinition" p:name="Vendor Sales Tax" />
     			<bean parent="MaintainableFieldDefinition" p:name="extension.azSalesTaxLicense" />
     			<bean parent="MaintainableFieldDefinition" p:name="extension.tucSalesTaxLicense" />
     		</list>
     	</property>
     </bean>

8. Created a spring file (spring-vnd.xml) to tell Spring where to look for our Vendor extension files. Also uses the merge="true" attribute.