GEC Validation Technical Specification

Jira Tasks

KITT-353@Jira

Revision History

Version	Date	User	Description
1.0	05/15/2009	Heather Lo	Initial Spec
1.1	05/19/2009	Heather Lo	Second Draft of Spec
2.0	05/27/2009	Heather Lo	Spec with Development Steps
2.1	06/01/2009	Heather Lo	Changed Steps for Error Certification Business Object
3.0	06/23/2009	Heather Lo	Final Spec (Reflects All Development Steps Taken)
3.1	08/28/2009	Heather Lo	Final Spec That Adds ErrorCertifiable Interface

Technical Description

The General Error Correction (GEC) is used to correct transactions that have posted to accounts. Currently at the UA we have a process called eRFAA that validates that the transaction being corrected does exist, but the delivered version of GEC doesn't require that a valid reference be entered. The GEC needs to be modified to validate the reference number against the original document number both when an accounting line is added and the document is submitted. There will also be a new system parameter to turn this validation on and off.
The GEC also needs to display an Error Certification tab. The fields are required if one of two conditions are met: 1) if the transaction is older than 30 days old and the account is a federal account, or 2) for all other accounts, if the transaction is older than 90 days. Two new system parameters are needed to help control the requirement of data in this tab. Additionally, when any field is completed in this tab, all fields must be completed. These fields require an extension to the existing GEC table in the database and the appropriate business object and data dictionary additions.

Furthermore, the fiscal officer or delegate must click yes after reading the error certification statement when transferring to/from the accounts associated with sub-funds specified in the parameter.

Details

Database Requirements
1. Three new system parameters: DEFAULT_NUMBER_OF_DAYS_ERROR_CERTIFICATION_TAB_REQUIRED, EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND, REFERENCE_NUMBER_VALIDATION_IND
  - Use parameter component "GeneralErrorCorrection" for PARM_DTL_TYP_CD.
2. New table for Error Certification tab info called FP_ERROR_CERT_T with corresponding fields.
UI Design
1. New Error Certification tab.
2. Error Certification Statement.
Development Checklist
1. Create the three new system parameters.
  - Write SQL to add parameters to database. Add to work/db/scripts/arizona/data.sql.
  - Run SQL in SQuirrel or a similar program.
  - Add constant declarations to edu/arizona/kfs/sys/AZKFSConstants.java.
2. Write a java class to validate the Reference Number against the Document Number on the posted GL transactions for each accounting line.
  - Create class: edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionRefNumberValidation.java
  - Extend GenericValidation class.
  - Use BusinessObjectService to look in the Entry business object.
  - Confirm existence of a record in GL_ENTRY_T with a FDOC_NBR that matches each reference number entered on all accounting lines (i.e. source and target). Display error if invalid reference number.
  - Also check REFERENCE_NUMBER_VALIDATION_IND parameter to see if validation is desired.
3. Add error message for invalid reference number. (Modify edu/arizona/kfs/sys/KFSKeyConstants.java and arizona-ApplicationResources.properties.)
4. Modify the data dictionary to reference the new validation.
  - Copy and modify org/kuali/kfs/fp/document/validation/configuration/GeneralErrorCorrectionValidation.xml. Define validation bean that references the java class.
  - Add the new validation to the GeneralErrorCorrection-addAccountingLineValidation and GeneralErrorCorrection-updateAccountingLineValidation bean definitions.
5. Add validation to edu/arizona/kfs/fp/spring-fp.xml.
6. Create business object to represent Error Certification tab fields.
  - Write SQL to create the Error Certification table (FP_ERROR_CERT_T). Include primary key (ERROR_CERT_ID) and add it as a foreign key to FP_ERROR_COR_DOC_T.
  - Create POJO for the fields. Includes errorCertID, expenditureDescription, expenditureProjectBenefit, errorDescription, errorCorrectionReason.
7. Modify existing GEC Document java class to include Error Certification.
  - Create edu.arizona version of GeneralErrorCorrectionDocument.java that extends the org.kuali version.
  - Make sure to declare that ErrorCertifiable is being implemented.
  - Include a method that gets/sets an ErrorCertification object.
8. Modify existing GEC Form java class to include Error Certification.
  - Create edu.arizona version of GeneralErrorCorrectionForm.java that extends the org.kuali version.
  - Create a new ErrorCertification object in our new GEC document object in the constructor.
