This guide lists all the points of customization and configuration for an implementing institution.
For the purposes of this documentation:
- Configuration - requires no source code changes
- Customization - requires source code changes
WHERE AN IMPLEMENTING INSTITUTION CAN CONFIGURE AND CUSTOMIZE THE SYSTEM
Note that all the configuration and customization points listed here are designed to be set by the implementing institution. They are built such that these modifications will not introduce breaking changes in future updates or upgrades of the application.
Business rules are also designed to be easily customizable by implementing schools. This is accomplished by introducing new, school-specific classes, rather than discarding or modifying the existing Kuali classes. School specific classes can completely re-implement functionality from the provided those provided or they can choose to override and implement only the specific methods that require modification. The only prerequisite for extending or replacing functionality via new classes is that the new classes must adhere to the same Interface as the original, Kuali provided classes. The system is configured via an XML file to refer to the newly created classes.
VALUES, RANGES, ALLOWED OR DISALLOWED VALUES FOR BUSINESS RULES
- The System Parameters and System Rules both store values that are used by the system to perform business logic. They both support single and multiple values.
- System Paramters are used to store values that can be retrieved and referred to by application code.
- System Rules can be used to do value comparison and rule application for simple tests like IN SINGLEVALUE, IN GROUP, NOT IN SINGLEVALUE, NOT IN GROUP.
- System Rules can also be used for reference values, like System Parameters
- Existing System Parameters and System Rules can be altered via the appropriate Maintenance Documents.
- This is configuration
- New System Parameters and System Rules can be created with the appropriate Maintenance Documents. Using new System Parameters and System Rules will require changes to code.
- This is both configuration and customization
- Note that each document's functional specification page should list out any System Parameters and System Rules used by that document
ERROR MESSAGE STRINGS - applicationResources.properties
- Error messages are displayed to users when a Business Rule fails. They are stored as key-value pairs in the applicationResources.properties file.
- Each message has a unique name as the key, and the string display message as the value.
- This is a customization. It requires altering a properties file and changes can only be applied when the application is restarted.
- Stores text-messages by key to be presented in the UI.
FIELD NAMES, LABELS, SIZE, SHAPE, VALIDATION
- Everything there is to know about how a field should be displayed, and what are the constraints on its size, shape, etc. is contained within the Data Dictionary (DD) XML file.
- This is where the bulk of the institutional-customization should happen.
- This is a customization because it involves altering source files (XML files). Changes to these files require restarting the application before the new values can be used.
- BusinessObject DD files
- for example, Account.xml
- holds various attributes about Business Objects (BOs)
- size & shape (text or numeric, maximum 7 digits, etc)
- required or not
- validation rules (if any)
- display name & long-english descriptions
- lookup configuration
- inquiry configuration
- control type to use on a UI display (if any)
- Document DD XML files
- for example, KualiTransferOfFundsDocument.xml
- holds various attributes about documents
- document class
- authorizer class
- rule class
- basic features of the BusinessObject DD attribute support
MAINTENANCE DOCUMENT DISPLAY, VALIDATION, DEFAULTS, ETC.
- Most of the functionality provided by maintenance documents, how they are displayed, what the default values are, what kind of default rules checking occurs, etc. is controlled in the DD Maintenance Document XML files.
- These files also contain what Business Rules Class is used to enforce business rules on the maintenance documents.
- These files also contain declarations of what sub-objects must pass an existence test.
- These files also contain declarations of what System Rules should be applied against what members. This only works for simple rules (i.e., IN VALUE LIST, NOT IN VALUE LIST), but it doesn't require touching any code if your needs fit within this constraint.
- This is a customization because it involves altering source files (XML documents).
- Business Object Maintenance XML Documents
- for example, AccountMaintenanceDocument.xml
- contains various attributes & configurations about the maintenance documents for a BO, including:
- business rules to run - specified by the contents of the <businessRulesClass /> element
- authorization rules to use - sepified by the contents of the <documentAuthorizerClass /> element
- workflow document type name - specified by the contents of the <documentTypeName /> element
- locking keys - specified by the contents of the <lockingKeys /> element and its children
- existence/active checks to run - specified by the contents of the <defaultExistenceChecks /> element and its children
- what sections to display, how fields are grouped into sections - specified by the contents of the <maintainableSections /> element and its children
- what fields to display - specified by the <maintainableField /> elements, contained within <maintainableSection />
- required flag - specified by the required attribute of the <maintainableField /> element
- readOnly display - specified by the readOnly attribute of the <maintainableField /> element
BUSINESS RULE CUSTOMIZATIONS
For simple size, shape, required, default-value, existence tests, or simple System Rule tests, these can all be declared in the different data dictionary files:
- Business Object Data Dictionary Files
- These files map straight to a business object; therefore, values in these files are global in a sense since many documents can reference this single BO DD file.
- This enables re-use of the settings; however, in some cases the global settings will not work, and the settings are specific to the document. The next two places solve this issue.
- Maintenance Document Data Dictionary Files
- For maintenance document specific contexts that cannot be handled by Business Object Data Dictionary files
- Example: AccountMaintenanceDocument.xml file, described above.
- Transactional Document Data Dictionary Files
- For transactional document specific contexts that cannot be handled by Business Object Data Dictionary files
- Example: KualiInternalBillingDocument.xml file, described above.
- Business Object Data Dictionary Files
For complex rule enforcement, that cannot be handled through the methods listed above, these business rule classes can be completely replaced. This replacement is easily handled by the "plugability" of the document data dictionary files.
- This is a customization because it involves altering source files (Java files)
- Business Rule Classes
- The classes that ship with Kuali do default business rule implementations. An implementing school can completely replace these with their own business rule classes, to perform different rules.
- As an example, the AccountMaintenanceDocument.xml includes the following element:
- Changing these Class names to some other custom class would cause the system to use this new class for the business rules, rather than the class that ships with the Kuali product.
- Likewise, the Transactional Document Data Dictionary files (i.e. KualiTransferOfFundsDocument) have this plug-in capability
CONTRACT AND GRANT FUND GROUP VS. SUB-FUND GROUP CUSTOMIZATION
Institutions implementing the Kuali Financial System may treat Contracts and Grants as either a Fund Group or a Sub-Fund Group. Customization from Sub-Fund Group (default) to Fund Group will require a change to the java code.
Look for the method named isInCg() in the Account.java object and follow the directions there: