1. Installing, Configuring & Customizing KFS Ailish Byrne (Indiana University) Naser Alavi (Michigan State University)

2. Oracle 10.1+ MySQL 5.0+ Data Access Tools ?? Data Access Objects Object Relational Bridge JDBC Database Platform Implementation p6spy & log4j

3. Service Tier Tools Data Access Objects log4j Services Business Rules Transaction Data Dictionary Workflow POJOsPOJOs POJOsPOJOs

4. JSP Web Client Tools Services log4j Dispatch Actions Request Processor FormsForms FormsForms POJOsPOJOs POJOsPOJOs HTML

5. Batch Tools Scheduler Service log4j Job Listener Job Step 1 Step 2 Step 3 JDBC Jobstore Scheduler

6. Other Tools Development & Testing IDE, e.g. Eclipse 3.2+ KFS test framework based on Junit 3.8.1 Continuous Integration, e.g. Anthill Pro 2.50+ Production Application Server, e.g. Tomcat 5.5.16+ Web Server, e.g. Apache 2.0.55+ Load Balancer, Zeus ZXTM-lb

7. Evaluation: Database Setup Install appropriate version of a supported database Install JDBC drivers Configure database import/export tool via impex-build.properties Perform initial setup steps Run bootstrap target Import demo data set

8. Import Flow

9. Evaluation: Environment Setup Configure build process via kuali- build.properties Set up java, ant, tomcat, and optionally Eclipse Run dist-local (+ make-source, if no IDE) Start tomcat

10. Build Files User properties Institution shared properties Project build.properties build.xml build directory –external –project

11. Dist Flow