9. Modify work/web-root/WEB-INF/struts-config.xml so that the GeneralErrorCorrectionForm references our version of the form.
10. Update the data dictionary.
  - Create data dictionary file for the new business object (ErrorCertification.xml).
  - Create edu\arizona\kfs\fp\document\datadictionary\GeneralErrorCorrectionDocument.xml and redefine the documentClass property to point to our version of GeneralErrorCorrectionDocument.java
11. Modify edu/arizona/fp/ojb-fp.xml.
  - Define the new business object.
  - Define the reference to the new business object in the original business object through a field descriptor and a reference descriptor.
12. Write code for new Error Certification tab.
  - Write work/web-root/WEB-INF/tags/fp/errorCertification.tag that contains jsp tag references and HTML.
13. Modify jsp for General Error Correction.
  - Add new tag reference for errorCertification.tag to kfs/work/web-root/jsp/fp/GeneralErrorCorrection.jsp.
14. Write two java classes for validation on the Error Certification Tab (GeneralErrorCorrectionErrorCertificationValidation.java and ErrorCertificationValidation.java).
  - One validation checks the dates from the source and target accounting lines, sub funds in the target accounting lines, and the parameters (DEFAULT_NUMBER_OF_DAYS_ERROR_CERTIFICATION_TAB_REQUIRED and EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND system parameters) and the dates from the accounting lines to see if the error cert fields are required when doc is submitted.
  - Another class checks the fields in the form to see if any are filled out. If so, all fields in the tab are required when doc is approved.
15. Create exception class for the new GEC validation for the cases when a matching Entry isn't found. (EntryNotFoundException.java)
16. Add error messages for incomplete fields. (Modify edu/arizona/kfs/sys/KFSKeyConstants.java and arizona-ApplicationResources.properties.)
17. Modify the data dictionary to reference the new validation.
  - Modify edu/arizona/kfs/fp/document/validation/configuration/GeneralErrorCorrectionValidation.xml. Define validation beans that reference the java classes.
  - List merge the new validations in the GeneralErrorCorrection-routeDocumentValidation bean definition.
18. Create pre-rules class for the Error Certification Statement. (GeneralErrorCorrectionDocumentPreRules.java)
  - Implement the doPrompts method.
  - Examine all of the target accounting lines to compare the sub funds and transaction dates to the EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND parameter.
  - Check the current route node to check if it is the fiscal officer or delegate.
19. Modify data dictionary (edu/arizona/kfs/fp/document/datadictionary/GeneralErrorCorrectionDocument.xml) to include pre-rules class.
20. Add certification text to arizona-ApplicationResources.properties.
21. Add constant for certification text to edu/arizona/kfs/sys/KFSKeyConstants.java.
22. Add constant for the id of the question to edu/arizona/kfs/sys/KFSConstants.java.

Development Steps Completed

Created the three new system parameters.
1. Wrote and added SQL to work/db/scripts/arizona/data.sql. Ran SQL to insert parameters in database.
2. Added constant declarations for parameters to edu/arizona/kfs/sys/AZKFSConstants.java.

Wrote a java class (edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionRefNumberValidation.java) to validate the Reference Number against the Document Number on the posted GL transactions for each accounting line. Validation is called in adds and updates of accounting lines (including document approval).

Checks REFERENCE_NUMBER_VALIDATION_IND parameter to see if validation is desired. Uses parameterService.getIndicatorParameter(GeneralErrorCorrectionDocument.class, AZKFSConstants.REFERENCE_NUMBER_VALIDATION_IND_PARM).

Confirms existence of a record in GL_ENTRY_T with a FDOC_NBR that matches each reference number entered on all accounting lines. Uses Map with document number and reference number from the current accounting line. Displays error if invalid reference number.

excerpt from edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionRefNumberValidation.java

.
.
.
/**
 * Checks to see if the reference number on an accounting line matches a record in GL_ENTRY_T.
 * @return boolean
 */
protected boolean isRefNumValid() {
    Collection matchingEntry = getRefNumberMatch();

    if (matchingEntry != null && matchingEntry.size() > 0) {
        return true;
    }
    else {
        GlobalVariables.getErrorMap().putError(REFERENCE_NUMBER, KFSKeyConstants.ERROR_GEC_REF_NUMBER_INVALID, accountingLineForValidation.getReferenceNumber());
        return false;
    }
}

/**
 *
 * This method tries to fetch a record in GL_ENTRY_T that has a FDOC_NBR = reference number entered.
 * @return Collection representing the matching GL entry
 */
