Export formats for state reporting

Export formats are the basis of Aspen's custom state reporting structure and includes several common components which do most of the data organization and display. Export formats also include some custom components and table data that gather the relevant data for the report.

Building a custom export

The first step of building a custom export is to review the report requirements defined by the state. The requirements define the:

type of data required
report layout

When you know these two things, you can determine what elements in Aspen are needed to create the report. The following table will help you identify the field values and calculations necessary to satisfy each field in the report.

Common components of an export

Following are the common components of an export:

Java component	Function
StateReportExport.java	Java source for Export procedure
StateReportValidateData.java	Java source for Validation Report
StateReportValidateData.jrxml	format for Validation Report

Common java classes

Common java classes used by state reporting are:

StateReportData.java
StateReportEntity.java
StateReportValidationError.java
FieldDefinition.java
FieldRetriever.java
FieldValidator.java

Custom components

The custom components which are required to implement a state report are:

Report data source procedure java source
Validation report input XML eXtensible Markup Language
Export input XML

Custom Table Data

The table data used by the state reporting structure:

Export Format Definition
Export Format Field

Components of the Export Format Definition

The Export Format Definition contains much of the data source and layout information required by a report and includes the following components:

Complement	Function
Procedure ID	Associates the export definition with its java source and an export and validation report. Must exactly match the procedure ID of the associated procedure's
Source table	Identifies the table whose beans will be used to provide data for the report.
Formatting values	Delimiter and wrapper characters used to format values in the output text. If a report has no delimiter, this should be left empty.
Multiple field definitions	Each field definition defines one data field to be exported in the report. Determine the following: data source lookup processing formatting possibly calculation

Components of a Field Definition

A field definition contains:

Complement	Description
Position	Integer position of the field in the report. Used for ordering fields.
Name	Unique name identifying the field and prints in the validation report.
Bean path	The bean path starting from the source table to the value required for the report. Can contain an alias for the field component of an alias is needed. To include an alias, surround the alias in square brackets: [DOE34] school.[DOE15] This value can be left empty if a calculation is available, or you just want the default value.
Default	A value to use as the export value if the generated value is empty.
Reference map	An indicator. If it is set and the field specified in the bean path has a reference table associated with it, the value in the field will be looked up in the reference table. The state code from the reference code will be used as the value for the export.
Minimum Length	Used in validation to warn if the value is smaller than expected by the state.
Maximum length	Used in validation and to pad or truncate values, if necessary.
Format type	If the value is not a string, it may need special formatting in the export. States generally require specific formatting for dates.
Format expression	A formatting expression used with the format type to format date or numeric values. The format rules are: Java SimpleDateFormat DecimalFormat classes The logical formatter has the expression of two characters used for true and false: YN TF 10
Validation pattern	A regular expression that is applied to the final result. Used in the validation report to warn of invalid values.
Padding direction	If the report is expected to be column delimited, padding is used along with maximum length to format the output in the column size specified. Padding can be: left, or right If no padding is required, this can be none, or it can be truncated to cut a value that is too long down to the maximum length.
Padding character	If padding is required (left or right), the padding char is used to pad. If no padding char is provided, spaces are used.
Calculation ID	Name of a mapped Retriever from the custom java source that will calculate the value for this field. If a field requires custom code to calculate the value, the code will be written in the custom java procedure and associated with a name in a map.The name in the map is placed here to allow it to be found and associated with this field.
Validation ID	Similar to the calculation ID. Custom validation code can be written in the java procedure and associated with a name in a map. The map name is placed here to find the code.
Calc	A parameter that can be passed into the calculation and validation code. This allows a calculation to support multiple fields and use the parameter to determine its behavior.

Custom Java Source


java component = data source procedure	Gathers the data for the state report and performs custom field validation on the data. Eventually installed as a procedure and must be contained in a single java source file. Must extend the java class Must include an inner class definition for an entity that extends StateReportEntity. An instance of the entity class represents one instance of the table bean specified in the Export Format Definition.
If a data element requires more complex lookup than a field retrieval and reference code state value lookup...	then a custom retriever may also be defined. This is an inner class that implements the FieldRetriever interface. This retriever code can look up any value necessary and perform any calculation. It should return the final value as text.
If a data element requires more complex validation than the simple length and pattern...	an inner class can be defined that performs complex validation. This method should return a Collection of StateReportValidationError objects, with errors for each validation error it encounters.
FieldRetriever and	Both receive: references to the parameters and cached copies of the other data fields for cross field validation. a reference to the current entity from which it can retrieve the student or staff or other object. a reference to the FieldDefinition object that contains information about the data field to be extracted.
data source procedure	Must initialize by: Build a query a request to find a group of records that match specific criteria at a particular time that retrieves the data entity records to be processed. Set the entity class (the inner class extending StateReportEntity interface). Build a map of any FieldRetrievers defined, using String map keys. Build a map of any FieldValidators defined, using String map keys. Set the query, entity class, and maps on the super class. Provide any initialization errors that might have occurred.

