ETL Extension Guidelines - Overriding an Existing Metric

This section contains guidance on overriding an existing core Metric with a new, custom metric with its own Metric ID. This is a relatively short process that may be a suitable alternative to the steps detailed in ETL Extension Guidelines - Refining an Existing Metric. This process is useful for situations where a granular core Metric ID must change, the associated ETL Application Translator still returns the same type of data, and you wish to avoid making any changes to rollup calculations. An example follows that demonstrates how to override three granular discipline metrics at the student level, while automatically applying the changes to the school and district level.

When to Override a Metric

In most circumstances, following the process detailed in ETL Extension Guidelines - Refining an Existing Metric will be appropriate for customization. The override process in this section is an alternative for minor replacements only. The process allows the replacement of a core Metric ID without modifying any code in the Translators for other Metrics that reference it. The steps below may be applied to granular Metrics that return the same type of data only. For more customized changes that will require modifications to rollup calculations, please follow the ETL Extension Guidelines - Refining an Existing Metric process, or create a new Metric using the steps outlined in ETL Extension Guidelines - Creating a New Metric.

Prerequisites

Review the process detailed in ETL Extension Guidelines - Refining an Existing Metric. Using the Metric override feature requires following the steps closely, specifically including:

Install and run the Dashboard ETL Application as documented in the ETL Developers' Guide - Installation section.
Install the Metric Configuration Tool. This will be required in order to create a new Metric ID.
Have a basic understanding of the SpecFlow language (http://www.specflow.org/). This is required to update the expected calculation results in tests referencing the overridden Metric
Install the SpecFlow language editor for Visual Studio 2013 or 2015 (http://www.specflow.org/getting-started/). This is required to modify and execute related tests.

Instructions: The Short Version

In Metric.cs, the Metric enumeration has an optional constructor that will take three values: a Metric ID, a display name, and another metric: overriddenByMetric. Using this optional constructor replaces all instances of the metric indicated by the Metric ID parameter with the Metric provided to the overriddenByMetric parameter. Use this feature if you wish to replace a core Metric ID without making modifications to the code of all the Translators that use it.

Instructions: The Long Version

In this example, we will override the three Non-State Offense discipline metrics at the student level with our own custom replacement metrics.

Currently, discipline offenses are separated into two categories: State Offense and Non-State Offense. As currently implemented, all discipline events that are not categorized as a State Offense will be given the Non-State Offense category. In this exercise, we will refine the Non-State Offense category to make it more specific by restricting the behavior type to School Violations and School Code of Conduct Incidents only.

Using the Metric Configuration Tool, create a Non-State Offenses - School Violations container metric using the existing Non-State Offenses container metric as a guide.
Using the existing Non-State Offenses as a guide, create three new granular metrics: Last 20 days, Last 40 days, and Year to Date. These will be our replacement metrics. Configure the metric states as desired, and make note of the new Metric IDs.
As described in How To: Add a New Metric, export the modified CSV files.

Checkpoint

Your dashboard Metric.csv should now contain 4 new entries: Non-State Offenses - School Violations (the container metric) and three new granular Metrics (Last 20 days, Last 40 days, and Year to Date). Data for these metrics will appear in MetricNode.csv and MetricVariant.csv. Once you have configured metric states, you will see new entries in MetricVariant.csv. If you are missing this data, please review the configuration and export instructions contained in the Metric Configuration Tool documentation.

With the Dashboard type files updated, you are ready to add the newly created Metric IDs to the code. In Metric.cs, add your new Metrics above the entries that you will override. Ensure that your new Metrics contain the new Metric IDs generated by the configuration tool.

4.a. Override the existing Non-State Offenses Metrics with our replacements created above. In this example, our new Metrics are 100003, 100004, 100005, and 100006. We have made the following overrides:

Metric 111 → Overridden by new Metric 100003 Metric 112 → Overridden by new Metric 100004 Metric 113 → Overridden by new Metric 100005 Metric 114 → Overridden by new Metric 100006

Metric.cs

private static readonly Metric OverrideStudentDisciplineNonStateOffensesContainerSchoolOnly = new StudentDisciplineMetric(100003, "Student - Non-State Offenses - School Violations");
public static readonly Metric StudentDisciplineNonStateOffensesContainer = new StudentDisciplineMetric(111, "Student - Non-State Offenses", overriddenByMetric: OverrideStudentDisciplineNonStateOffensesContainerSchoolOnly);
private static readonly StudentDisciplineMetric OverrideStudentDisciplineNonStateOffensesLastXSchoolOnly = new StudentDisciplineMetric(100004, "Student - Non-State Offenses (Last X) - School Violations");
public static readonly StudentDisciplineMetric StudentDisciplineNonStateOffensesLastX = new StudentDisciplineMetric(112, "Student - Non-State Offenses (Last X)", overriddenByMetric: OverrideStudentDisciplineNonStateOffensesLastXSchoolOnly);
private static readonly StudentDisciplineMetric OverrideStudentDisciplineNonStateOffensesLastYSchoolOnly = new StudentDisciplineMetric(100005, "Student - Non-State Offenses (Last Y) - School Violations");
public static readonly StudentDisciplineMetric StudentDisciplineNonStateOffensesLastY = new StudentDisciplineMetric(113, "Student - Non-State Offenses (Last Y)", overriddenByMetric: OverrideStudentDisciplineNonStateOffensesLastYSchoolOnly);
private static readonly StudentDisciplineMetric OverrideStudentDisciplineNonStateOffensesYTDSchoolOnly = new StudentDisciplineMetric(100006, "Student - Non-State Offenses (YTD) - School Violations");
public static readonly StudentDisciplineMetric StudentDisciplineNonStateOffensesYTD = new StudentDisciplineMetric(114, "Student - Non-State Offenses (YTD)", overriddenByMetric: OverrideStudentDisciplineNonStateOffensesYTDSchoolOnly);

In this example, we've set the accessibility of the new Metrics to private in order to enforce the fact that we do not want two versions of the same Metric appearing elsewhere in code. Two Metrics in use with the same ID may not exist. If the Metric has changed in logic enough where both metric copies should be accessible from the outside, then the process detailed in ETL Extension Guidelines - Refining an Existing Metric or ETL Extension Guidelines - Creating a New Metric may be more appropriate.

4.b. Allow student discipline Metrics to make use of the overrides we have provided. Here, we use the Metric constructor that accepts an override in order to ensure that the ID is set early in the bootstrap process when the application initializes.

Metric.cs

public StudentDisciplineMetric(int value, string displayName, Metric overriddenByMetric)
	: base(value, displayName, overriddenByMetric)
    {
    	DefaultGoal = overriddenByMetric.DefaultGoal;
    }

Update any Translator logic at the granular level that needs to change by either replacing or modifying existing Translators. In this example, we have restricted Non-State Offenses to school violations and school code of conduct incidents only.

5.a.Modify student-level logic for Non State Offenses YTD:

5.b. Modify student-level logic for Non State Offenses Last X and Last Y Metrics:

5.c. Here's the code snippet for that change:
```
return behaviorDescriptor == BehaviorDescriptor.SchoolCodeOfConduct || behaviorDescriptor == BehaviorDescriptor.SchoolViolation;
```
With the changes applied at the student level, rollup calculations at the School and District level will reference the new Metric ID automatically. This includes the calculators for SchoolDisciplineNonStateOffenses, SchoolDisciplineNonStateOffensesLastX, SchoolDisciplineNonStateOffensesLastY, LocalEducationAgencyDisciplineNonStateOffenses, LocalEducationAgencyDisciplineNonStateOffensesLastX, LocalEducationAgencyDisciplineNonStateOffensesLastY, and any other Translators that reference the student-level calculation results.

Just as referenced in ETL Extension Guidelines - Refining an Existing Metric, With the Metric ID changed and new logic applied, you should observe that any SpecFlow tests referencing the old Metric IDs (i.e., 111, 112, 113, 114) will now be failing – as expected. These tests should be updated with the new Metric ID and expected output as follows:

StudentDisciplineReferralsIncidentsLog.feature

Scenario: Business Rule: Incidents Log - Student
    Given a student enrolled in High School with discipline referrals
        | StudentParticipationCodeDescriptor | BehaviorDescriptor     | IncidentDate | IncidentTime | IncidentIdentifier | IncidentCode | IncidentDescription    | IncidentDescriptionDetail         | Action                   | ActionDetail         |
        | Perpetrator                        | Aggravated Robbery     | 2012-09-15   | 13:45        | 23                 | 46           | Aggravated Robbery     | Robbery                           | Community Service        | NULL                 |
        | Witness                            | State Offense          | 2012-09-15   | 12:15        | 3456               | 01           | State Offense          | NULL                              | Community Service        | NULL                 |
        | Perpetrator                        | School Code of Conduct | 2012-10-22   | 15:10        | 1                  | 04           | School Code of Conduct | NULL                              | Out-Of-School Suspension | NULL                 |
        | Perpetrator                        | State Offense          | 2012-11-30   | 15:00        | 45                 | 01           | State Offense          | State Offense Detailed Desciption | Community Service        | In-School Suspension |
        | Perpetrator                        | State Offense          | 2012-12-05   | 10:45        | 67                 | 01           | State Offense          | NULL                              | Community Service        | In-School Suspension |
        | Witness                            | School Code of Conduct | 2012-12-11   | 09:05        | 34                 | 04           | School Code of Conduct | NULL                              | Community Service        | NULL                 |
        | Perpetrator                        | School Code of Conduct | 2013-01-02   | 11:10        | 87                 | 04           | School Code of Conduct | NULL                              | NULL                     | NULL                 |
        | Perpetrator                        | School Violation       | 2013-02-03   | 10:15        | 123                | 02           | School Violation       | NULL                              | In-School Suspension     | NULL                 |
        | Perpetrator                        | Other                  | 2013-02-09   | 14:20        | 47                 | 03           | Other                  | NULL                              | Other                    | NULL                 |
    When executed
    Then the student discipline referrals incident log should be
        | BehaviorDescriptor     | MetricId | Date             | IncidentCode | IncidentDescription                                  | Action                                  | Note                                                                           |
        | State Offense          | 105      | 2012-09-15 13:45 | 23           | State Offense #23: Robbery                           | Community Service                       | Combined IncidentDescription/IncidentDescriptionDetail                         |
        | School Code of Conduct | 100003   | 2012-10-22 15:10 | 1            | School Code of Conduct #1                            | Out-Of-School Suspension                |                                                                                |
        | State Offense          | 105      | 2012-11-30 15:00 | 45           | State Offense #45: State Offense Detailed Desciption | Community Service: In-School Suspension | Combined IncidentDescription/IncidentDescriptionDetail and Action/ActionDetail |
        | State Offense          | 105      | 2012-12-05 10:45 | 67           | State Offense #67                                    | Community Service: In-School Suspension | Combined Action/ActionDetail                                                   |
        | School Code of Conduct | 100003   | 2013-01-02 11:10 | 87           | School Code of Conduct #87                           | No action found for incident            |                                                                                |
        | School Violation       | 100003   | 2013-02-03 10:15 | 123          | School Violation #123                                | In-School Suspension                    |                                                                                |