Determining Whether a Change is Impacting

What is an impacting change?

An impacting change is any change that, when incorporated into an implementors system, requires alterations to their local database, code, or configuration in a way which is not handled by our upgrade scripts.

Examples of Impacting Changes

Changing the name or data type of a business object property.
- Implementors may have extended/overridden the class. This could cause problems in extended code and overridden data dictionary entries if the parent no longer exists.
Changing the ID of any Data Dictionary entry.
- (same as above)
Adding a spring-injected property to a service.
- If the institution has overridden the bean, they will not be injecting that new property and their application will fail at runtime with a NullPointerException when they attempt to use the code which utilizes the new property.
Changing the ID of or removing any service bean.
- (same as above)
Removing any existing services/beans.
Changing the signature of, or removing any public or protected service methods.
- Implementors may have overridden the method. This could cause problems in extended code if the overridden method no longer exists.
There are other examples of changes that could impact implementers and that we specifically track with the following JIRA fields in the KFS Contribution Development queue: Rice Change Required?, API Changes, Data Structures, KFS Data, Rice Data, Configuration Properties, and Libraries

Configuration Problems

If you update and start seeing page display problems try:
- Clearing your browser cache
- Stop Tomcat and delete your tomcat working directory
If you update and see what appear to be configuration issues like OJB and spring errors, when you start the web application
- Make sure you ran mvn package -DskipTests=true
- Verify that the xml configuration files in the project source directory have been built to your classes directory, and if not try Cleaning and rebuilding the project
  - mvn clean package -DskipTests=true

Development Logging Configuration

To override the default logging configuration, copy kfs/src/main/resources/log4j.properties to a directory outside the project, your home directory for example, and then override the log4j.settings.file property to point to this file. For example:

log4j.settings.file=/Users/bh79/log4j.properties

Once you've done this, you can modify your log4j.properties file. The simplest option is just to modify the level of the rootLogger
- Change log4j.rootLogger=INFO, StdOut to log4j.rootLogger=DEBUG, StdOut to see all the DEBUG level log statements the code issues
If you want to get fancier, you can do something like add this line to see all the DEBUG level statements for the labor module: log4j.logger.org.kuali.module.labor=DEBUG
Or, you could combine the two approaches by setting log4j.rootLogger=ERROR, StdOut and also adding the additional logger (log4j.logger.org.kuali.module.labor=DEBUG). This will only log statements at error and above for anything outside of the labor packages and log any statements issued by classes in the labor packages at debug.

Formatting on jsps and tags

Avoid doing arithmetic on jsp/tag. Do it in BO instead and use appropriate getter. For that matter, avoid practically all business logic in jsps and tags.

For 1000s commas use DD or if not available JSTL. Example:

DD: On your attributeReference or attribute use

<formatterClass>org.kuali.core.web.format.CurrencyFormatter</formatterClass>

Directly on tag / jsp:

<fmt:formatNumber value="${KualiForm.budgetOverviewFormHelper.personnelSalaryAgencyRequest}"
type="currency" currencySymbol="" maxFractionDigits="0" />

Record Locked

If you get a message such as: "This document cannot be Saved or Routed because the maintenance record is locked by #xyz" then you can either try to cancel that document by opening it (or completing it's route) or if it's hosed you can delete the lock from krns_maint_lock_t by deleting any row where the FDOC_NBR matches xyz (so whatever the locked document is).

Testing protected service methods

Service interfaces are only to have methods that are useful for the project. Do not expose methods solely for junit test cases. Instead put the test case in the same (test) package and utilize TestUtils.getUnproxiedService to get an unproxied instance of the service. Using getUnproxiedService is necessary because Spring returns proxied instances of Services that can not be cast to implementations.

For example usages of this see:

BalancingServiceImplTest
LaborBalancingServiceImplTest

It is also possible to instantiate the Service Implementation class, however keep in mind that you need to inject the services that Spring would normally inject for you manually. For this reason, the getUnproxiedService approach described above may be preferable.

For example usages of this see:

ContractsGrantsInvoiceCreateDocumentServiceImplTest
CustomerDocumentServiceImplTest

Reappearing line items after deletion

"I'm adding items to a collection, saving the document, retrieving it from the database, and they are automagically back!! What should I do?!"

Override buildListOfDeletionAwareLists in your business object. Below is the relevant JavaDoc from PersistableBusinessObject. See DelegateGlobal.buildListOfDeletionAwareLists as an example.

/**
 * If this method is not implemented appropriately for PersistableBusinessObject with collections, then
 * PersistableBusinessObject with collections will not persist deletions correctly.
 * Elements that have been deleted will reappear in the DB after retrieval.
 * 
 * @return List of collections which need to be monitored for changes by OJB
 */

Viewing the serialized workflow XML

Go to the portal -> Administration -> Document Operation -> <enter your doc number> NOTE: The Document Operation screen is for experts only, use at your own risk.