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

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;}








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"/>








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>








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)


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








@Overrideprotected boolean processCustRouteDocRules(Document doc) {

if (!orgCodePrefixOfDocDesc(doc)) { registerErrorOnWebPage(); return false; } return super.processCustRouteDocRules(doc);}









<bean id="CashControlDoc“ parent="CashControlDoc-parentBean"> <property name="businessRulesClass" value="<cust_pkg>.CustCashContDocRule"/>

</bean>









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>









• In ~/kfs-build.properties, define the following:institution.spring.source.files=,edu/school/kfs/

module/ar/spring-ar-overrides.xml

• Note the leading comma


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

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

…


KFS App


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



References


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



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


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



References


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



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


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>  <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



References


for event X

…Route

doc

eve

nt

Event X (e.g.

Save, Approve)

Validation 1

Validation 2

Validation 3

Validation N

…


KFS App



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


Mapping

Spring ref

Spring ref

Ref by name


<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



References


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



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


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"/>


• Modify the ToF document to only allow documents that have credits and debits totals of $100

Transfer of Funds Document


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



References


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



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


Mapping

Spring ref

Spring ref

Ref by name


edu.school.kfs.fp.document.validation.impl.CustomTransferOfFundsHundredDollarValidation

public boolean validate(AttributedDocumentEvent event) {

if (!debAndCred100USD(acctDocForValidation)) { registerError(); return false; } return true;}


<bean id="TransferOfFundsDocument-debitsAndCreditsAreHundredDollars" class=“<package>.CustomTransferOfFundsHundredDollarValidation" abstract="true" />


DocumentEntry in DD



References


for event X

…Route

doc

eve

nt

Event X (e.g.

Save, Approve)

Validation 1

Validation 2

Validation 3

Validation N

…


KFS App



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


Mapping

Spring ref

Spring ref

Ref by name


<bean id="TransferOfFunds-routeDocumentValidation" parent="TransferOfFunds-routeDocumentValidation-parentBean" >

<property name="validations"> <list>  <bean parent="TransferOfFundsDocument- debitsAndCreditsAreHundredDollars“/> <bean parent="AccountingDocument- debitsAndCreditsBalanceValidation"/> <bean parent="TransferOfFunds- fundGroupsBalancedValidation"/> </list> </property></bean>


KFS App



dataDictPackages

List of Validations

Non-DD Spring Beans

Validationbeans

DD Spring Beans

DocumentEntry


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!

https://test.kuali.org/confluence/x/uYCUDQ

Questions?

Thank you

Documents

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