12. build/external SourceDestination appserver/*.jar${appserver.lib.dir} appserver/carol.properties${appserver.classes.dir} appserver/context.xml${appserver.localhost.dir} or META-INF directory in war work/*${external.work.directory} log4j.properties${settings.directory} security.properties${security.directory}

13. build/project SourceDestination configuration.properties${source.directory} spy.properties${source.directory} web.xml${webinf.directory} help.zip${help.directory} rice- - licenses.zip ${licenses.directory}/rice rice- -web.zip${webroot.directory}

14. Test Flow

15. Funcnical Implementation Questions ?Should we use workflow for other applications ?Will our security office frown on the encryption strategy ?How will we source institutional user data ?How and when will our batch schedule run ?Should our static content be release independent and who will maintain it

16. Configuration & Customization: build.properties Deployment Database platform Batch User Maintenance Authentication Spring Files User Interface User Messages

17. Configuration & Customization: Spring: Bean Overrides User Service Authentication Service Mail Service Encryption Service Modules

18. Configuration & Customization: web.xml Workflow CAS Filters Listeners

19. Configuration & Customization: Spring: Module Definition Users Authorization Data Dictionary Database Batch Javascript

20. Configuration & Customization: Data Dictionary Labels Presence & Order of Fields Custom Fields Inquiry Association Authorization Maintainables Business Rules Authorization

21. Functional Implementation Questions ?What will our chart and organization hierarchy look like ?Will we use flexible offsets ?Do we have additional attributes that we need to represent in KFS ?How can we change workflow to meet our approval process

22. Configuration & Customization: Extended Attributes Module Spring bean override Database object(s) Extension class descriptor & base descriptor override Extension business object & rule override Extension BO DD entry, base BO and document DD override Optional control values & AJAX

23. Configuration & Customization: Workflow Document Types –Exception, blanket approval, etc. workgroups –Route nodes / path –Search configuration Rules / Searching –Add templates / modify existing templates –Modify / add XML attribute definitions –Extend and customize java attributes

24. Configuration & Customization: Parameters Configuration –Exception mailing lists –Authorized groups –Derivations Validation: simple and compound constraints Relative help URLs

25. Implementation Database Setup –Import bootstrap data set –Review data setup page for delivered data description and dependency information –Determine what you will load through UI vs other –Use the post-data load encryption process as needed for data not loaded through UI Environment Setup –Revisit build properties –Wrap or replace KFS build

26. Maintaining Customizations Additions should reside outside the org.kuali package Do not modify delivering files (data dictionary, OJB, spring) – override them When you need to modify delivered files, use the keyword: INSTITUTIONAL CUSTOMIZATION (in comment appropriate for file type) Track modifications to delivered document types, parameters, workgroups Version control or other comparison tool to assist with merge of modifications to delivered files

27. Upgrade Process Get distribution, point at your prior version, run delivered code upgrade process Use delivered process to generate database upgrade script, review & execute Branch your current development version, replace custom code with the distribution Sync and reapply changes

28. Customizing Kuali Outline: System Parameters Business Rules Authorization Pre-Rules

29. System Parameters Allow institutions to customize out of the box business rules based on their own policies Controlled by functional users via maintenance documents Externalize constants out of the code Maintained in System Parameters Tables Convenient service and evaluator methods are provided for developers to access and use the constant values in business rules validations

30. System Parameters Use Cases May be used in: –Business rules checks –Runtime changes to values displayed within the application without a restart of the application server May not be used in: –System configuration values that can’t be represented as constants/literals in the code –Core constants that will not change –Spring XML configuration files –OJB XML descriptor files

31. System Parameter Tables Parameter (SH_Param_T) Parameter Namespace (SH_Param_NMSPC_T) Parameter Type (SH_PARM_TYP_T) Parameter Detailed Type (SH_PARM_DTL_TYP_T)

32. System Parameter Tables

33. Parameter Namespace Table (SH_PARM_NMSPC_T) High-level classification that allows the association of parameters with a particular application and module Namespace Code (primary key) –Format is Application-Module, KFS-FP (KFS Financial Processing), KR-NS (Rice Nervous System), KFS-SY (KFS System Wide) Namespace Name Active Indicator

34. Parameter Type (SH_PARM_TYP_T) High-Level classification that allows the grouping of parameters by functional type Type Code (primary key) Type Name –CONFG (Configuration) –VALID (Document Validation) –AUTH (Authorization) –HELP (Help) Active Indicator

35. Parameter Detailed Type Table (SH_PARM_DTL_TYP_T) Entities or Components such as: – Maintenance tables – Transactional documents – Batch steps Namespace Code (primary key) Detailed Type Code (primary key) Detailed Type Name Active Indicator

36. Parameter Table (SH_PARM_T) A single record has a composite key made up of: –Namespace Code (Module Code) A group used to organize various parameter records into logical functional units. –KFS-PA, KFS-GL –Detailed Type Code (Component) Entities such as maintenance tables or transactional documents and batch steps –PaymentRequest, ExtractPdpStep –Name The name identifying the parameter – ACCOUNTS_PAYABLE_GROUP

37. Parameter Table (SH_PARM_T) Namespace Code (primary key) Detailed Type Code (primary key) Name (primary key) Type Code Workgroup Value Description Constraint (values allowed or disallowed)- must be A or D

38. Parameter Business Object public class Parameter extends PersistableBusinessObjectBase { … private String parameterNamespaceCode; private String parameterDetailTypeCode; private String parameterName; private String parameterValue; private String parameterDescription; private String parameterTypeCode; private String parameterConstraintCode; private String parameterWorkgroupName; private ParameterNamespace parameterNamespace; private ParameterType parameterType; private ParameterDetailType parameterDetailType; …

39. Accessing System Parameters

40. System Parameters Lookup

41. Parameters Module Codes

42. Parameters Type Codes

43. Parameters Lookup Example

44. Parameter Example

47. Parameters Maintenance Only KUALI_PARAMETER_MAINTAINERS workgroup members can initiate: –Parameter namespace –Parameter Type –Parameter Detailed Type –Parameter Members of a workgroup are authorized to maintain parameters associated with that workgroup. –Changes to any other Parameter field except the value and operation will be routed to KUALI_PARAMETER_MAINTAINERS

48. Parameter Developer Use Use the methods in the ParameterService to retrieve information about system parameters, value(s), or ParameterEvaluators. See the javadoc for – ParameterService/Impl – ParameterEvaluator/Impl –AlwaysSucceedParameterEvaluator/Impl.

49. ParameterService public boolean parameterExists(Class componentClass, String parameterName); public String getParameterValue(Class componentClass, String parameterName); public String getParameterValue(Class componentClass, String parameterName, String constrainingValue); public List getParameterValues(Class componentClass, String parameterName); public List getParameterValues(Class componentClass, String parameterName, String constrainingValue); public ParameterEvaluator getParameterEvaluator(Class componentClass, String parameterName);

50. ParameterEvaluator /** * This is a statefull wrapper for Parameters, which provides convenient methods to evaluate a constrained value against a Parameter. */ public boolean evaluationSucceeds(); public boolean constraintIsAllow(); public boolean evaluateAndAddError(Class businessObjectOrDocumentClass, String constrainedPropertyName);

