Rice Release Notes

KFS 5.0.2 is built against Rice 2.1.6. The version of Rice included in the KFS 5.0.2 distribution zip is 2.1.6-rc2 which is equivalent to the final Rice 2.1.6 release.

You should review the release notes from the Rice team, as the changes to Rice between 1.0.3.3 and 2.1.6 are extensive, as well as the Post-2.0 impacting changes.  Also here are some fairly detailed notes taken during the upgrade process by Indiana University as well as the Rice Upgrade Troubleshooting page.

• Kuali Rice Release Documentation (In particular, review the Upgrade Guide sections in the Release Notes for 2.0, 2.1, 2.1.2, 2.1.3 and 2.1.6)

• Post-2.0 impacting changes

• Kuali Rice 2.0 Upgrade Notes - Indiana University

• Rice Upgrade Troubleshooting

Configuration Property and Parameter Changes

There are a number of new parameters and configuration properties in KFS 5.0.2.  They are documented in separate files:

• System Parameters: 5.0.2 Parameter Changes 

• KIM Data (Roles/Permissions): 5.0.2 KIM Data Changes

KFS Configuration Properties

A number of properties changed between KFS 4.1.1 and 5.0.2.  Most of these changes are related to Rice 2.x.  The KFS team has made an effort to hide most of the details by setting the new properties automatically via the KFS build process.  There are, however, a number of properties you will want to make sure that you have set properly for your institution.  You should review properties listed below in case you have set them manually, as many properties are derived.  And, if you have set any of the derived properties directly, you will circumvent the automatic inclusion of newly needed values or file locations.  (Which will, most likely, result in startup failures or missing error messages.)

Details on the changes can be found here: 5.0.2 Configuration Property Changes

See also: Configuration Properties

New in KFS 5.0.2 is an optional runtime configuration property which specifies a file (outside the KFS war file) that KFS will read configuration properties from at runtime. This parameter can be passed as a runtime parameter to Tomcat as follows:

-Dadditional.kfs.config.locations=PATH_TO_CONFIG_FILE

KFS/KC Integration

As of KFS 5.0.2, KFS will look for KC services on the KSB by default and if it doesn't find them there it will fallback to SOAP. By default bus security is enabled via the following property:

kuali.coeus.integration.bus.security.enabled=true

The namespace URIs for KFS and KC have also changed. The URIs are different than the namespace URIs used to expose other KFS and KC services on the KSB so that the integration can potentially be changed on a different schedule than the applications in the future.

The URI for the KFS Namespace (used for exposing KFS services to KC) is specified in the kfs/build/properties/build.properties file and shouldn't be changed:

# Namespace for KFS KC-KFS integration services on the Kuali Service Bus
# DO NOT CHANGE UNLESS YOU KNOW EXACTLY WHAT YOU ARE DOING!
kc-kfs.kfs.service.namespace.uri=http://kfs.kuali.org/kc-kfs/v2_0

The URIs are also specified in the org.kuali.kfs.module.external.kc.KcConstant class. Unfortunately, they are used in annotations for the service clients and there is not an easy way to parameterize this via a property. This may be something we look to change in the future.

KFS/KC Integration Data

When integrating KFS and KC and sharing a common Rice installation, the KFS Contracts & Grants Project Director role needs to have the KC PI Derived role added as a member. There is a liquibase file which does this: kfs/work/db/rice-data/07_bootstrap_kfskc_krim_role_perm_data.xml. There also needs to be a user setup with roles and permissions in both systems. There are Liquibase demo data files that show an example of this for the KC quickstart demo user: kfs/work/db/rice-data/08_demo_kfskc_krim_entity_data.xml and 09_demo_kfskc_krim_role_perm_data.xml.

Rice Server Configuration Change

This item only affects implementations which use a standalone Rice server.  As of Rice 2.0, the workflow engine will not look up the value of ${application.url} from the server which "owns" the document.  Instead, that string will *always* resolve to the Rice server.  This was done to reduce inter-server dependency within workflow and improve performance.

As such, all there ${application.url} references in the document handler URLs within the KREW_DOC_TYP_T table will need to be changed to${kfs.url} AND a configuration property (of kfs.url) with your KFS server's address must be defined *on the rice servers.*

