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:

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 queryClosed 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

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:

 <!-- ************** -->

 <!-- DATA PROCEDURE -->

 <!-- ************** -->

 <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 bundleClosed is available.

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

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

To import a bundle:

  1. Log on to the District view.
  2. Click the Exports side-tab, and then click Export Formats.
  3. Click the state report format to view its details.
  4. 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.