This document lists instructions for people with existing groups installations on how to upgrade to newer versions of grouper (or grouper related products).  If you notice something missing please let us know.  The instructions are in descending order based on date/release.  You will find instructions below for Grouper, Grouper-ws, Grouper-ui, etc.  It is assumed if you are running grouper-ui that you will perform both the grouper upgrade notes, and the grouper-ui upgrade notes.  It is understood that you will get the new source/javadoc/etc files, this document addresses configurations, jars, etc.  Note that for major upgrades, you should follow the upgrade steps.  For minor upgrades, that instructions should be sufficient.

Note that Grouper 1.5 affects the database schema, if you have queries accessing the database, or views, you will need to adjust them.  Ask the listserv if you have questions.

Grouper

• 2010/03/26: v1.5.3 GROUPER_1_5_BRANCH: compare the grouper.properties with the grouper.example.properties and get the readonly property
• 2010/03/12: v1.5.2 GROUPER_1_5_BRANCH:
  • merge the log4j.properties with log4j.example.properties as there is a new log setting for change log entries
  • merge the grouper.hibernate.properties with grouper.hibernate.example.properties as there is a new batch setting
• 2010/01/21: v1.5 HEAD: get the latest jars
  • 2010/01/21:get the latest commons-io.jar in lib/grouper (no real change from addition one month prior, just added version to manifest)
  • 2009/11/21:get the latest junit.jar from lib/grouper
  • get the latest commons-cli in lib/grouper
  • get the new ezmorph.jar and json-lib.jar in lib/grouper
  • get the latest log4j.jar to lib/grouper
  • get the latest p6spy.jar to lib/grouper
  • get the latest subject.jar to lib/grouper
  • get the latest xstream.jar to lib/grouper
• 2009/12/05: v1.5 HEAD: Merge grouper.properties with grouper.example.properties:
  • 2009/12/05: Mysql will only work in utf8 if big varchar columns are text instead.  If you arent utf8, and you dont want text, set this: ddlutils.dontSubstituteVarchar4000forTextMysql
  • 2009/09/21: Add attribute privilege defaults, e.g. attributeDefs.create.grant.all.attrAdmin, also the attributeDef privilege interface: privileges.attributeDef.interface
  • 2009/08/18: Remove the membership event log part: e.g. memberships.log.group.effective.add
  • 2009/06/09: Views are required in the database for Grouper to run.  So remove this setting: ddlutils.disableViews
  • 2009/06/08: Control if notifications/change log is enabled in API: changeLog.enabled
  • 2009/04/28: You can have hooks on a loader job: hooks.loader.class
  • 2009/03/24: Add in the optimistic locking setting: dao.optimisticLocking = true.  If you get stale state object exceptions, you can set this to false, and let the grouper team know (might be due to a custom hook we can advise on tweaking)
  • 2009/03/21: Add the two settings for if group and stem last_membership_change col should be updated (you need it for ldappc or custom things, otherwise it is not needed).  e.g. groups.updateLastMembershipTime
  • 2009/02/27: If you have the privileges or if you are wheel, then you can copy, move, rename stems.  However, if you want to lock it down, you can require stem namespace transitioners to be in a certain group: security.stem.groupAllowedToMoveStem, security.stem.groupAllowedToRenameStem, security.stem.groupAllowedToCopyStem
  • 2009/02/09: There are some audit settings: if auditing should be required for all actions (catches coding gaps in Grouper), not advisable to set to true.  And if missing audits should be logged.  audit.requireAuditsForAllActions, audit.logAuditsForMissingActions
  • 2009/01/31: You can omit time consuming or non automatically passing unit tests with several grouper.properties settings e.g. junit.test.ldappc
  • 2009/01/27: owner_id, and via_id in grouper_memberships were split out so foreign keys can be used.  If they were converted, this will drop the backup of those cols with: gsh -registry -deep
      ddlutils.dropMembershipBackupColsFromOwnerViaUpgrade = false
  • 2009/01/02: v1.5 HEAD: compare grouper.properties with grouper.example.properties.  After the DDL upgrade is successfully (perhaps a few days later), set this in grouper.properties:
      ddlutils.dropAttributeBackupTableFromGroupUpgrade = false

• 2009/11/1: v1.5 HEAD: compare grouper-loader.properties with grouper-loader.example.properties.
  • 2009/11/1: Add the enabled/disabled cron in if you want to support enabled/disabled dates on memberships
  • 2009/6/9: Add the change log section.  Note the loader must run for the change log to run.  Set the enable option to true to run this.  Set the cron to tune the default.   Add change log consumers if you have any.