protected Collection getRefNumberMatch() {
    LOG.debug("ref num: " + accountingLineForValidation.getReferenceNumber());

    Map criteria = new HashMap();
    criteria.put(KNSPropertyConstants.DOCUMENT_NUMBER, accountingLineForValidation.getReferenceNumber());
    Collection results = getBusinessObjectService().findMatching(Entry.class, criteria);
    LOG.debug("results: " + results);

    return results;
}
.
.
.

Added error message for invalid reference number. (Modified edu/arizona/kfs/sys/KFSKeyConstants.java and arizona-ApplicationResources.properties.)
Modified the data dictionary to reference the new validation.
1. Created UA version of GeneralErrorCorrectionValidation.xml to define our validation bean and add it to the GeneralErrorCorrection-addAccountingLineValidation and GeneralErrorCorrection-updateAccountingLineValidation bean definitions.
2. Included parameterService and businessObjectService as properties in our validation bean definition.
Added validation to edu/arizona/kfs/fp/spring-fp.xml with import statement.
Created business object to represent Error Certification tab fields.
Modified existing GEC Document java class to include Error Certification (edu/arizona/kfs/fp/document/GeneralErrorCorrectionDocument.java).
1. Extends org.kuali.kfs.fp.document.GeneralErrorCorrectionDocument.
2. Added "implements ErrorCertifiable".
3. Included constructor that calls super class, methods to get/set an ErrorCertification object and methods to get/set an errorCertID Integer.

Modified existing GEC Form java class to include Error Certification (edu/arizona/kfs/fp/document/web/struts/GeneralErrorCorrectionForm.java).

Created a new ErrorCertification object in our new GEC document object in the constructor.

excerpt from edu/arizona/kfs/fp/document/web/struts/GeneralErrorCorrectionForm.java

import edu.arizona.kfs.fp.businessobject.ErrorCertification;
import edu.arizona.kfs.fp.document.GeneralErrorCorrectionDocument;

public class GeneralErrorCorrectionForm extends org.kuali.kfs.fp.document.web.struts.GeneralErrorCorrectionForm {

    public GeneralErrorCorrectionForm() {
        super();
        GeneralErrorCorrectionDocument document = new GeneralErrorCorrectionDocument();
        document.setErrorCertification(new ErrorCertification());
        setDocument(document);
    }
}

Modified work/web-root/WEB-INF/struts-config.xml so that the GeneralErrorCorrectionForm form-bean references our version of the form.
Updated the data dictionary.
1. Created data dictionary file for the new business object (edu/arizona/kfs/fp/businessobject/datadictionary/ErrorCertification.xml).
2. Created edu/arizona/kfs/fp/document/datadictionary/GeneralErrorCorrectionDocument.xml and redefined the documentClass property to point to our version of GeneralErrorCorrectionDocument.java
Modified edu/arizona/fp/ojb-fp.xml.
1. Defined the new business object.
2. Defined the reference to the new business object in the original business object through a field descriptor (to match the primary key) and a reference descriptor (for the business object) that includes the errorCertID as a foreign key.

Wrote code for new Error Certification tab.

Wrote work/web-root/WEB-INF/tags/fp/errorCertification.tag that contains jsp tag references and HTML.

Defines a tabErrorKey for error message location.

excerpt from work/web-root/WEB-INF/tags/fp/errorCertification.tag

<kul:tab tabTitle="Error Certification" defaultOpen="true" tabErrorKey="document.errorCertification">
     <div class="tab-container" align="center">
        <c:set var="attributes" value="${DataDictionary.ErrorCertification.attributes}" />
     		<h3>Error Certification</h3>
        <table cellpadding="0" cellspacing="0" class="datatable" summary="Error Certification Section">
            <tr>
                <th align="right" valign="middle" class="bord-l-b" width="50%">
                   <div align="right"><kul:htmlAttributeLabel attributeEntry="${documentAttributes.expenditureDescription}" /></div>
                </th>
                <td align="left" valign="middle" class="datacell" width="50%">
                     <kul:htmlControlAttribute
                    	attributeEntry="${documentAttributes.expenditureDescription}" property="document.errorCertification.expenditureDescription"
                    	readOnly="${not fullEntryMode}" />
                </td>
            </tr>
.
.
.
	</table>
     </div>
</kul:tab>

Modified jsp for General Error Correction.
1. Added new tag reference for errorCertification.tag to kfs/work/web-root/jsp/fp/GeneralErrorCorrection.jsp.
  excerpt from kfs/work/web-root/jsp/fp/GeneralErrorCorrection.jsp
