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

2. System Parameters Maintenance Tables Extending KFS Classes – Presentation Controllers – Authorizers – Rules Granular Validations Ways to Customize KFS

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

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

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/ApplicationModule Configs DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers spring.source.files build property dataDictionaryPackages property 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 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 ControllersDocument 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/ApplicationModule Configs DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers spring.source.files build property Properties in DD doc entry dataDictionaryPackages property

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 <property name="businessRulesClass“ value=“.CashMgmtDocRule"/> <property name="documentAuthorizerClass“ value=“.CashMgmtDocAuth"/> <property name="documentPresentationControllerClass“ value=“.CashMgmtDocPresContBase"/>

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

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.FinancialSystemModuleConfiguration" abstract="true"> org/kuali/kfs/module/ar/bo/datadictionary org/kuali/kfs/module/ar/doc/datadictionary

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

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 ${shared.external. build.properties} build/project/ *.properties OVERRIDES Optionally defines

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? 1.Write a new rules class 2.Override the DD bean 3.Override the module bean 4.Define new build properties 5.Redeploy application

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

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/ApplicationModule Configs DD Spring Beans (Document Entries) Doc rules, pres, cont., authorizers spring.source.files build property Properties in DD doc entry dataDictionaryPackages property

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

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

50. Customization example 1 – Step 3 edu/school/kfs/module/ar/spring-ar-overrides.xml org/kuali/kfs/module/ar/bo/datadict org/kuali/kfs/module/ar/doc/datadict edu/school/kfs/module/ar/doc/datadict

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

52. Customization example 1 – Step 4 In ~/kfs-build.properties, define the following: institution.spring.source.files=,edu/school/kfs/modu le/ar/spring-ar-overrides.xml Note the leading comma

53. Customization example 1

54. Granular Validations Intended for easy customization of rules Breaks rules down into sub-rules Sub-rules implement Validation interface Relies on composition, not inheritance Event-to-list-of-Validations mappings Primarily for accounting docs https://test.kuali.org/confluence/x/9ABEAw

55. Logical configuration diagram Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

56. Configuration overview KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans Aqua-colored components shown on previous slide DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

57. DD Validation beans Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

58. DD Validation beans KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

59. DD Validation beans.DebitsAndCreditsBalanceValidation " abstract="true" /> The class implements the Validation interface. Validation beans should be abstract

60. List of Validations Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

61. List of Validations KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

62. List of Validations <bean parent="AccountingDocument- debitsAndCreditsBalanceValidation"/> <bean parent="TransferOfFunds- fundGroupsBalancedValidation"/> Note: beans in list use “parent”

63. Event to list-of-Validation mapping Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

64. Event to list-of-Validation mapping KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

65. Event to list-of-Validation mapping.MapFactoryBean"> (pkg).AttributedRouteDocumentEvent TransferOfFunds-routeDocumentValidation...

66. DD Document Entry Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

67. DD Document Entry KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

68. DD Document Entry <bean id="TransferOfFundsDocument-parentBean“ abstract="true“ parent="AccountingDocumentEntry"> <property name="businessRulesClass“ value=“.AccountingRuleEngineRuleBase"/> <property name="validationMap“ ref="TransferOfFundsDocument-validations"/>

69. Customization example 2 Modify the ToF document to only allow documents that have credits and debits totals of $100

70. Transfer of Funds Document

71. Customization example 2 How? 1.Write new Validation implementation 2.Define Validation abstract bean definition 3.Override the Validation list 4.Define new build properties 5.Redeploy application

72. Customization example 2 – Step 1 & 2 Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

73. Customization example 2 – Step 1 & 2 KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

74. Customization example 2 – Step 1 edu.school.kfs.fp.document.validation.impl.CustomTran sferOfFundsHundredDollarValidation public boolean validate(AttributedDocumentEvent event) { if (!debAndCred100USD(acctDocForValidation)) { registerError(); return false; } return true; }

75. Customization example 2 – Step 2.CustomTransferOfFundsHundredDolla rValidation" abstract="true" />

76. Customization example 2 – Step 3 Document Entry in DD Event-to- Validations Mapping List of Route Validation References List of Validation Refs for event X … Route doc event Event X (e.g. Save, Approve) Validation 1 Validation 2 Validation 3 Validation N …

77. Customization example 2 – Step 3 KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

78. Customization example 2 – Step 3 <bean parent="TransferOfFundsDocument- debitsAndCreditsAreHundredDollars“/> <bean parent="AccountingDocument- debitsAndCreditsBalanceValidation"/> <bean parent="TransferOfFunds- fundGroupsBalancedValidation"/>

79. Customization example 2 – Step 4 KFS App Module Configuration spring.source.files build property dataDictPackages List of Validations Non-DD Spring Beans Validation beans DD Spring Beans Document Entry Event-to- Validations- Mapping Spring ref Ref by name

80. Configuration example 2 – Step 4 Add the following property to ~/kfs- build.properties institution.spring.source.files=,edu/school/kfs/fp/d ocument/validation/configuration/CustomFinancialPr ocessingValidators.xml,edu/school/kfs/fp/document/ validation/configuration/CustomTransferOfFundsVali dation.xml Note the leading comma

81. Configuration example 2

82. Patches Patch files describing both examples have been attached in the Kuali wiki https://test.kuali.org/confluence/x/uYCUDQ Note that no files delivered with KFS were modified!

83. Questions? Thank you