Post on 24-Jan-2016
Customizing KFS Business RulesHeather Stapleton, Indiana University Warren Liang, University of California-Irvine November 17th, 2009
• System Parameters• Maintenance Tables• Extending KFS Classes
– Presentation Controllers– Authorizers– Rules
• Granular Validations
Ways to Customize KFS
Identity Management (KIM)
Tuesday @ 11amSalon B
Workflow(KEW)
Wednesday @ 2pmConf 3+4
Parameters - Purpose
• Customize based on YOUR policies• Controlled by users• Externalize constants• Maintained in tables• Easy to use
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
Parameter Lookup
Parameter Lookup - Namespace
Parameter Lookup – Component
Parameter Lookup - Component
Parameter Lookup – App Namespace
Parameter Lookup – App Namespace
Parameter Lookup – Type Code
Parameter Examples
On/Off Switches
Parameter Examples
Defaults
Parameter Examples
Requiredness
Parameter Examples
Maintenance Tables
Maintenance Tables
Maintenance Tables
Maintenance Tables
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
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
Configuration overview
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
dataDictionaryPackages property
Properties in DD doc entry
Document Presentation Controllers
• Determines whether a document is in a state that would allow certain actions to be performed
• Decisions not based on user
Document Presentation Controllers
interface DocumentPresentationController {
Set<String> getDocumentActions(Document document);
boolean canInitiate(String docTypeName);
}
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
Presentation Controller/Authorizer
Presentation Controllers Document Authorizers
Document Rules
• Performs validation before actions are taken • Primarily used for maintenance documents,
but also for some transactional documents
Document Rules
interface RouteDocumentRule extends BusinessRule { boolean processRouteDocument(Document document);
}
DocumentRuleBase
• Base implementation for most of these interfaces is DocumentRuleBase
• Contains a customization hook to add document-specific logic
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;}
Configuration overview
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
Data Dictionary
• Repository of metadata for documents and business objects
• Comprised of Spring beans• Configures how to validate a document
Data Dictionary Overriding
• Abstract parent bean definition and “concrete” inheriting bean
• Customize/override the concrete beans
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"/>
Configuration overview
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
Module Configuration
• Maintains metadata related to an application module– List of DD directories
• Override the Module Configuration Bean if adding new DD files
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>
Configuration overview
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
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.
Build property customization
~/kfs-build.properties
${shared.external.build.properties}
build/project/*.properties
OVE
RRID
ESOptionallydefines
Build property customization
• institution.* properties are customization hooks
• Override properties in ~/kfs-build.properties or shared external build properties file
Cash Control Document
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)
Customization example 1
How?1. Write a new rules class2. Override the DD bean3. Override the module bean4. Define new build properties5. Redeploy application
Customization example 1 – Step 1
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
Customization example 1 – Step 1
@Overrideprotected boolean processCustRouteDocRules(Document doc) {
if (!orgCodePrefixOfDocDesc(doc)) { registerErrorOnWebPage(); return false; } return super.processCustRouteDocRules(doc);}
Customization example 1 – Step 2
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
Customization example 1 – Step 2
<bean id="CashControlDoc“ parent="CashControlDoc-parentBean"> <property name="businessRulesClass" value="<cust_pkg>.CustCashContDocRule"/>
</bean>
Customization example 1 – Step 3
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
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>
Customization example 1 – Step 4
KFS/Application Module Configs
DD Spring Beans(Document Entries)
Doc rules, pres, cont.,authorizers
spring.source.files build property
Properties in DD doc entry
dataDictionaryPackages property
Customization example 1 – Step 4
• In ~/kfs-build.properties, define the following:institution.spring.source.files=,edu/school/kfs/
module/ar/spring-ar-overrides.xml
• Note the leading comma
Customization example 1
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
Logical configuration diagram
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
Configuration overview
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
Aqua-colored components shown on previous slide
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
DD Validation beans
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
DD Validation beans
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
DD Validation beans
<bean id="AccountingDocument-debitsAndCreditsBalanceValidation" class=“<package>.DebitsAndCreditsBalanceValidation" abstract="true" />
The class implements the Validation interface.
Validation beans should be abstract
List of Validations
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
List of Validations
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
List of Validations
<bean id="TransferOfFunds-routeDocumentValidation" parent="TransferOfFunds-routeDocumentValidation-parentBean" />
<bean id="TransferOfFunds-routeDocumentValidation-parentBean" parent="CompositeValidation" abstract="true">
<property name="validations"> <list> <!-- some validations omitted --> <bean parent="AccountingDocument- debitsAndCreditsBalanceValidation"/> <bean parent="TransferOfFunds- fundGroupsBalancedValidation"/> </list> </property></bean> Note: beans in list use “parent”
Event to list-of-Validation mapping
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
Event to list-of-Validation mapping
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
Event to list-of-Validation mapping
<bean id="TransferOfFundsDocument-validations" parent="TransferOfFundsDocument-validations-parentBean"/>
<bean id="TransferOfFundsDocument-validations-parentBean"
class=“<package>.MapFactoryBean"> <property name="sourceMap"> <map> <entry> <key> (pkg).AttributedRouteDocumentEvent </key> <value> TransferOfFunds-routeDocumentValidation </value> </entry> ...
DD Document Entry
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
DD Document Entry
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
DD Document Entry
<bean id="TransferOfFundsDocument" parent="TransferOfFundsDocument-parentBean"/>
<bean id="TransferOfFundsDocument-parentBean“ abstract="true“ parent="AccountingDocumentEntry"> <property name="businessRulesClass“ value=“<package>.AccountingRuleEngineRuleBase"/> <property name="validationMap“ ref="TransferOfFundsDocument-validations"/>
Customization example 2
• Modify the ToF document to only allow documents that have credits and debits totals of $100
Transfer of Funds Document
Customization example 2
How?1. Write new Validation implementation2. Define Validation abstract bean definition3. Override the Validation list4. Define new build properties5. Redeploy application
Customization example 2 – Step 1 & 2
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
Customization example 2 – Step 1 & 2
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
Customization example 2 – Step 1
edu.school.kfs.fp.document.validation.impl.CustomTransferOfFundsHundredDollarValidation
public boolean validate(AttributedDocumentEvent event) {
if (!debAndCred100USD(acctDocForValidation)) { registerError(); return false; } return true;}
Customization example 2 – Step 2
<bean id="TransferOfFundsDocument-debitsAndCreditsAreHundredDollars" class=“<package>.CustomTransferOfFundsHundredDollarValidation" abstract="true" />
Customization example 2 – Step 3
DocumentEntry in DD
Event-to-ValidationsMapping
List ofRoute Validation
References
List ofValidation Refs
for event X
…Route
doc
eve
nt
Event X (e.g.
Save, Approve)
Validation 1
Validation 2
Validation 3
Validation N
…
Customization example 2 – Step 3
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
Customization example 2 – Step 3
<bean id="TransferOfFunds-routeDocumentValidation" parent="TransferOfFunds-routeDocumentValidation-parentBean" >
<property name="validations"> <list> <!-- some validations omitted --> <bean parent="TransferOfFundsDocument- debitsAndCreditsAreHundredDollars“/> <bean parent="AccountingDocument- debitsAndCreditsBalanceValidation"/> <bean parent="TransferOfFunds- fundGroupsBalancedValidation"/> </list> </property></bean>
Customization example 2 – Step 4
KFS App
Module Configuration
spring.source.filesbuild property
dataDictPackages
List of Validations
Non-DD Spring Beans
Validationbeans
DD Spring Beans
DocumentEntry
Event-to-Validations-
Mapping
Spring ref
Spring ref
Ref by name
Configuration example 2 – Step 4
• Add the following property to ~/kfs-build.properties
institution.spring.source.files=,edu/school/kfs/fp/document/validation/configuration/CustomFinancialProcessingValidators.xml,edu/school/kfs/fp/document/validation/configuration/CustomTransferOfFundsValidation.xml
Note the leading comma
Configuration example 2
Patches
• Patch files describing both examples have been attached in the Kuali wikihttps://test.kuali.org/confluence/x/uYCUDQ
• Note that no files delivered with KFS were modified!
Questions?
Thank you