```
<fp:errorCertification documentAttributes="${DataDictionary.ErrorCertification.attributes}" />
```
Wrote two java classes for validation on the Error Certification Tab (edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionErrorCertificationValidation.java and edu/arizona/kfs/fp/document/validation/impl/ErrorCertificationValidation.java).
1. GeneralErrorCorrectionErrorCertificationValidation.java extends GenericValidation and implements the validate method. It checks the dates from the transactions that are referenced in the source and target accounting lines, sub funds in the target accounting lines, and the parameters (DEFAULT_NUMBER_OF_DAYS_ERROR_CERTIFICATION_TAB_REQUIRED and EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND system parameters) to see if the error cert fields are required when doc is submitted.
2. The number of days in EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND is used if the sub fund from the parameter tied to an account from at least one of the target accounting lines.
3. GeneralErrorCorrectionErrorCertificationValidation.java also calls a method from ErrorCertificationValidation.java to retrieve the number of blank fields in the Error Certification tab.
4. ErrorCertificationValidation.java extends GenericValidation and implements the validate method. It checks the fields in the form to see if any are filled out. If so, all fields in the tab are required when doc is approved. Displays an error message if the form is partially filled out.
Created exception class for the new GEC validation for the cases when a matching Entry isn't found. (EntryNotFoundException.java)
1. Contains constructor and get/set methods for a Map object that contains the entry match criteria.
Added error messages for incomplete fields. (Modified edu/arizona/kfs/sys/KFSKeyConstants.java and arizona-ApplicationResources.properties.)
Modified the data dictionary to reference the new validation.
1. Modified edu/arizona/kfs/fp/document/validation/configuration/GeneralErrorCorrectionValidation.xml. Defined validation beans that reference the java classes.
2. The GeneralErrorCorrection-errorCertificationValidation-parentBean includes properties for parameterService and businessObjectService.
3. List merged the new validations in the GeneralErrorCorrection-routeDocumentValidation bean definition.

Created pre-rules class for the Error Certification Statement that extends PromptBeforeValidationBase.java. (edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionDocumentPreRules.java)

Implemented the doPrompts method.
Examined all of the target accounting lines to compare the sub funds and transaction dates to the EFFORT_CERTIFICATION_DEFAULT_OVERRIDE_BY_SUB_FUND parameter.

Checked the current route node to check if it is the fiscal officer or delegate.

excerpt from edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionDocumentPreRules.java

/**
 * This method checks the current route level. If it is at the "Account" route node, then the fiscal officer
 * is looking at the GEC.
 * @return true if it's at the "Account" route note; false otherwise
 */
private boolean checkRouteLevel(GeneralErrorCorrectionDocument gecDocument) {
    String currNode = gecDocument.getDocumentHeader().getWorkflowDocument().getCurrentRouteNodeNames();
    LOG.debug("checkRouteLevel currNode: " + currNode);
    if (currNode.equals(org.kuali.kfs.sys.KFSConstants.RouteLevelNames.ACCOUNT)) {
        return true;
    }

    return false;
}

Used SpringContext.getBean(class name) to get the ParameterService and BusinessObjectService.

Called the askOrAnalyzeYesNoQuestion method from PromptBeforeValidationBase.java.

excerpt from edu/arizona/kfs/fp/document/validation/impl/GeneralErrorCorrectionDocumentPreRules.java

/**
 * Shows the Error Certification Statement and returns the result.
 * @return true if the Error Certification Statement returns a "Yes"; false otherwise
 */
private boolean showErrorCertStmt() {
    String questionText = SpringContext.getBean(KualiConfigurationService.class).getPropertyString(KFSKeyConstants.QUESTION_ERROR_CERTIFICATION_STMT);
    boolean approved = super.askOrAnalyzeYesNoQuestion(KFSConstants.GeneralErrorCorrectionDocumentConstants.GENERATE_ERROR_CERTIFICATION_STMT_ID, questionText);

    if (!approved) {
        super.event.setActionForwardName(RiceConstants.MAPPING_BASIC);
    }
    return approved;
}

Modified data dictionary (edu/arizona/kfs/fp/document/datadictionary/GeneralErrorCorrectionDocument.xml) to include pre-rules class (property name="promptBeforeValidationClass").
Added certification text to arizona-ApplicationResources.properties.
Added constant for certification text to edu/arizona/kfs/sys/KFSKeyConstants.java.
Added constant for the id of the question to edu/arizona/kfs/sys/KFSConstants.java.
About Code Excerpts
The three dots in code excerpts signify code that I didn't want to include in the documentation for brevity.