Additionally, an issue was discovered with the document search help URLs in that they were resolving against the rice server’s base URL instead of KFS.  The delivered (and upgraded) documents will now contain the ${kfs.externalizable.help.url} property which will need to be set on standalone Rice servers.

The scripts provided with this upgrade will change that value for delivered KFS documents.  Any documents which have been added by your institution will need to be updated manually.  This can be done either in the database directly or via the document type maintenance document on the Rice servers.

Kuali Service Bus Changes

The Kuali Service Bus has undergone a number of changes in Rice 2.0.  The main impacting change is that the object remoting service has been removed.  This service allowed the Rice server to access classes on other application servers without them being formally published.  It was used primarily for workflow-related services related to document attributes, security checks, and search.  If you have not customized the KFS workflow customizations, you don’t need to do anything.  The upgrades have been done in the baseline code and the workflow data has been updated to use the new service names.

Second, all the service calls are now being done via XML-based SOAP calls.  This should be mostly transparent as it is handled by the KSB internals.  It does mean, however, that if you were exporting a service twice (once for the KSB and once for non-KSB clients), you should not need the second exporter.

The Spring beans used to export the beans has changed significantly for Rice 2.x.  They have also been extracted into their own files.  You can find them in the spring-xxx-bus-exports.xml files in the project.  The 4.1.1 to 5.0.2 Upgrade Notes document has more information on the exporter changes.

Upgrade Process Summary

work/db/upgrades/4.1.1_5.0

work/db/upgrades/5.0_5.0.1

work/db/upgrades/5.0.1_5.0.2

This process is covered in detail in the 4.1.1 to 5.0.2 Upgrade Notes document.

• Replace baseline code

• Re-apply any local changes to baseline code.

• Convert customization code using provided conversion program

• Complete code updates manually

• Apply KFS database changes (back up first)

• Apply Rice Server database changes

• Apply Rice server KFS data changes (parameters/roles/perms/etc...)

• Review and apply workflow changes (only apply if needed - must be compared to institution workflow customizations and requirements)

• Tomcat Configuration Changes

• -D properties used on Tomcat startup (JAVA_OPTS/CATALINA_OPTS)

• Optional configuration property which specifies a file (outside the KFS war file) that KFS will read configuration properties from at runtime:

  -Dadditional.kfs.config.locations=PATH_TO_CONFIG_FILE

• Configuration file changes

• Build process files (properties with defaults in the build/properties directory)

• security.properties on servers

• log4j.properties on servers

• rice-config.xml file on Standalone Rice servers

Locations of Upgrade Files

All upgrade scripts for this release are in:

kfs/work/db/upgrades/4.1.1_5.0

kfs/work/db/upgrades/5.0_5.0.1

kfs/work/db/upgrades/5.0.1_5.0.2

Within those directory we have:

• db - Liquibase scripts for upgrading a KFS database not including Rice server tables.

• Special note:  If you are using a bundled rice server (uses the same database schema), you do *not* want to run the rice-client-script.xml as those tables will also be upgraded by the Rice server upgrade scripts.

• rice_server - Scripts which need to be run against the Rice server schema.  These upgrade the KIM, KEW and KNS data as needed for KFS 5.0 as well as changes forced by the Rice 2.x upgrade.

• rice-server-script.xml - Scripts extracted from the Rice 2.0, 2.1, 2.1.2, 2.1.3 and 2.1.6 releases to upgrade a schema with the Rice server tables to the needed release.

• rice-20-code-upgrade-scripts - Groovy script and conversion patterns for upgrading institutional customizations. (only in kfs/work/db/upgrades/4.1.1_5.0)

   

• workflow - Workflow XML scripts to upgrade KFS document for changes in KFS 5.0.2.  Also includes some required attribute updates from KEW structural changes.

• rice_provided - Copies of the upgrade scripts provided by the Rice project for non-KFS document types. (only in kfs/work/db/upgrades/4.1.1_5.0)

Database Changes

There are a number of database changes in KFS 5.0.2.  Most are minor, adding new fields.  But a couple have changed the structure of important tables and added or modified the relationships between tables.

You should review the liquibase scripts in kfs/work/db/upgrades/4.1.1_50/db, kfs/work/db/upgrades/5.0_5.0.1/db, and kfs/work/db/upgrades/5.0.1_5.0.2/db directories for the details of all the changes.

