Extended Attributes 2

Description

Extension attributes are a method of adding new attributes to existing business objects without having to change the delivered code or database structure. Some minor coding is required, but all changes can be made without altering the files delivered with KFS. This allows upgrades to be performed much easier than if changes are made to core elements.

Extension attributes are implemented by creating a secondary table that shares the same primary key as the table being extended. The KNS has a built-in hook which allows an institution to attach these new attributes without needing to alter the object being extended. Most of the changes required are XML configuration. And, while the instructions below may seem long, most of it is the standard set of modifications which need to be done to create a new business object.

Implementation Instructions

In our example, we are adding an attribute called program code to the account table. This example makes program code a free-form field, rather than associating a reference table that can be used to lookup / validate values. However, it is perfectly feasible to associate a reference table with an extension attribute. It is also possible to use extension attributes in custom properties and existing JavaScript in transactional documents, e.g. to display the value next to the account description on accounting lines. See the patches/program-code-extension-attribute in the distribution for a full example demonstrating both of these things. Basically, once you have created an extension table using the steps below, the new attributes can be used just like normal attributes in the delivered system or standalone entities that you add to the system.

1. Create a table to hold the additional attributes (e.g. CA_ACCOUNT_EXT_T).
   The table should have the same primary key fields as the delivered table that you are adding to. See the table creation documentation for more information. For example...
   CA_ACCOUNT_EXT_T.table.ddl
2. Create a Java object for the extension table (e.g. edu.sampleu.kuali.module.chart.bo.AccountExtension).
   It must implement the org.kuali.core.bo.PersistableBusinessObjectExtension interface and should extend the org.kuali.core.bo.PersistableBusinessObjectExtensionBase class. For example...
   edu.sampleu.kuali.module.chart.bo.AccountExtension.java
3. Create/modify your OJB repository file for the module.
   1. Add a class descriptor for the extension business object.
   2. Copy the repository descriptor for the base business object from the delivered OJB repository file (e.g. org.kuali.module.chart.OJB-repository-chart.xml) into your OJB repository file and add a reference to the extension business object.
      For example...
      edu.sampleu.kuali.module.chart.sampleu-repository-chart.xml
      Icon

      Be sure to retain all of the original field, reference, and collection descriptors from the original OJB class descriptor. If any are missing, the system may not be able to persist to/retrieve from the corresponding attributes of the business object.

4. Update the data dictionary.
   1. Make the business object entry changes.
      1. Add a data dictionary file for the extension business object.
         This would be completed like any other business object except that it does not need an Inquiry or Lookup section. For example...
         edu.sampleu.kuali.module.chart.datadictionary.AccountExtension.xml
      2. Copy the data dictionary file for the base object into the your data dictionary directory. IMPORTANT: Keep the file name the same!
         • Update the copy of the base object's file to include properties from the extension object.
         • Create attributes as <attributeReference> tags and link to the extension business object (or as appropriate).
         • Add new fields to the inquiry and lookup sections as required.
         • Add relationships if the extension object uses lookups. Relationships must be defined from the location of the base object being edited.
         • Link in the extension.versionNumber attribute for object persistence to work properly.
           (Account) even if the relationships also exist on the subordinate object (AccountExtension).
           edu.sampleu.kuali.module.chart.datadictionary.Account.xml
   2. Make the maintenance document data dictionary changes.
      • Add attributes to the maintainable fields lists.
      • If new rules are needed, create a new business rule and/or pre-rules class by subclassing the base one's referenced here, then change the references to point to the new rules class(es) you created.
      • Update the default existence checks, if necessary.
      • Add new script files, if needed.
5. Override the appropriate module definition to pull in the files that you have added.