There are several ways to customize how KC handles its data and behavior. One of the most common ways to facilitate making changes to KC is to use a Maven war overlay. This allows an implementor to install a local clean version of KC in their local Maven repository and then create a new project reflecting their own institutional changes to KC. When a new version of KC becomes available, the implementer can simply switch war files and then proceed to resolve any errors caused by the upgrade. There are several customization options available:
- Replace existing web content with new JSPs, tags, images, etc.
- Change redirect behavior by extending existing Struts Action classes and referencing them in a custom Struts file, which can be loaded after KC's
- Install new or overriding existing services via a Spring Beans file
- Run different document rules via a custom Data Dictionary
- Add new properties to a business object by using the extension mechanism
Using a Maven War Overlay
Creating a new project with a KC maven overlay will allow you to override web content and Struts actions before you create your final war.
Prepare KC Project for Install
- Download the current
kc_projectand import it into Eclipse
- Enable maven and download all relevant Maven libraries. NOTE: You may have to install your database driver manually.
- Resolve all other compilation errors by running
- Install the kc_project war into your local repository by running
Create Your New Project
- You can check out "https://svn.kuali.org/repos/kc -> custom" and apply the custom40-base.patch which can be downloaded from from this confluence page.
- Or you can use the following steps to create project.
- Use Maven's archetype capability to initialize your new project
kc_custominto Eclipse as an Existing Maven Project
- Copy the contents of
kc_custom/src/main/webapp/WEB-INF/web.xmland make changes as needed.
- Change these tags in the root of your pom.xml
- Set up the maven dependency to kc_project in pom.xml.
- Add the war overlay build to pom.xml.
- When you are done with your customizations in
kc_custom, create a war file for
kc_customwith the overlay of
- Copy this war file to tomcat webapps folder, rename it to
kc-dev.war, and start Tomcat to deploy it.
Overriding the Spring Beans
You can change much of KC's behavior by adding your own Spring beans.
kc-custom-springbeans.xml, reference your
CustomSpringBeans.xmlby entering the following
- In the
web.xmlcopied over from
kc_projectthere is a section that loads these bootstrap Spring beans files. Edit it to add your new
kc-custom-springbeans.xmlfile You can create as many bootstrap and Spring files as you wish, depending on your needs, as they are all loaded by Spring anyway. This guide will depend on this one file for implementing services, adding data dictionary entries, and extending business objects in the next few sections.
Creating or Extending New Services
Once you have added the
CustomSpringBeans.xml file, you are ready to add or extend a service.
- Add a reference in
CustomSpringBeans.xmlto your future custom service. If you are extending a KC service, remember to include all services that its parent needs.
- Write your custom service, in this case, extending the KC basic service.
Overriding the Data Dictionary
Once you have added the
CustomSpringBeans.xml file, you are ready to add custom Data Dictionary entries.
- Decide where you are going to put your new Data Dictionary files. They must reside in a different directory than KC's Data Dictionary files (
src/main/resource/org/kuali/kra/datadictionary) to distinguish them from KC's basic Data Dictionary files. This guide will use
- Add the reference for this new directory in your
Adding Business Object Extensions
Many institutions need to add fields to existing business objects so they can adapt KC to their own business processes. KC provides a business object extension mechanism to enable implementers to do this.
- Create an extension table to hold your extra fields. The table must have the same primary keys as the KC table in order to facilitate joining tables.
- Create a Java class for the extension table in
- Create the OJB repository file
src/main/resources/org/kuali/kra/custom/repository-custom.xmland add your class descriptors. In order to make sure the objects link correctly, you will need to also add the class descriptor from the original KC repository and use the extension object to reference your new class.
- Create and integrate
CustomSpringBeans.xml(see above) and add your new repository file to it.
- Create a Data Dictionary entry for your extension object. You do not need to create Inquiry or Lookup sections.
- Copy over the Data Dictionary entry for the existing KC object, keeping the name exactly the same. You will need to edit the file to be like the following:
The file above includes the following changes:
- Adds a new field to the list of attributes
- Creates a link to the field in the extension Data Dictionary file
- References the new extension field in the inquiry and lookup sections.
- Copy over any jsp or tag files that will hold the new field and edit them as appropriate.