51. Using System Parameter in TaxNumberService public boolean isValidTaxNumber(String taxNbr, String taxType) { … Integer defaultTaxNumberDigits = new Integer(parameterService. getParameterValue(VendorDetail.class, "DEFAULT_TAX_NUMBER_DIGITS")); if (taxNbr.length() != defaultTaxNumberDigits || !isStringAllNumbers(taxNbr)) { return false; } … }

52. Using System Parameters in TaxNumberService /** * Splits the set of tax number formats which are returned * from the rule service as a semicolon-delimited String * into a String array. * * @return A String array of the tax number format regular * expressions. */ public String[] parseSSNFormats() { if (ObjectUtils.isNull(taxNumberFormats)) { taxNumberFormats = parameterService.getParameterValues(VendorDetail.class, "TAX_SSN_NUMBER_FORMATS"); } return taxNumberFormats.toArray(new String[] {}); }

53. System Parameters Summary: Create and populate workgroup that should have maintenance permission Create parameter to control runtime system behavior or to define legal/illegal values

54. Customizing Kuali Outline: System Parameters Business Rules Authorization Pre-Rules

55. Customizing Payment Request Document Case Study Check for duplicated Payment Requests before validating business rules –In case of duplication give the user a warning and the option for continue or cancel Check the pay date before routing Customize the rendering of the tabs and buttons on the page based on the document status

56. Customizing Payment Request Document Case Study The functionality was provided through customizing codes in: Payment Request Doc DD XML Payment Request Rule Payment Request Authorizer Payment Request Pre-Rule (using question framework) Payment Request Action

57. Payment Request Document

60. Pluggable Business Rules Class Pluggable through DD Since written in Java, they are much more expressive than just matching Has access to all Kuali services Extensive code reuse through inheritance and services

61. Business Rule Framework DocumentRuleEvent W Interface Request Call rule interface method Generate event KualiRuleService Busines Rule Impl Implemnts rule interface? Get business rule impl Return errors Document.xml

62. Plugging Business Rules Class Register your business rule class with a document type. Specify the fully qualified class name of the business rule class with the tag in the document's data dictionary file.

63. Plugging Business Rules Class Example, PaymentRequestDocument.xml: org.kuali.module.purap.document.PaymentRequestDocument org.kuali.module.purap.rules.PaymentRequestDocumentRule

64. Rule Hierarchy Example

65. DocumentRuleBase Implements common checks that should be run after every event Rule implementations should extend this class Override the processCustom DocumentBusinessRule() methods defined in this class. Examples: –To define new save rules, override processCustomSaveDocumentBusinessRules() –To define new route rules, override processCustomRouteDocumentBusinessRules()