KFS Database Changes

• AR

  • New reported date on the invoice document table.

  • New Billing Statement table.

• CAM

• Increased the size of the asset description fields.

• New asset payment allocation table and addition of the code and fields to the asset payment tables.

• Additional fields to support the year-end depreciation work.

• New asset payment type document type table.

• Addition of active indicators to supporting asset tables.

• COA

• Addition of labor benefit rate code to Account table.

• Creation of a child table with a one-to-many relationship to hold the ICR account and percentage information.  Migration of the affected data in the account table to the child table. (KFSMI-5614)

• Same as above but for the A21 Sub Account.

• FP

• Addition of columns to the capital asset detail table.

• Addition of columns to the capital asset group detail table.

• Dropped the revolving funds detail table (unused in KFS 4.x)

• Dropping of the FDOC_COLUMN_TYP_CD column from a number of cash-related tables and removed it from the table relationships.

• Addition of the currency amount fields to the deposit header table.

• Addition of a cashier status code to the cash detail tables.

• Migration of data into the new field.

• Addition of a procurement card defaults table.

• Addition of the accounting category code to balance report temp tables.

• Creation of a couple more temp tables for supporting balance lookups.

• GL

• Renamed GL_EXPEND_TRN_T

• LD

• Addition of benefit rate category table and added it to related tables.

• PDP

• Added ACH Eligibility code to the payee type table.

• PURAP

  • New view to help calculate total amounts on a PO.

  • Flag for whether to display a given transmission method.

  • Addition of accounting distribution method flag.  (dollars vs. percent)

  • Correction of percentage column data type.

  • Added item line numbers needed to support calculation.

  • Dropped non-null constraints on the purchasing document status code columns.

    • This is related to the application document status changes.  They are described further in 4.1.1 to 5.0.2 Upgrade Notes.

  • New purchasing excluded vendor tables and addition of related columns to other purchasing tables.

  • Dropped the AP_ELCTRNC_INV_RJT_DOC_TR2 foreign key constraint on the AP_ELCTRNC_INV_RJT_DOC_T table

    • This was preventing invalided DUNS #s from being corrected on EIRT docs.
      

  • Added auto approved indicator to AP Payment Request table.

• SYS

• Added active indicator to tax region type table.

• VND

• Added active indicator to commodity contract manager table.

• Systemwide

• Addition of fiscal year and period columns to transactional document header tables.

• Fixed data lengths on address fields.

Rice Client Database Changes

This is a summary only.  Consult the liquibase kfs/work/db/upgrades/4.1.1_5.0/rice-client-script.xml and kfs/work/db/upgrades/5.0.1_5.0.2/rice-client.script.xml files for details. 

• Renamed SRVC_NM to APPL_ID in KSB Message Queue Table.

• Updated the size of the document description field in the KNS document header to 255 characters from 40.

• Added a new table for maintenance document attachments.  (To hold the attachments in the database instead of the file system.)
  

• Added session id to locks.

Rice Server Database Changes

These are the changes being made by the KFS project to the Rice database.  It does not include changes in the Rice server upgrade scripts provided by the Rice team.

• kfs/work/db/upgrades/4.1.1_5.0/rice_server/kim_upgrade_pre_rice_20.xml

• All KIM permissions and responsibilities need to be modified to have unique namespace/name combinations.  One of the scripts here does that for any permissions/responsibilities with the “default” style name (where the name matches the template name).

• If you have not used this convention in any of your institution’s permissions, you will need to rename them in advance of the Rice 2.0 server upgrade.

• Removes a handful of duplicate permissions by ID (as provided by Kuali)

• Re-numbers a couple of KIM type IDs which were accidentally re-used by new Rice data.

• kfs/work/db/upgrades/4.1.1_5.0/rice_server/kew_upgrade.xml

• Updates the labels on a couple document types.

• Updates the help and document search help URLs.

• Adds ${kfs.externalizable.help.url} to the beginning of KFS document search help URLs.

• Replaces ${application.url} with ${kfs.url} on all delivered KFS document types. 

• If you have new document types, your document types should be added to this statement.  *DO NOT* simply update all records, as the Rice server documents need to retain ${application.url} to function.

• Updates class names of changed classes linked to routing nodes to handle changes in Rice class names.

