Skip to end of metadata
Go to start of metadata

Background

In Rice 1.0, the KIM module has been implemented to provide group-related services. This module replaces the WorkgroupService and related classes which have traditionally been a part of KEW. In order to get rid of this redundancy, we need to execute a conversion from the KEW services to the KIM services.

Classes which should no longer exist after conversion is complete

  1. org.kuali.rice.kew.workgroup.*
  2. org.kuali.rice.kew.workgroup.dao.*
  3. org.kuali.rice.kew.dto.WorkgroupDTO
  4. org.kuali.rice.kew.dto.WorkgroupIdDTO
  5. org.kuali.rice.kew.dto.WorkgroupNameDTO
  6. org.kuali.rice.kew.dto.WorkflowGroupIdDTO

Classes which should not be considered for conversion

  • KimWorkgroupServiceImpl
  • NotificationRecipientServiceKewImpl

Guidelines for Performing the Conversion

Timeline for Conversion

  1. Convert back-end references from KEW's objects and services to KIM's objects and services
  2. Convert KEW client APIs (WorkflowDocument, WorkflowInfo)
  3. Change all data types referencing a group id in KEW to store the data in a VARCHAR2 column instead of a NUMBER column. Change all java objects representing group ids from java.lang.Long to java.lang.String. Create database conversion scripts.
  4. Change names of member variables on OJB/JPA mapped classes from "workgroupId" to "groupId"
    Icon

    It's important that we don't change "workgroupId" to "groupId" on our database-mapped beans until the end. The reason for this is because the people working on finishing the JPA implementation would be immediately impacted by this. Instead we should wait until the end to perform this conversion.

Major Differences between KIM groups and KEW groups

There are a few major differences which will have to be considered during the conversion.

  1. KEW groups are uniquely identified by name, KIM groups need both name and namespace code
  2. KEW group ids are treated as numeric Long values, KIM group ids are treated as Strings
  3. KimGroup and KimPrincipal do not share a common hierarchy, KEW's Workgroup and WorkflowUser do (rooted at org.kuali.rice.kew.user.Recipient)
  4. KEW groups have a List of members on them, to get the members of a KimGroup a separate service call must be made
  5. IDs of KEW groups exist in a class hierarchy which is shared with WorkflowUser ids, in KIM identifiers are not encapsulated into objects but rather passed around as Strings

These differences will need to be dealt with during conversion. Details on how to deal with each of these cases is described below.

API Changes

The KEW APIs will need to change in the following ways:

WorkflowDocument/KualiWorkflowDocument

Any method in WorkflowDocument which took a WorkflowGroupIdDTO will now just take the group ID.

This has impacts on the following API methods on WorkflowDocument

  1. appSpecificRouteDocumentToGroup
  2. takeGroupAuthority
  3. releaseGroupAuthority

WorkflowInfo/KualiWorkflowInfo

Any methods referencing WorkgroupDTO or WorkgroupIdDTO will be removed from the WorkflowInfo/WorkflowUtility service. Instead, client applications should use the KIM IdentityManagementService. This includes the following methods:

Conversion Details

Replace Workgroup with Kim Group

Icon

Content below this point is still in progress

In general, this should be straightforward. However, as mentioned previously if the original code

1) Workgroup needs to be replaced with KimGroup

2) To fetch the KimGroup you will need to call KIMServiceLocator.getIdentityManagementService().getGroup(...) or getGroupByName(...).

3) There are also methods on the service to check group membership. It's preferable to use these where possible instead of loading the group members from the service. This helps with efficiency (in KEW the group members were attached to the Workgroup object, in KIM that's not the case and helps to improve efficiency).

4) There is a difference between groups names in KEW and those in KIM. In KIM the group is identified by a name plus a namespace. For this reason, if you are forced to lookup a workgroup by name, use KIMConstants.TEMP_GROUP_NAMESPACE. This is deprecated and will make it easier for us to track these cases down and resolve them later but should help in not slowing us down during the conversion.

