Analysis JIRA:

Many of the items raised on the Inquiry analysis will apply to maintenance documents. They are both defined by similar data structures in the data dictionary and, ultimately, rendered by rowDisplay.tag.

 

 

KNS Feature

Implemented in KRAD

Notes

Ability to copy another business object by clicking a link from the lookup. Copies all the attributes except for the primary key, ver number, and object ID fields by default.
(Why can't we do this from a link on the inquiry page?) 

 

Different implementation will be needed, since object ID and version number are no longer required.

Upon copy, blanks out any fields determined to be "restricted" based on input from the document authorizer.  
Ability to delete a business object. (Though usually no link is displayed to perform this operation.)  
Ability to edit an existing business object.  
   
Ability to pass in properties on the HTTP request to pre-populate fields on the document. If overrideKeys=field1,field2 not specified, then only parameters with the names of the primary key fields will be used.  
Calls into the Maintainable to populate any blank fields which have defaults after a New or Copy document is created.  
Automatically displays the left "Old" side when editing or copying a business object.  
In any document where the Old/New sections are both displayed, highlight (yellow asterisk in the KNS) fields which have been changed from their "old" values.  
Ability to block the creation of new objects of a given type at the data dictionary level. (allowsNewOrCopy)  
Knowledge of the fields and collections present in sections (tabs) so that error messages will be displayed under the correct heading.  
Auto-opening of tabs which have errors when redisplaying the document after a form submit which performs validation.  

Security mechanism which required the registration of all properties displayed on the form. The standard form control tags pushed their field names into a session scope variable. Upon form re-posting, only attributes registered in this way would be posted back to the business object. This was done due to the way that Struts (and now Spring) auto-bind values based on dot-notation. Without this, it is possible to create custom form widgets in the browser and change internal properties of business objects which should have been non-editable by the end user.

(A call like: ${kfunc:registerEditableProperty(KualiForm, field.propertyName)} is used to perform this function from rowDisplay.tag)

The KualiMaintenanceForm also registers a number of properties which are not editable, but which will be present on the form. These are used to prevent the security system from blowing the page for these standard fields. That map is also used to prevent the values on the form from being updated in the objects upon posting of the form.

  
Rendering of the "* = required field" heading when the document was in an editable format. (Probably not needed due to dynamic feedback in KRAD.)  

Display of maintenance document sections in collapsable tabs.

  
Ability to expand/collapse tabs one at a time or all at once.  
Memory of the state of the tabs on a given document across page refreshes.  
Ability to specify the default open/closed state of the document-specific tabs.  
Ability to include additional non-standard sections via a DD-specified file. The file would be included via the <jsp:include> tag.  
Ability to configure help links in the section headers via the DD.  
Ability to hide sections conditionally via the presentation controller.  
Ability to make entire sections conditionally read-only via the presentation controller.  
Ability to include additional JS files in the page via DD configuration.  
(warning) documentOverview.tag/rowDisplay.tag : Detection of whether the screen is a maintenance document by checking if the Struts Form class == KualiMaintenanceForm.  
Ability to set the title of the tab sections via the DD.  
Ability to set an ID for sections for use by the presentation controller and document authorizer when setting sections as hidden or read only. If no ID is specified, the ID defaults to the tab's title. (This is not the HTML id used in the generated code.)  

Support for custom buttons on maintenance documents which only display on the "New" side and not when in read-only mode. They call back into the "refresh" method but with a custom action in one of the special URL-encoded fields. The custom action is manually inserted into the request parameter map passed to the Maintainable's processAfterPost() method.

  
Use of the control definitions in the business object DD files to render the fields.  
Recognizes properties which are sensitive when passed in for the "newWithExisting" action and assumes they are encrypted, decrypting them before passing them into the new business object. (Please don't support - we should never be passing sensitive information on URLs. If there is a need to do this, have it place the sensitive data in Session scope and have the passed value be some sort of GUID to retrieve it.) (There is also use of a special prefix in places to indicate that a value is encrypted: EncryptionService.ENCRYPTION_POST_PREFIX)  
Support for retrieving attachments which have been linked to properties on the business object itself. (I presume they have been linked to BLOB fields.)
There also seems to be support for attachment objects linked to collections within the BO. (See PersistableAttachment and PersistableAttachmentList)
  
Altering of behavior of the main Action when the generic docHandler method is used depending on the "command" passed (displayActionListView, displayDocSearchView, displaySuperUserView, displayHelpDeskActionListView, initiate)  
Special handling to support multiple value lookups and mapping of the properties from the business object being looked up into the child records actually referenced by the "global" document. This is handled via the fairly overloaded "refresh" method. MV lookups only return the OBJ_ID values, so the records need to be retrieved before the properties can be mapped. (question) How will this work in KRAD if the object being looked up does not implement the "GloballyUnique" interface?  
Support for collections within business objects, with base methods for handling the addition and deletion of lines from the collection.  

Special handling of the Struts populate command on the form to strip off the new/oldMaintainable prefix and push the resulting properties directly into the business objects. (Since the base function would to have been document.newMaintainableObject.boProperty.) This population is deferred to the maintainable's populateBusinessObject() method rather than using the Struts functions.

Now, the existing code applies the values to the "oldMaintainableObject" as well. This probably should not have been happening, as the old object should never be changed by UI code.

  
All incoming properties are handled as String objects. Data conversion errors are handled by storing the unconverted values in a "cachedValues" Map. This map is then used when re-displaying the page so that the data the user entered is not lost even though it may not be able to be stored in the data type on the business object. (E.g., letters in a KualiDecimal property.   
For lookups and inquiry buttons/links: Automatic passing of keys from related fields when the field is the last field in a multi-field foreign key. (E.g., retrieval and inclusion of the chartOfAccountsCode when performing a lookup on the accountNumber field.)  
Automatic setting of the primary key fields on the BO to read-only when the maintenance document is in edit mode (FieldUtils).  
Special case of above: Automatic setting of the principal name property to read only when the related principal ID field is part of the primary key.  
Automatic handling of field conversion values for building the quickfinders and direct inquiry buttons on attributes. Adds the necessary "document.newMaintainableObject." prefix.   

In maintenance document authorization checks, automatic stripping of the document/maintainable prefixes on property names to allow the permission definitions to only use the business object property name.

  
Automatic recognition of masked fields as sensitive. If so, it marks them as needing encryption when sent to the client and sets up their masked value for display.  
Support for specification of additional "onblur" functionality in the DD. (Assumes that any called functions exist in the standard libraries or are included in the additional script files also in the DD for the maintenance document.  
Ability to define a help URL on a per-field basis. (This should probably be retired in favor of KRAD popup help.)  
Ability to indicate that any property which is the code on a relationship for a BO class which implements KualiCode should display itself as a combination of Code + Name. (Used when document/field is in read-only mode.)  
Automatically clears out secure fields upon a BO copy operation.  
If a collection class under the main object implements the Inactivatable interface, then display, as part of the tab containing the collection) a show/hide inactive button.  
Skipped generating a required field error if the field was also marked as unconditionally read only. The assumption is that the field would be filled in by server-side code in these cases and not to inform the user since they could not do anything about it anyway.  
   
   
   
   
   
   
   
DD Properties  
Ability to control whether an BO can be deleted via maintenance document at the DD level. (I.e., disallow it regardless of permissions.)  
Allow for PK values to be preserved when copying a business object.  
Ability to control whether new BOs of a given type can be created via documents. (if not, you can only edit existing records.) We should consider moving this down to the BO DD files. This is really a property which affects the BO table, not any particular document which edits that object. Though, we may need it on the document as well.
Automatic detection, upon document submit, if there is already an existing document ENROUTE for the same business object.  
Ability to define a set of key fields used for detecting the above locking. (E.g., when the object has a user-visible unique key which is separate from the underlying primary key.) When not specified, the locking keys should default to the primary key.  
Ability to set the maintenance document base class. (Defaults to MaintenanceDocumentBase - but KFS does override this.)  
Ability to pre-process the HTTP request and manipulate the Struts form object directly rather than relying on the business object population. (org.kuali.rice.kns.web.derivedvaluesetter.DerivedValuesSetter) Not sure if this is still needed. I know that KFS uses this function a bit, but maybe there is a better way under KRAD.
Ability to specify a class which can ask questions prior to routing the document. (org.kuali.rice.kns.rule.PromptBeforeValidation) Again, this can probably be handled better in KRAD since we can use JavaScript. The KNS implementation had to work with JS turned off.
Ability to set a field as required (MaintainableFieldDefinition) - this was used to render the asterisk on the UI and perform DD validation when the document was submitted.  
Ability to set a field as "lookup-only", meaning that it could only by populated by use of a lookup - never entered directly. This was generally done when special processing was needed after entering a value. (E.g., to load other fields.) IMO - we should remove this capability. It's a PITA in places where you know the code. Example: Parent document type on the document type lookup. Why do I need to enter that when I know that I want "KFS" for the parent document?!?!?
Ability to specify a class (ValueFinder) which will obtain the default value for a field. The KNS version has a problem in that it is not aware of the document's state, and so can't make any decisions based on what is already on the document.
Ability to set a field as "unconditionally read only" so that not even permissions can make it editable. This also causes the UI components to simply not render the <input> tag for that field.  
Ability to note that a field (within a collection) should be read only after its been added. (Used to lock down collection PK fields after the user enters them.  
Ability to specify an alternate attribute to use for display purposes when the document is in read-only mode.  
Ability to specify an additional attribute for use during read-only display.  
On maintainable collections, to support multiple value lookup, you can specify what the source class is that you are looking up. (I.e., on the account global document, the detail object is AccountGlobalDetail - part of the document - but the source object is Account - the business object which gets referenced by that document class)  
Ability to control the existence of the "add" line via the collection definition.  
Ability to control whether to have a multiple value lookup.  
Ability to specify whether items can be deleted from the collection. (Default is to only allow deletion of newly added lines.)  
Ability to specify which field (singular) should be highlighted if there is a key violation between collection records.  
Ability to set a title for the summary line that appears at the top of each collection "row" (Applies when using the KNS-style old/new vertical alignment for collection rows.)  
Ability to set fields which will be included after the summary title. (Applies when using the KNS-style old/new vertical alignment for collection rows.)  
Ability to specify the list of fields which form the unique key within a collection.  
   
   
   
   
   
   
   
  • Handling for EBOs

 

Permission Checks

KIM Permission

Check Description

Location

Supported in KRAD
KR-NS / Full Unmask Field

Checks if a security-masked field can be displayed in the clear

BusinessObjectAuthorizationServiceImpl.canFullyUnmaskField

 
KR-NS / Partial Unmask Field

Checks if a security-masked field can be partially displayed

BusinessObjectAuthorizationServiceImpl.canPartiallyUnmaskField

 
KR-NS / Create / Maintain Record(s)Allows the control of the editing or creation of individual records via permissions. It's sometimes used to control access to specific records based on role qualifiers, though that is not directly supported. (subclasses add the PK values of the obejct being edited)

canCreate
canMaintain
canCreateOrMaintain 

 

KR-NS / Modify Maintenance Document Section

Uses the DD-provided section ID to check this permission.

This permission is keyed by the Business Object and section ID being edited. This must be the "master" business object being edited by the document. (Not a child object also being edited by the document.)

BusinessObjectAuthorizationServiceImpl.considerMaintenanceDocumentAuthorizer

 

KR-NS / View Inquiry or Maintenance Document Section

Uses the DD-provided section ID to check this permission.

This permission is keyed by the Business Object and section ID being edited. This must be the "master" business object being edited by the document. (Not a child object also being edited by the document.)

BusinessObjectAuthorizationServiceImpl.considerInquiryOrMaintenanceDocumentAuthorizer

 

KR-NS / Modify Maintenance Document Field

This permission is keyed by the Business Object and property name being edited. This must be the "master" business object being edited by the document. (Not a child object also being edited by the document.)

BusinessObjectAuthorizationServiceImpl.considerBusinessObjectFieldModifyAuthorization

 

KR-NS / View Inquiry or Maintenance Document Field

This permission is keyed by the Business Object and property name being edited. This must be the "master" business object being edited by the document. (Not a child object also being edited by the document.)

BusinessObjectAuthorizationServiceImpl.considerBusinessObjectFieldViewAuthorization

 

KR-NS / Edit Document

A (usually) automatically determined permission to ensure that the proper users can edit the documents at the right times. When this is false, the document should generally be completely non-editable.

Not Maint Doc specific: Only here to ensure that the interaction between Edit Document and the Modify Field permissions is preserved.

  

KR-NS / Open Document

 DocumentAuthorizerBase.canOpen 

KR-NS / Perform Custom Maintenance Document Function

When a custom button is supposed to be present on a maintenance document, this permission is checked for the id of the button. (property name) If the user does not have the permission, the button is not shown.BusinessObjectAuthorizationServiceImpl.considerCustomButtonFieldAuthorization 
    
    

Delete permission is insufficient. Just because a user can maintain an object, doesn't mean they should be able to delete it. A new permission template should be introduced for business object deletion.

Additionally, any record deletion should be within a try/catch which handles any FK violations and reports back by disapproving the document rather than throwing to exception.

 

Involved Classes

Class

Notes

Finished Analysis

Struts Classes

 

 

org.kuali.rice.kns.web.struts.action.KualiMaintenanceDocumentAction

 

(tick)

org.kuali.rice.kns.web.struts.action.KualiDocumentActionBase (tick)

org.kuali.rice.kns.web.struts.form.KualiMaintenanceForm

 

(tick)

org.kuali.rice.kns.web.struts.form.KualiDocumentFormBase (tick)
org.kuali.rice.kns.web.struts.form.pojo.PojoFormBase (tick)
General Classes  
org.kuali.rice.kns.document.MaintenanceDocumentBaseMostly support for the PersistableAttachment framework. Left in the KNS because its objects use PersistableBusinessObject. Needs to be converted to KRAD/JPA.(tick)
org.kuali.rice.krad.maintenance.MaintenanceDocumentBaseThis is most of the KNS function and is working as-is. 
org.kuali.rice.kns.rules.MaintenanceDocumentRule  
org.kuali.rice.kns.maintenance.rules.MaintenanceDocumentRuleBase  
org.kuali.rice.kns.rule.PromptBeforeValidation (tick)
org.kuali.rice.kns.web.derivedvaluesetter.DerivedValuesSetter (tick)

org.kuali.rice.krad.bo.GlobalBusinessObjectDetail

  
org.kuali.rice.krad.bo.GlobalBusinessObjectDetailBase  
org.kuali.rice.kns.util.KNSGlobalVariablesSupport for a MessageList component which could add messages to the top of the KNS screens after form submission. (E.g., Document is successfully routed)(tick)

org.kuali.rice.kns.util.FieldUtils

 

(tick)

org.kuali.rice.kns.web.ui.FieldBridge

Converts the field metadata into UI objects used by rowDisplay.tag

(tick)

org.kuali.rice.kns.web.ui.SectionBridge

Converts the section metadata into UI objects used by rowDisplay.tag

(tick)

org.kuali.rice.kns.util.MaintenanceUtils (tick)

JSP/Tag Files

 

 

/rice-web/src/main/webapp/kr/WEB-INF/jsp/KualiMaintenanceDocument.jsp

 

(tick)

/rice-web/src/main/webapp/WEB-INF/tags/kr/page.tag (tick)
/rice-web/src/main/webapp/WEB-INF/tags/kr/documentOverview.tag (tick)

/rice-web/src/main/webapp/WEB-INF/tags/kr/documentControls.tag

 

(tick)

/rice-web/src/main/webapp/WEB-INF/tags/kr/tab.tag

 

(tick)

/rice-web/src/main/webapp/WEB-INF/tags/kr/rowDisplay.tag

Handles the actual display of the data cells in the document.

(tick)

Maintainable

 

 

org.kuali.rice.kns.maintenance.KualiGlobalMaintainableImpl

 

 

org.kuali.rice.kns.maintenance.KualiMaintainableImpl

 

 

org.kuali.rice.krad.maintenance.MaintainableImpl  

Data Dictionary Classes

 

 

org.kuali.rice.kns.service.impl.MaintenanceDocumentDictionaryServiceImpl

Support service for accessing the DD. Mainly proxied all calls, handling nulls where needed. Also handled calling the ValueFinder instances for obtaining default values for fields.

  • Performed the required field validation for maint docs and the existence check for person fields. (This latter seems to assume that the Person object had already been populated by upstream code.
  • Checks for duplicates in collections.
(tick)

org.kuali.rice.kns.datadictionary.MaintainableSectionDefinition

 

(tick)

org.kuali.rice.kns.datadictionary.MaintainableSubSectionHeaderDefinition

 

(tick)

org.kuali.rice.kns.datadictionary.MaintainableItemDefinitionDummy superclass which just provided a name.(tick)
org.kuali.rice.kns.datadictionary.MaintainableFieldDefinition (tick)

org.kuali.rice.kns.datadictionary.MaintainableCollectionDefinition

 

(tick)

org.kuali.rice.kns.datadictionary.validation.MaintenanceDocumentAttributeValueReaderLegacy support class.(tick)
org.kuali.rice.kns.datadictionary.MaintenanceDocumentEntry (tick)
org.kuali.rice.kns.datadictionary.KNSDocumentEntry (tick)
org.kuali.rice.krad.datadictionary.MaintenanceDocumentEntry (tick)
Presentation Controller and Authorization  
org.kuali.rice.krad.document.DocumentPresentationControllerBase (tick)

org.kuali.rice.kns.document.authorization.MaintenanceDocumentPresentationControllerBase

 

(tick)

org.kuali.rice.kns.document.authorization.MaintenanceDocumentAuthorizerBase

 

(tick)

org.kuali.rice.kns.document.authorization.MaintenanceDocumentRestrictionsBase

DTO class which contains the results of all presentation controller and authorizer checks on document sections and fields. Used by the KNS UI classes to alter the contents of the document.

(tick)

org.kuali.rice.kns.document.authorization.InquiryOrMaintenanceDocumentRestrictionsBase (tick)

org.kuali.rice.kns.bo.authorization.BusinessObjectAuthorizerBase

 

(tick)

org.kuali.rice.kns.service.impl.BusinessObjectAuthorizationServiceImplHandles the building of the "restrictions" objects by calling the methods on the document authorizer.(tick)