66. Associating Rules with Events and Using Common Services /** * This class contains all of the business rules that are common to all documents. */ public abstract class DocumentRuleBase implements SaveDocumentRule, RouteDocumentRule, ApproveDocumentRule, AddNoteRule, AddAdHocRoutePersonRule, AdHocRouteWorkgroupRule { private static UniversalUserService universalUserService; private static KualiModuleService kualiModuleService; private static DictionaryValidationService dictionaryValidationService; private static KualiWorkflowInfo workflowInfoService; private static KualiConfigurationService kualiConfigurationService;

67. Associating Rules with Events (Save Example) package org.kuali.core.rule; /** * Defines a rule which gets invoked immediately before a document gets saved. */ public interface SaveDocumentRule extends BusinessRule { /** * @param document * @return false if the rule fails */ public boolean processSaveDocument(Document document); }

68. DocumentRuleBase Rule Implementation public abstract class DocumentRuleBase implements SaveDocumentRule, … { public boolean processSaveDocument(Document document) { boolean isValid = true; isValid &= isDocumentOverviewValid(document); if (isValid) { isValid &= processCustomSaveDocumentBusinessRules(document); } return isValid; } protected boolean processCustomSaveDocumentBusinessRules (Document document) { return true; }

69. DocumentRuleBase Rule Implementation public abstract class DocumentRuleBase implements RouteDocumentRule, … { public boolean processRouteDocument(Document document) { boolean isValid = true; isValid &= isDocumentAttributesValid(document, true); if (isValid) { isValid &= processCustomRouteDocumentBusinessRules(document); } return isValid; } protected boolean processCustomRouteDocumentBusinessRules (Document document) { return true; }

70. DocumentRule Example public class PaymentRequestDocumentRule extends AccountsPayableDocumentRuleBase { @Override protected boolean processCustomSaveDocumentBusinessRules (Document document) { PaymentRequestDocument paymentRequestDocument = (PaymentRequestDocument) document; return processValidation(paymentRequestDocument); }

71. DocumentRule Example public class PaymentRequestDocumentRule extends AccountsPayableDocumentRuleBase { @Override protected boolean processCustomRouteDocumentBusinessRules(Document document) { boolean isValid = true; PaymentRequestDocument paymentRequestDocument = (PaymentRequestDocument) document; isValid &= validateRouteFiscal(paymentRequestDocument); isValid &= processValidation(paymentRequestDocument); isValid &= checkNegativeAccounts(paymentRequestDocument); return isValid; }

72. DocumentRule Example public class PaymentRequestDocumentRule extends AccountsPayableDocumentRuleBase { …. @Override public boolean processValidation(PurchasingAccountsPayableDocument purapDocument) { boolean valid = super.processValidation(purapDocument); valid &= processInvoiceValidation((PaymentRequestDocument)purapDo cument); valid &= processPurchaseOrderIDValidation((PaymentRequestDocument )purapDocument); valid &= processPaymentRequestDateValidation((PaymentRequestDocum ent)purapDocument); return valid; }

73. Customizing Kuali Outline: System Parameters Business Rules Authorization Pre-Rules

74. Document Authorizer Framework Determines who can initiate a document –Initiators in Doc DD XML How document fields are rendered What buttons are displayed Complex Rules in Document Authorizer Class Approvals in Workflow

75. Plugging Authorizer Class org.kuali.module.purap.document.PaymentRequestDocument org.kuali.module.purap.document.PaymentRequestDocument Authorizer KUALI_PURAP_ACCOUNTS_PAYABLE KualiPaymentRequestDocument PREQ

76. PaymentRequestDocument Authorizer Override hasInitiateAuthorization –Simple true/false value Override getEditMode –A map of mode -> value mappings. The JSP layer uses these mappings to determine how it should render the document Override getDocumentActionFlags –Returns an object with numerous boolean flags, indicating whether a button may be rendered

77. PaymentRequestDocument Authorizer @Override public boolean hasInitiateAuthorization(Document document, UniversalUser user) { String authorizedWorkgroup = SpringContext.getBean(ParameterService.class).getParameterValue (ParameterConstants.PURCHASING_DOCUMENT.class, PurapParameterConstants.Workgroups.WORKGROUP_ACCOUNTS_PAYABLE); try { return SpringContext.getBean(KualiGroupService.class).getByGroupName(a uthorizedWorkgroup).hasMember(user); } catch (GroupNotFoundException e) { throw new RuntimeException("Workgroup " + authorizedWorkgroup + " not found", e); }

78. PaymentRequestDocument Authorizer @Override public Map getEditMode(Document document, UniversalUser user, List sourceAccountingLines, List targetAccountingLines) { … Map editModeMap = super.getEditMode(document, user, sourceAccountingLines, targetAccountingLines); PaymentRequestDocument paymentRequestDocument = (PaymentRequestDocument)document; if (StringUtils.equals(paymentRequestDocument.getStatusCode(),Pura pConstants.PaymentRequestStatuses.INITIATE)){ editModeMap.put(PurapAuthorizationConstants.PaymentRequestEditM ode.DISPLAY_INIT_TAB, "TRUE"); } else { editModeMap.put(PurapAuthorizationConstants.PaymentRequestEditM ode.DISPLAY_INIT_TAB, "FALSE"); } return editModeMap; }

79. PaymentRequestDocument Authorizer The JSP uses the values in the edit mode map to determine how to render the document. Example from PaymentRequest.jsp:

80. PaymentRequestDocument Authorizer @Override public DocumentActionFlags getDocumentActionFlags(Document document, UniversalUser user) { DocumentActionFlags flags = super.getDocumentActionFlags(document, user); KualiWorkflowDocument workflowDocument = document.getDocumentHeader().getWorkflowDocument(); PaymentRequestDocument paymentRequestDocument = (PaymentRequestDocument)document; if (StringUtils.equals(paymentRequestDocument.getStatusCode(), INITIATE)){ flags.setCanSave(false); flags.setCanClose(false); flags.setCanCancel(true); } else { flags.setCanSave(true); } return flags; }

81. PaymentRequestAction (Continued) public ActionForward continuePREQ(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception { PaymentRequestForm preqForm = (PaymentRequestForm) form; PaymentRequestDocument paymentRequestDocument = (PaymentRequestDocument) preqForm.getDocument(); //preform duplicate check which will forward to a //question prompt if one is found ActionForward forward = performDuplicatePaymentRequestCheck(mapping, form, request, response, paymentRequestDocument); if (forward != null) { return forward; } …. }

82. PaymentRequestAction (Continued) private ActionForward performDuplicatePaymentRequestCheck(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response, PaymentRequestDocument paymentRequestDocument) throws Exception { ActionForward forward = null; HashMap duplicateMessages = SpringContext.getBean(PaymentRequestService.class).paymentReque stDuplicateMessages(paymentRequestDocument); // ask question if not already asked if (!duplicateMessages.isEmpty()) { Object question =request.getParameter(KFSConstants.QUESTION_INST_ATTRIBUTE_NAME ); if (question == null) { return this.performQuestionWithoutInput(mapping, form, request, response, PREQDocumentsStrings.DUPLICATE_INVOICE_QUESTION, duplicateMessages.get(PREQDocumentsStrings.DUPLICATE_INVOICE_QU ESTION), KFSConstants.CONFIRMATION_QUESTION, KFSConstants.ROUTE_METHOD, ""); }

83. PaymentRequestAction (Continued) Object buttonClicked = request.getParameter(KFSConstants.QUESTION_CLICKED_BUTTON); if ((PurapConstants.PREQDocumentsStrings.DUPLICATE_INVOICE_QUESTIO N.equals(question)) && ConfirmationQuestion.NO.equals(buttonClicked)) { // if no button clicked just reload the doc in the // INITIATE status and let the user to change the // input values paymentRequestDocument.setStatusCode(PurapConstants.PaymentRequ estStatuses.INITIATE); forward = mapping.findForward(KFSConstants.MAPPING_BASIC); } return forward; }

84. Customizing Kuali Outline: System Parameters Business Rules Authorization Pre-Rules

85. Pre-rules are invoked automatically by the framework before saving, routing, approving, and blanket approving a document.

86. Pre-Rules Use Cases Modification of values on the form –Auto-fill values –Setting default values –Deriving values based on other values Switching to another page – e.g. go to a confirmation page

87. Pre-Rules Framework Document Request Yes, continue action No Get pre-rules class Yes Document.xml Action Data Dictionary Service Pre-rules ok? Get pre-rules class Has pre-rules?

88. Plugging Pre-Rules Specify fully qualified class name for the Pre-rule implementation in the data dictionary XML file –Example: PaymentRequestDocument.xml org.kuali.module.purap.rules. PaymentRequestDocumentPreRules

89. PreRulesCheck Interface public interface PreRulesCheck { /** * Callback method from Maintenance action that allows checks to be done and response redirected via the PreRulesCheckEvent * * @param form * @param request * @param event * @return boolean indicating whether routing should stop or continue */ public boolean processPreRuleChecks(ActionForm form, HttpServletRequest request, PreRulesCheckEvent event); }

90. PreRulesContinuationBase This class simplifies clarifying user input prior to applying business rules. It mostly shields the classes that extend it from being aware of the web layer, even though the input is collected via a series of one or more request/response cycles.

91. PreRulesContinuationBase public abstract class PreRulesContinuationBase implements PreRulesCheck { protected String question; protected String buttonClicked; protected PreRulesCheckEvent event; protected KualiForm form; public abstract boolean doRules(Document document);

92. PreRulesContinuationBase public boolean processPreRuleChecks(ActionForm form, HttpServletRequest request, PreRulesCheckEvent event) { … try { result = doRules(event.getDocument()); } catch (IsAskingException e) { return false; } if (isAborting) { return false; } return result; }

93. PreRulesContinuationBase

94. PaymentRequestDocumentPre Rules /* Performs prompts and other pre business rule checks for the Payment request Document */ public class PaymentRequestDocumentPreRules extends AccountsPayableDocumentPreRulesBase { … @Override public boolean doRules(Document document) { boolean preRulesOK = true; PaymentRequestDocument preq = (PaymentRequestDocument) document; if ((!SpringContext.getBean(PurapService.class).isFullDocumentEntryComplete d(preq)) || (StringUtils.equals(preq.getStatusCode(), PurapConstants.PaymentRequestStatuses.AWAITING_ACCOUNTS_PAYABLE_REVIEW)) ) { if (!confirmPayDayNotOverThresholdDaysAway(preq)) { return false; } preRulesOK &= super.doRules(document); return preRulesOK; }

95. Summary System parameters –Provides on-the-fly configuration of certain components –Provides business rules validations based on matching values Authorizer –Determines who can initiate a document –How document fields are rendered & What buttons are displayed

96. Summary “Pluggable” business rules –Java-based implementation of rules that are more powerful than simple matching Pre-rules –Allows modification of form values prior to processing –Allows “redirection” to a different page

97. Questions? kualitestdrive@oncourse.iu.edu