5) In KIM the group ID is a String (varchar2(40)) in KEW it's was a Long (number(19)). So the getGroup(...) method on the IDM service takes a String instead of a Long. Where possible, please convert references to a group ID from a Long to a String. This includes in the database and the OJB mapping (see how I dealt with this for DocumentType blanket approve workgroup id, etc.). You can find examples of SQL to execute to perform the db conversion to convert a number column to a varchar column (see kew-upgrade-0.9.3-to-0.9.4.sql for examples)

6) Remember to update JSPs! For example, there are JSPs out there that have something like workgroup.groupNameId.nameId in them. If the "workgroup" reference ends up getting changed to a KimGroup then this would change to something like this: workgroup.groupName (see the KimGroup class). There will be quite a few JSPs where we are printing out workgroup names (action list, route log, etc.)

7) You won't be making changes to the KEW Workgroup object and WorkgroupService in the org.kuali.rice.kew.workgroup package (the old workgroup API). instead, the idea is to keep removing references to that stuff until nothing is left referencing that and we can remove it.

8) One of the gaps we will have to deal with is the XML parser for Workgroup XML (currently the WorkgroupXMLHandler). I think we will probably just rewrite this so that it deals with KimGroup instead of Workgroup. That can likely wait until the rest of the conversion is complete though.

9) Please try to bite off small pieces of this at a time (for example, start with the actionitem package). You will find a lot of this work has a trickle-down effect where you change one thing which requires you to change something else and so on. Eventually, you will reach a point where you can stop and commit the work you've done so far (after dong a quick test of course). I may be working on this as well as I'm working on other things. So I don't want us to end up with a large outstanding change set that has to be merged in some way. This will also allow us to distribute work on this task beyond the both of us if it comes to that.

Progress

The following code is either in progress, has been converted to Kim, or is compatible with the legacy KEW system:

  • org.kuali.rice.kew.actions
    • AdHocAction (compatible/done)
    • DisapproveAction (tested/done)
    • ActionTakenEvent (needs testing)
    • ReleaseWorkgroupAuthority
    • TakeWorkgroupAuthority
  • org.kuali.rice.kew.actionlist.*
    • ActionListTest (ignored - test class)
    • ActionListService (in progress)
    • ActionListServiceImpl (in progress)
    • ActionListFilterAction (in progress/needs testing)
  • org.kuali.rice.kew.actionrequest.*
    • ActionRequestFactory (needs testing)
    • ActionRequestValue (needs testing)
    • ActionRequestServiceImpl (needs testing)
  • org.kuali.rice.kew.actiontaken.*
    • ActionTakenService (needs testing)
    • ActionTakenServiceImpl (needs testing)
    • ActionTakenValue (needs testing - database value converted as well)
  • org.kuali.rice.kew.docsearch
    • DocumentSearchSecurityTest
  • org.kuali.rice.kew.engine.simulation
    • SimulationEngine (needs testing)
  • org.kuali.rice.kew.lookupable
    • RuleBaseValuesLookupableImpl
  • org.kuali.rice.kew.service.*
    • WorkflowUtilityWebServiceImpl (needs testing)
  • org.kuali.rice.ken.service.impl
    • NotificationRecipientServiceKewImpl/NotificationRecipientServiceKimImpl (tested/done)
  • org.kuali.rice.kew.server
    • BeanConverterTester
  • org.kuali.rice.kew.service
    • WorkflowDocument
  • org.kuali.rice.kew.rule.service.impl
    • RuleServiceImpl (needs testing)
  • org.kuali.rice.kew.test.*
    • TestUtilities (needs testing)
  • org.kuali.rice.kew.util
    • FutureRequestDocumentStateManager (needs testing)
  • org.kuali.rice.kew.web.session
    • UserSession
  • org.kuali.rice.kew.rule.web
    • WebRuleResponsibility
  • org.kuali.rice.kew.web
    • WorkflowRoutingForm
    • WorkflowAction (needs testing)
  • org.kuali.rice.kew.xml
    • RuleXMLParser
  • org.kuali.rice.kew.actionlist.web
    • ActionListAction (needs testing)
    • ActionListFilterAction (needs testing)
  • org.kuali.rice.kew.actionitem.dao.impl
    • ActionItemDAOOjbImpl (needs testing)
  • No labels