• kfs/work/db/upgrades/5.0_5.0.1/rice_server/kew_upgrade.xml

  • Updates the help and document search help URLs.

  • Updated service namespace to be a URI "{http://kfs.kuali.org/kfs/v5_0}" instead of "{KFS}" in order for bus security to work properly.

• kfs/work/db/upgrades/4.1.1_5.0/rice_server/kim_upgrade.xml

• Prefixes all KFS type service names in KRIM_TYP_T with “{KFS}” to enable them to continue working in a standalone Rice environment. (Superseded by 5.0_5.0.1 kim_upgrade.xml changes)

• Removed KIM data related to the RA document.  (Not used since KFS 2.0 and fully removed in 5.0.)

• Fixed the namespace and KIM type on the “Administer Batch File” permission.

• Other changes, including new/updated roles, new/updated permissions, and changed role/permission assignments are documented in 5.0.2 KIM Data Changes.

• kfs/work/db/upgrades/5.0_5.0.1/rice_server/kim_upgrade.xml

  • Prefixes all KFS type service names in KRIM_TYP_T with a URL "{http://kfs.kuali.org/kfs/v5_0}" instead of “{KFS}” to enable them to continue working in a standalone Rice environment (required for bus security).

  • Other changes, including new/updated roles, new/updated permissions, and changed role/permission assignments are documented in 5.0.2 KIM Data Changes.

• kfs/work/db/upgrades/5.0.1_5.0.2/rice_server/kim_upgrade.xml

  • Changes, including new/updated roles, new/updated permissions, and changed role/permission assignments are documented in 5.0.2 KIM Data Changes.

• kfs/work/db/upgrades/4.1.1_5.0/rice_server/parameter_updates.xml

• kfs/work/db/upgrades/5.0_5.0.1/rice_server/parameter_updates.xml

• kfs/work/db/upgrades/5.0.1_5.0.2/rice_server/parameter_updates.xml

• Too many to list here.  They are documented in 5.0.2 Parameter Changes.

Workflow Changes

Summary of changes

• Searchable Attributes / Document Search Customizers

• The Rice API for customizing document search has changed dramatically in Rice 2.0.  As such, if you customized the FinancialSystemSearchableAttribute or DataDictionaryDocumentSearchCustomizer. you will need to adapt your changes to the new APIs.  Use the KFS files as examples and refer to the Rice documentation on customizing document search:http://site.kuali.org/rice/2.1.0/reference/html/TRG.html#d1357e8196 

• Purchasing Application Document Status Updates

• (see below)

• Changes:

• Moved CFDA document under the COA Simple maintenance documents parent.

• Addition of org review routing to CRM

• Routing by object code for ECD document

• Added Separation of Duties review to the DV

• Restored parallel routing to LD documents

• Renamed YEARENDDEPR document to YDPA

• Added Recall from Routing policies to top-level KFS document.

• Re-enabled the Sensitive Data Security Attribute.

• New Documents:

• Procurement Card Default document PCDM

• Asset payment document type document: APDT

• Labor Benefit Rate Category: BNRC

• Removal of RA document (unused since KFS 2.x)

• Updated package for the DataDictionaryQualifierResolver class

• Changed ${application.url} references to ${kfs.url}

• Updated document search URLs to be prefixed with ${kfs.externalizable.help.url}

Purchasing Accounts Payable Workflow Changes

Due to the change in Purchasing/Accounts Payable to use the application document status field present on the workflow document header instead of in the local purap tables, all purchasing documents (which had a custom status field at the top) must update their workflow definitions.

If you have not customized the workflow XML from that provided by the foundation in release 4.1.1, you can ingest the contents of purchasing_document_updates.xml as is.  If you have, however, you will need to review and customize to match your institution’s workflow.  In addition, the constants which were used to map the various statuses within the code has changed.  While some of the transitions are now specified in the workflow XML (removing the need for code in certain cases), a number of others still need to be managed manually.  More information on the code changes will given later in this document.

Running Rice Upgrade Program

We have provided a conversion program for Rice 1.x based code.  It is not perfect, and will result in compile errors.  But, it takes care of about 95% of the compile errors which occur when you drop in the new Rice jars.

Running of this program is documented in the 4.1.1 to 5.0.2 Upgrade Notes document.

Changes Affecting Institutional Customizations

Rice Package Changes