Entities and Complex Entities


Entity inner class	Created for each row returned from the query. Has functions that can be used to filter a set of criteria to selectively screen out incoming information, such as "all active students" or "former students" out entities that need to be removed from the report for data reasons. Also has a post process procedure for performing actions after the report, such as saving some custom data back to the database. Otherwise, it represents the entity that it contains.
Data rows	Some reports may require data rows that represent more than a single data entity or contain mixed entities. Example: Staff work assignment which contains staff assignments and staff positions. The Entity object can represent a Staff, but it can provide multiple rows of data which represent assignments or position. These complex entities should be defined on the next higher level where there is something in common. For Staff work assignment, this is the staff record.
super.setRowCount super.setCurrentRow	Within the entity, the implementing class must lookup up a list of the child fields when it is initialized. It then contains a row counter and current row. These are set with super.setRowCount and With these set, a single entity will be used several times to retrieve several data rows for the export. The entity must use the current row value to determine which data row to use when asked for data.

Entity inner class

Created for each row returned from the query.
Has functions that can be used to filter a set of criteria to selectively screen out incoming information, such as "all active students" or "former students" out entities that need to be removed from the report for data reasons.
Also has a post process procedure for performing actions after the report, such as saving some custom data back to the database. Otherwise, it represents the entity that it contains.

Data rows

Some reports may require data rows that represent more than a single data entity or contain mixed entities.
Example: Staff work assignment which contains staff assignments and staff positions. The Entity object can represent a Staff, but it can provide multiple rows of data which represent assignments or position. These complex entities should be defined on the next higher level where there is something in common. For Staff work assignment, this is the staff record.

super.setRowCount

super.setCurrentRow

Within the entity, the implementing class must lookup up a list of the child fields when it is initialized. It then contains a row counter and current row. These are set with super.setRowCount and
With these set, a single entity will be used several times to retrieve several data rows for the export. The entity must use the current row value to determine which data row to use when asked for data.

Building a custom state report input XML

When the state report data procedure needs user input, it can get this input the same way as other procedures. The XML input by the user defines all input parameters and these are passed to the data source java program.

This input XML must also contain a hidden element that contains the procedure ID of the data source procedure in a tag like:

<inputname="procedureIddata-type="string"display-type="hidden"default-value="EXPDATA-MA-SIMS/>

This is used by the common StateReportExport and

Installing a custom report

To install a custom state report, there must be:

Report entry containing:

StateReportValidateData.java

StateReportValidateData.jrxml

{custom input XML with matching PROCEDURE ID }

Export entry containing:

StateReportExport.java

{custom input XML with matching PROCEDURE ID}

Procedure containing:

{custom data source java source}

PROCEDURE ID

Export Format Definitions:

PROCEDURE ID

The report and the export can be run directly or through the scheduler, but the procedure should not be run directly since it is not a valid procedure and will fail.

Due to the quantity of elements required for this structure, a portability bundle zip file containing the tool components and main XML document that describes the tool name, ID, and navigation is available.

To generate a bundle that contains all elements of the state report:

Make a complete working installation of all elements, including format definitions, procedure, export and report.
Once this is ready and working, log on to the District view.
Select the Tools tab.
Click the Exports side-tab, and then click Export Formats.
Click the state report format to view its details.
Go to the Options menu, and select Export.
Click the checkboxes for procedures, reports, and exports.
Click Export.

To import a bundle:

Log on to the District view.
Click the Exports side-tab, and then click Export Formats.
Click the state report format to view its details.
Go to the Options menu, and select Import. The import screen will have an option to find a bundle file. Choose the bundle file generated by the export. Then press analyze. This will display changed in the format definition and field definitions. Once selected, choose to include reports, and then import. All elements will be imported.