• 2009/10/15: v1.5 HEAD: compare the build.properties with build.example.properties, add the ldappc resources dir settings
• 2009/09/21: v1.5 HEAD: compare the grouper.ehcache.example.properties with grouper.ehcache.properties, a few caches were added.
• 2009/09/02: v1.5 HEAD: Subject API changed, if you have custom subject sources/Subject implementations, see if they still compile.  Here is the list of changes.  You should probably subclass SubjectImpl and BaseSourceAdapter.  Get the latest subject.jar from the grouper 1.5 lib dir.  If you use a JDBC source, and you can pull from a single table or view with one row per subject, you should consider switching to the more powerful GrouperJdbcSourceAdapter2 (example in sources.example.xml)
• 2009/08/18: merge the log4j.example.properties to log4j.properties.  The event log package was changed: log4j.logger.edu.internet2.middleware.grouper.log.EventLog
• 2009/08/11: grouper.hiberate.properties caching default was changed in 1.4.2+ hibernate.cache.use_query_cache=true
• 2009/03/24: v1.5 HEAD: Group attributes changed a bit.
  • If you use them in custom code, make sure your code still compiles, and if you can remove deprecated calls (each deprecated method is overloaded with a new method).
  • You do not need to call group.store() for an attribute change anymore, it is only needed for Group fields (name, displayName, description, etc).
  • If you are making changes to the registry in a hook, you need to not use a finder to find the object you are updating, but rather use the object model provided to you.  This will prevent stale state exception, might want to send your hook code to the email list (or just the core grouper developers) for review.
  • If you are using attributes to access core fields (group.getAttributes().get("name")), please refactor so just call group.getName()
  • Non core group fields are not in the group.dbVersionDifferentFields()... you should use an AttributeHook if you need to trigger based on non group core fields (or we can add a high level hook for group edits, discuss with the core team)

Then the next ddl upgrade will delete the backup table BAK_GROUPER_ATTRIBUTES, do this yourself manually, or run: grouper_home/bin/gsh -rergistry -deep, and that will drop the backup table.

• • sdf
• 2009/03/21: v1.5 HEAD: Exception handling has changed so that grouper exceptions are now unchecked.  You can look at your custom code including hooks and see if that changes anything (if anything you can optionally not catch grouper exceptions and convert into runtime if you are right now).  Also, finders for single objects are deprecated.  If you use these in custom code or hooks you can refactor so they use the overload, pass in true as last param so it throw exception if not found.  e.g. GroupFinder.findByName()
• 2009/01/28: v1.5 HEAD: the DDL is different, this step will address the following changes.  Run this to upgrade: GROUPER_HOME/bin/gsh -registry -check
  • 2009/01/28: there are two new cols in grouper_groups and grouper_members
  • 2009/01/27: the membership table cols owner_id and via_id were expanded to owner_group_id, owner_stem_id, via_group_id, and via_composite_id.
  • 2009/01/02: grouper_groups atttributes (name, extension, display_extension, display_name, description) are now columns of grouper_groups table
    •  TO UPGRADE:
    • Look through custom code which uses the API (including hooks), and if you have accessed these fields through attributes, then convert to it how accesses via direct getters/setters.  e.g. from getAttribute("name") to getName().  or setAttribute("extension") to setExtension().  Including getAttributes() and getAttributesDb()
    • Turn off grouper systems for updates
    • Backup the registry, e.g. with export: gsh -xmlexport GrouperSystem /whatever/20090127_1_5.xml
    • Either run the in-place upgrade, or reinstall the registry and import
    • [in-place] Run: grouper_home/bin/gsh -registry -check
      • Then look at the result script, and execute that script, perhaps with:
        grouper_home/bin/gsh -registry -runsqlfile C:/mchyzer/isc/dev/grouper_v1_4/grouper/ddlScripts/grouperDdl_20090120_08_39_44_148.sql
    • -or- [reinstall] grouper_home/bin/gsh -registry -drop -runscript
      • gsh -xmlimport GrouperSystem /whatever/20090127_1_5.xml

Grouper UI

• 2009/11/13: Probably want to replace the resources/grouper/media.properties since so many settings have changed/been added
• 2009/11/12: Compare the build.properties with build.properties.template and get the new settings for grouper folder, web xml, jar, etc
• 2009/11/08: Probably want to replace the resources/grouper/nav.properties since so many settings have changed/been added
• 2009/09/09: Update or add the following jars: commons-fileupload.jar, commons-jexl.jar, jstl.jar, opencsv.jar, servlet.jar, standard.jar

Grouper WS

• 2009/11/13: Compare the build.properties with the build.example.properties.  Note that Grouper WS requires the API to be on the filesystem, it is no longer included inside
• 2009/11/13: Compare grouper-ws.properties with grouper-ws.example.properties.  Jsonconverter is now pluggable, and defaults to a new implementation.  If someone was using the old, try to get them to migrate.
• 2009/10/27: Add junit.jar to lib/grouper-ws