In order to meet the goal of version compatibility, the Rice team needed to move their classes into standard locations since, once 2.0 was released, the locations of system components would be locked down for the foreseeable future.  This has the unfortunate side effect of massively breaking every application which upgrades to Rice 2.0.  Fortunately, most of the changes were straight-forward, with class names remaining the same and only the package structure changing.  The upgrade program will take care of most of these.

Rice API Changes

One of the major changes in Rice is the support for remote web services which required the data transfer objects to be immutable for caching.  (Since caching is a critical component of maintaining performance in a distributed application.)  As such, all of the objects retrieved from the KIM and KEW service APIs are read-only.  Each has a sub-object called “Builder” which can be used to generate new versions of the objects if you need to make changes.

If you have retrieved any objects from the KIM/KEW services and then called a setter on that object, you will need to update your code before you will be able to compile it.

KIM Service API Changes

Part of the KIM changes in Rice 2.0 resulted in the removal of the IdentityManagementService.  The use of this service is now deprecated and the remaining portions of that service are being maintained within KFS.  Any new code should be using the five KIM services directly.

As for the service calls, most are fundamentally the same.  Many have slightly changed names, but the parameters and return types are the same.  The biggest change is on the lookup methods, which now have a more complex query-by-criteria mechanism and return an object containing the results as well as some metadata.  (This is common to many of the general-purpose lookups across the Rice modules.)

You should review the KIM Services documentation in the Rice 2.1 Reference Guide:http://site.kuali.org/rice/2.1.0/reference/html/TRG.html#d1357e10393 

Below are some items to watch for when upgrading your code:

• The Role Management service has been removed.  Replace any references to it with the RoleService (which now performs the caching function the RoleManagementService previously performed.)

• Permission checks (isAuthorizedXxxxx methods)

• isAuthorized no longer takes permission details.  Since Namespace and Name are now unique, they were no longer necessary.

• On other calls, you can not pass null into the permission details.  If you have no details, you must pass in an empty Map<String,String>.

• Due to how the beans are imported, you are no longer able to use SpringContext.getBean(KimServiceName.class) to obtain the services.  You should use KimApiServiceLocator.getPermissionService(), etc... for KIM services.

• The service names stored in the KRIM_TYP_T table now must have a {KFS} prefix so they can be loaded by the Rice server.  It uses that namespace to determine the server from which to request the service.

• Most service API methods will no longer accept nulls.  Usually this will be an issue with collection parameters.  If you have nothing to pass, use an empty collection of the appropriate type instead.

Use of Identity Service vs. use of Person Service

The use of the Person Service can cause performance issues that can possibly be mitigated by using the Identity Service instead. There is an API change in Rice 2.1.3 that facilitates this (see: KULRICE-8723), and there is a contribution coming in a future internal KFS patch release (5.0.3) that implements this performance improvement in KFS (see: KFSCNTRB-1337). Implementers should also keep this in mind when upgrading their own code. An example of this type of change would be to change the following code:

with this code:

Overriding Rice Spring Beans

Overriding Rice Spring beans is a bit more complex in KFS 5.0.2 due to structural changes in Rice 2.0.  It all depends if you need to override it such that *all* Rice code also sees your customizations.  (It’s probably safer if they do.  Just remember that your customizations will *not* be present on the standalone Rice server, so plan accordingly.)

In Rice 2.x, each rice sub-module (KIM/KEW/KRAD/etc...) has its own set of spring beans.  Now, to override a Rice service/dao so that other Rice services as well as KFS services see it, you need to inject that service into the correct Rice module and then export that definition back into KFS.  (This last step is only if is is not already an exported service.  See spring-kfs-imported-rice-beans.xml for the full list of beans extracted from Rice.)

To help with the override process, these properties have been created.  If set, the listed file will be injected into the specified module.  As you can see, KFS is already overriding some of the beans in the KRAD module with customized versions.

kfs.krad.override.spring.files=classpath:spring-rice-krad-overrides.xml
access.security.krad.override.spring.files=,classpath:org/kuali/kfs/sec/spring-sec-rice-overrides.xml
#krad.override.spring.files= (this one is set dynamically in build.xml from the two properties above)
core.override.spring.files=
coreservice.override.spring.files=
kim.override.spring.files=
kew.override.spring.files=
ksb.override.spring.files=
location.override.spring.files= 

