Batch Upload Screen

Introduction

The batch upload screen provides functionality to allow users to upload, download, and delete XML files to be processed for batch processes. This guide will describe the process how to implement a screen for a specific job.

The XML files that may be easily incorporated into the batch upload screen having the following properties:

• Can be validated with an XSD file
• Can be converted into a java object using an Apache Digester script

Batch upload screen screenshot

The following is a screenshot of the Procurement Card Batch Upload screen.  Note that it allows the following actions:

• To upload (via the "add" button): The screen prompts for a file to upload and a file identifier.  A file identifier is a string consisting of only letters and digits that serves as a note about file.  It is used to generate the file name when the uploaded file is stored on the server, and is not likely to be used for any other purposes.
• To download and delete: There is a drop-down box indicating which files may be downloaded or deleted by the user.  Note that next to each file name, "processed" or "ready to process" is displayed.  Generally, the former indicates that the file has already been processed by the batch job.  For exceptions to this rule, see the discussion of done files below.  The latter indicates that the file is ready to be processed by the batch job.

About KFS batch files

KFS batch data files may exist on the filesystem with a "done" file in the same directory. The done file has an extension of ".done", and its presence indicates that the data file has been fully written to disk and is ready to be processed. The "done" file is not to be interpreted as the system is "done" processing the file.

The done filename prefix must match the data file name prefix. For example, if the data file name is "pcdoTrans.xml", then the done file must be named "pcdoTrans.done".

When uploading a batch data file, the data file is usually created first, and then the done file is created. Batch jobs are required to only process a data file if the done file exists on disk. Upon completion of a batch job, it should delete the done file so that future executions of the job will not process the same data file.

The absence of the done file indicates one of two conditions, both of which will cause the batch upload screen to indicate "processed" in the drop down boxes of files:

• A vast majority of the time, it indicates that a batch job has completed processing a file
• For a very small period of time, it could indicate that a data file is being uploaded and a done file has not yet been created.

Steps to implement the batch upload screen

This section will describe how the procurement card upload screen is implemented using the batch file upload framework.

Create a new class that implements BatchInputFileType, or extends BatchInputFileTypeBase

Instances of org.kuali.kfs.batch.BatchInputFileType provide metadata about the data files appropriate for a batch process. Its base implementation org.kuali.kfs.batch.BatchInputFileTypeBase provides default implementations for the common operations defined by the interface.

The following is the implementation for the batch input file type for the procurement card. Further explanation is provided in the comments.

package org.kuali.kfs.fp.batch;

//import here

/**
 * Batch input type for the procurement card job.
 */
public class ProcurementCardInputFileType extends XmlBatchInputFileTypeBase {
    private static org.apache.log4j.Logger LOG = org.apache.log4j.Logger.getLogger(ProcurementCardInputFileType.class);

    private DateTimeService dateTimeService;

    /**
     * @see org.kuali.kfs.sys.batch.BatchInputFileType#getFileTypeIdentifer()
     */
    public String getFileTypeIdentifer() {
        return KFSConstants.PCDO_FILE_TYPE_INDENTIFIER;
    }

    /**
     * No additional information is added to procurment card batch files.
     * 
     * @see org.kuali.kfs.sys.batch.BatchInputFileType#getFileName(org.kuali.rice.kim.bo.Person, java.lang.Object,
     *      java.lang.String)
     */
    public String getFileName(String principalName, Object parsedFileContents, String userIdentifier) {
        String fileName = "pcdo_" + principalName;
        if (StringUtils.isNotBlank(userIdentifier)) {
            fileName += "_" + userIdentifier;
        }
        fileName += "_" + dateTimeService.toDateTimeStringForFilename(dateTimeService.getCurrentDate());

        // remove spaces in filename
        fileName = StringUtils.remove(fileName, " ");

        return fileName;
    }
    
    public String getAuthorPrincipalName(File file) {
        String[] fileNameParts = StringUtils.split(file.getName(), "_");
        if (fileNameParts.length >= 2) {
            return fileNameParts[1];
        }
        return null;
    }

    /**
     * @see org.kuali.kfs.sys.batch.BatchInputFileType#validate(java.lang.Object)
     */
    public boolean validate(Object parsedFileContents) {
        return true;
    }

    /**
     * @see org.kuali.kfs.sys.batch.BatchInputFileType#getTitleKey()
     */
    public String getTitleKey() {
        return KFSKeyConstants.MESSAGE_BATCH_UPLOAD_TITLE_PCDO;
    }

    /**
     * Gets the dateTimeService attribute.
     */
    public DateTimeService getDateTimeService() {
        return dateTimeService;
    }

    /**
     * Sets the dateTimeService attribute value.
     */
    public void setDateTimeService(DateTimeService dateTimeService) {
        this.dateTimeService = dateTimeService;
    }

}

Configure the bean from the previous step in Spring, and set any desired properties

The next step is to define a new Spring bean that is an instance of the class implemented in the previous step. Consult this page for instructions on how to incorporate a new Spring definition file into KFS.

The following is the bean for the Procurement Card Batch Upload screen. Note that the name of this bean is identical to the value returned by the getFileTypeIdentifer() method in the class above.

	<bean id="procurementCardInputFileType" class="org.kuali.kfs.fp.batch.ProcurementCardInputFileType"> 
	    <property name="directoryPath">
	       <value>${staging.directory}/fp/procurementCard</value>
	    </property>
	    <property name="fileExtension">
	       <value>xml</value>
	    </property>
	    <property name="digestorRulesFileName">
	       <value>org/kuali/kfs/fp/batch/pcdoDigesterRules.xml</value>
	    </property>
	    <property name="schemaLocation">
	       <value>${externalizable.static.content.url}/xsd/fp/procurementCard.xsd</value>
	    </property>
	    <property name="dateTimeService">
	       <ref bean="dateTimeService"/>
	    </property>
	</bean>

Note that property substitution was used (e.g. the ${staging.directory}), and the value for properties can be overridden by following the instructions here.

Security & Permissions

In order for a user to upload the batch file there should be a permission created and assigned for that specific file input type and user. For example here "procurementCardInputFileType" has permission created using KIM permission template "KR-NS Upload Batch Input File(s)" and assigned to file type in krim_perm_attr_data_t table. Here in this case the permission id is 74 and assigned to role 45- KFS-SYS Operations.