Customizing KFS Business Rules

1. Heather Stapleton, Indiana University Warren Liang, University of California-Irvine November 17th, 2009 Customizing KFS Business Rules

2. Ways to Customize KFS • System Parameters • Maintenance Tables • Extending KFS Classes • Presentation Controllers • Authorizers • Rules • Granular Validations Identity Management (KIM) Tuesday @ 11am Salon B Workflow (KEW) Wednesday @ 2pm Conf 3+4

3. Parameters - Purpose • Customize based on YOUR policies • Controlled by users • Externalize constants • Maintained in tables • Easy to use

4. Parameters – Usage • May be used in: • Business rules checks • Runtime changes; no server restart • May not be used in: • Values not represented by constants • Core constants that will not change • Spring XML configuration files • OJB XML descriptor files

5. Parameter Lookup

6. Parameter Lookup - Namespace

7. Parameter Lookup – Component

8. Parameter Lookup - Component

9. Parameter Lookup – App Namespace

10. Parameter Lookup – App Namespace

11. Parameter Lookup – Type Code

12. Parameter Examples On/Off Switches

13. Parameter Examples Defaults

14. Parameter Examples Requiredness

15. Parameter Examples

16. Maintenance Tables

17. Maintenance Tables

18. Maintenance Tables

19. Maintenance Tables

20. Customizing KFS Goals • To customize KFS documents’ rules and authorization with a minimal amount of KFS code changes • Achieve this by: • Extending classes • Overriding configuration

21. Customizing KFS Rules - note Code shown on the PPT is abbreviated Real code is shown in the notes of the PPT file Examples will be shown, link to patches at end of slides

22. Configuration overview KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

23. Document Presentation Controllers • Determines whether a document is in a state that would allow certain actions to be performed • Decisions not based on user

24. Document Presentation Controllers interface DocumentPresentationController { Set<String> getDocumentActions(Document document); boolean canInitiate(String docTypeName); }

25. Document Authorizers • Determines whether a particular user is allowed to take a particular action against a document • Primarily a façade for KIM • Customization performed by changing KIM data

26. Presentation Controller/Authorizer Presentation Controllers Document Authorizers

27. Document Rules • Performs validation before actions are taken • Primarily used for maintenance documents, but also for some transactional documents

28. Document Rules interface RouteDocumentRule extends BusinessRule { boolean processRouteDocument(Document document); }

29. DocumentRuleBase • Base implementation for most of these interfaces is DocumentRuleBase • Contains a customization hook to add document-specific logic

30. DocumentRuleBase public boolean processRouteDocument(Document doc) { boolean isValid = isDocAttrsValid(document, true); isValid = isValid && processCustomRouteDocBusinessRules(doc); return isValid; } protected boolean processCustomRouteDocBusinessRules(Document doc) { // Document-specific logic would override this method return true; }

31. Configuration overview KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

32. Data Dictionary • Repository of metadata for documents and business objects • Comprised of Spring beans • Configures how to validate a document

33. Data Dictionary Overriding Abstract parent bean definition and “concrete” inheriting bean Customize/override the concrete beans

34. Document DD bean example <bean id="CashMgmtDocument" parent="CashMgmtDocument-parentBean"/> <bean id="CashMgmtDocument-parentBean" abstract="true“ parent="AccountingDocumentEntry"> <property name="businessRulesClass“ value=“<package>.CashMgmtDocRule"/> <property name="documentAuthorizerClass“ value=“<package>.CashMgmtDocAuth"/> <property name="documentPresentationControllerClass“ value=“<package>.CashMgmtDocPresContBase"/>

35. Configuration overview KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

36. Module Configuration • Maintains metadata related to an application module • List of DD directories • Override the Module Configuration Bean if adding new DD files

37. Module Configuration Example <bean id="arModuleConfiguration" parent="arModuleConfiguration-parentBean" /> <bean id="arModuleConfiguration-parentBean" class=“<package>.FinancialSystemModuleConfiguration" abstract="true"> <property name="dataDictionaryPackages"> <list> <value> org/kuali/kfs/module/ar/bo/datadictionary </value> <value> org/kuali/kfs/module/ar/doc/datadictionary </value> </list> </property> }

38. Configuration overview KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

39. Build properties • Files in build/properties contain default values • Can redefine props in ~/kfs-build.properties • Various output files • work/src/configuration.properties • web.xml • security.properties • Etc.

40. Build property customization ~/kfs-build.properties Optionally defines ${shared.external. build.properties} OVERRIDES build/project/ *.properties

41. Build property customization • institution.* properties are customization hooks • Override properties in ~/kfs-build.properties or shared external build properties file

42. Cash Control Document

43. Customization example 1 • Modify rule to force org doc code to be a prefix of the description • Rule will only be triggered on routing (and, as a side effect, approvals, because of chaining)

44. Customization example 1 How? • Write a new rules class • Override the DD bean • Override the module bean • Define new build properties • Redeploy application

45. Customization example 1 – Step 1 KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

46. Customization example 1 – Step 1 @Override protected boolean processCustRouteDocRules(Document doc) { if (!orgCodePrefixOfDocDesc(doc)) { registerErrorOnWebPage(); return false; } return super.processCustRouteDocRules(doc); }

47. Customization example 1 – Step 2 KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

48. Customization example 1 – Step 2 <bean id="CashControlDoc“ parent="CashControlDoc-parentBean"> <property name="businessRulesClass" value="<cust_pkg>.CustCashContDocRule"/> </bean>

49. Customization example 1 – Step 3 KFS/Application Module Configs spring.source.files build property dataDictionaryPackages property DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers Properties in DD doc entry

50. Customization example 1 – Step 3 edu/school/kfs/module/ar/spring-ar-overrides.xml <bean id="arModuleConfiguration" parent="arModuleConfiguration-parentBean"> <property name="dataDictionaryPackages"> <list> <value>org/kuali/kfs/module/ar/bo/datadict</value> <value>org/kuali/kfs/module/ar/doc/datadict</value> <value>edu/school/kfs/module/ar/doc/datadict</value> </list> </property> </bean>