Exporting JSTL Constants

The JSTLConstants class is gone.  All the constants classes used to extend this class so that they could be exposed to the JSP layer of the application.  As of 2.0, the Rice team has changed that so that you no longer need a special superclass and can export any class with "public static final" values.

If you have custom constants classes (or have overridden/extended ones from the baseline code), you will need to add beans like those below to your spring-xxx.xml files.  The properties will be exposed as a top-level attribute to the JSP files under the key given in the map of the second bean.

Message Property Locations

Under KFS 4.1.1, all the message resources (for KFS) were combined in a single ApplicationResources.properties file.  With 5.0.2, these properties were (for the most part) split out into module-specific files.  The original file has been removed from the repository and is no longer referenced in the configuration.  If you have modified that file or reference it in your message files properties, you will need to make changes to move your changes into a local institution property file and update the configuration appropriately.

For reference, the properties you will want to set are:

• institution.property.files

• institution.rice.struts.message.resources

You will want to make sure that you are *not* directly setting the following properties, as you want to inherit the settings from the foundation code:

• property.files

• rice.struts.message.resources

KFS Startup Changes

The spring configuration files used to launch the necessary components of the system have changed significantly in KFS 5.0.2 to better align with changes in Rice 2.0.  Below is a table of the files (old and new names if applicable) and their intended contents.

KFS Startup File Location

In KFS 4.1.1, this file was hard-coded in the SpringContext class.  As of KFS 5.x, it is specified by the "bootstrap.spring.file" build-time configuration property.  This property is injected into web.xml during the "dist-local" process.

RiceConfigurer Has Been Removed

As part of the changes to Rice setup, the RiceConfigurer class which served to bind all the modules of Rice into the startup process has been removed.  Instead, each of the module configurers (which still exist) now self-register without the need for an over-arching configurer.

• New initialize listener: KFSInitializeListener (instead of WebApplicationInitListener)

• Still using servlet listener

• Using more of the Rice startup code than 4.1.1 (where we duplicated it)

• Other classes used for starting up non-web instances of KFS

KFS and Components

This mainly affects the Parameter maintenance document on the Rice server, but the method of getting these components into the Rice server has changed drastically in Rice 2.0.  It should not affect applications much, but it's important to know what is going on now.

Component Publishing 

In Rice 1.x, there was a service which was published by all client applications (the RiceApplicationConfigurationService) that was queried when the Rice server needed to load components.  This required that the KFS server be on-line at the time when the data was needed.  In Rice 2.0, each client application "publishes" its components to the Rice server shortly after startup.  These components are then stored in a special table.  Every time the KFS servers start up, they re-publish their list of components to the server.  This helps the server maintain a comprehensive list of components as well as improves performance and validation reliability.

This loading is performed in the method: SpringContext.finishInitializationAfterRiceStartup()

Batch Steps

In KFS, batch steps are also valid components.  But, since they are not in the data dictionary, KFS had some special code which made them appear as such to the Rice server.  In Rice 2.0, the concept is the same, but the process is more formal, as we can publish them to the server in the same manner as the data dictionary-based components.

The loading of the batch steps is performed in: SpringContext.publishBatchStepComponents()

Additional Implementation Considerations

Java 7

KFS 5.0.2 should work with Java 7 as well as with Java 6. This version of KFS has been tested against Java 7 (1.7.0_17-b02). All core and optional unit tests were run with no disparities compared with tests run against Java 6. We haven't yet converted our EC2 instances or Jenkins CI server to Java 7 yet. For more information, see: Kuali Java 7 Transition Plan.

Standalone Rice Dependency

One of the major changes in the Rice KSB is that the registry is now accessed as a web service itself.  In Rice 1.x, each client maintained a database connection to the Rice database to access and update the registry.  The practical side-effect of this was that KFS did not *need* for the Rice server to be up at the same time as it was starting up.  It only needed the database to be accessible.

With Rice 2.x, the KFS application requires the Rice application server (or at least the KSB module - service registry) to be available upon startup or it will fail and need to be restarted.

Other considerations:

• KRAD causes the application to use more memory.  Production implementations should allocate more memory to the JVM to ensure existing performance.

• Rice seems to use more database connections, requiring the database pool sizes to be larger.