Skip to end of metadata
Go to start of metadata

Introduction

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 struts-config.xml file.
  • 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
Icon

This guide assumes you have working versions of Java, Maven, and Eclipse up and running.  It also is using Rice 2.x classes but they all have Rice 1.x equivalents, so please look in your version of KC's source code to see which classes are appropriate for that version.

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

  1. Download the current kc_project and import it into Eclipse
  2. Enable maven and download all relevant Maven libraries. NOTE: You may have to install your database driver manually.
  3. Resolve all other compilation errors by running
  4. Install the kc_project war into your local repository by running

Create Your New Project

  1. 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.
  2. Or you can use the following steps to create project.
  3. Use Maven's archetype capability to initialize your new project
  4. Import kc_custom into Eclipse as an Existing Maven Project
  5. Copy the contents of kc_project/src/main/webapp/WEB-INF/web.xml to kc_custom/src/main/webapp/WEB-INF/web.xml and make changes as needed.
  6. Change these tags in the root of your pom.xml
  7. Set up the maven dependency to kc_project in pom.xml.
  8. Add the war overlay build to pom.xml.
  9. When you are done with your customizations in kc_custom, create a war file for kc_custom with the overlay of kc_project.
  10. 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.

  1. Create src/main/resources/kc-custom-springbeans.xml and src/main/resources/org/kuali/kra/custom/CustomSpringBeans.xml in kc_custom.
  2. In kc-custom-springbeans.xml, reference your CustomSpringBeans.xml by entering the following
  3. In the web.xml copied over from kc_project there is a section that loads these bootstrap Spring beans files.
    Edit it to add your new kc-custom-springbeans.xml file
    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.

  1. Add a reference in CustomSpringBeans.xml to your future custom service. If you are extending a KC service, remember to include all services that its parent needs.
  2. 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.

  1. 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 src/main/resource/org/kuali/kra/customdatadictionary.
  2. Add the reference for this new directory in your CustomSpringBeans.xml.

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.

  1. 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.
  2. Create a Java class for the extension table in kc_custom.
  3. Create the OJB repository file src/main/resources/org/kuali/kra/custom/repository-custom.xml and 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.
  4. Create and integrate CustomSpringBeans.xml (see above) and add your new repository file to it.
  5. Create a Data Dictionary entry for your extension object. You do not need to create Inquiry or Lookup sections.
  6. 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.
  7. Copy over any jsp or tag files that will hold the new field and edit them as appropriate.
  • No labels

1 Comment

  1. I just wanted to add some notes about a specific change we did as part of our Rice 2.0.1 upgrade for KC Release 4.0. 

    Because of the KEN/KCB modularity changes and added support for remote runMode for these modules, KC web deployment descriptor shouldn't and couldn't map KEN/KCB servlets anymore. And so, depending on the deployment mode of our application, our web.xml needed to change. We have implemented this through Maven property substitution & profile based build. While we are running in bundled mode, we don't have to change anything because the default property (rice.ken.servlet) value is set to contain those mappings. But if we are going to deploy KC in embedded mode, we have to pass the profile names rice-web, ken-remote-mode to the maven build process. This will ensure that the maven property rice.ken.servlet value gets overridden for KEN remote calls.

    Something to keep in mind. Since KC 4.0 was an internal release, I don't think we documented this elsewhere.