The Ed-Fi “Classic Dashboards” are no longer supported through the Ed-Fi Alliance. You can still receive support and maintenance through the Ed-Fi vendor community. Please look at any of the vendors’ dashboard solutions on the Registry of Ed-Fi Badges or the Ed-Fi Starter Kits if you are looking for a visualization solution to use with the Ed-Fi ODS. This documentation will remain available to assist existing Classic Dashboard implementers.

ETL Extension Guidelines - Refining an Existing Metric

Owned by Itzel Torres
Sep 23, 2019
7 min read

This section contains guidance for refining existing metrics by walking through two examples. Modifying an existing metric is a great place to get started with coding for the Ed-Fi ETL Application.

Example 1: Modify the Student Tardy Rate Calculation

We will refine the existing Student Tardy Rate to include the "Early departure" AttendanceEventCategoryDescriptor. In the as-shipped code student tardy rate calculations, the Translator only considers attendance categories of "Tardy" in the calculation. We want to include the "Early departure" attendance category in the tardy rate calculation. 

Prerequisites

This lab has the following prerequisite steps:

Update SpecFlow Tests

To ensure that the Translator is written correctly, we will update the existing SpecFlow test to include "Early departure" category in test.

  • Navigate in File Explorer to where you have cloned the code from GitHub. Open the "EdFi ETL.sln" file in "Etl\src".
  • Open the StudentTardyRate.feature file in the Edfi.MetricBusinessLogic.Tests project under the StudentAttendance\TardyRate folder.

You should see the first SpecFlow test described below. We will need to add an attendance event with the category "Early departure" in Homeroom for our test. Only attendance section events that occur in Homeroom are counted towards the calculation based on the business rules specified in Student - Tardy Rate.

  • Update the SpecFlow scenario to give the student Early departure attendance events in Homeroom for both the current and previous reporting periods. The tardy rate, days tardy, and year to date tardy rate values will need updated based on the student's number of tardies.
  • Save the SpecFlow feature file, it will regenerate the StudentTardyRate.feature.cs file which contains the NUnit test representation of the SpecFlow feature file. 

In this example, we are only updating the first SpecFlow scenario. For full test coverage, all scenarios in the StudentTardyRate feature should be updated to test for the "Early departure" attendance category.


Execute SpecFlow Tests

  • Execute the SpecFlow tests for the StudentTardy.feature file by right-clicking on the StudentTardy.feature.cs file in the Solution Explorer and selecting Run Unit Tests (see How To: Execute SpecFlow Tests in the ETL Solution for more information). The BusinessRuleSectionAttendance scenario will fail since the Student Tardy Translator is not considering the "Early departure" attendance category.

Update Student Tardy Rate Translator

To update the Student Tardy Rate Translator, expand the Core Metrics folder and open the StudentAttendance project and expand the TardyRate folder.

The Translators involved in calculating the Student Tardy Rate for Last X (Last 20 days), Last Y (Last 40 days), and Year to Date use the LastXDaysTardyMetricTranslator, LastYDaysTardyMetricTranslator, and YearToDateTardyMetricTranslator classes. Inspecting the code for each Translator, they all use the helper class TardyRateHelper to inform the translators which attendance event categories to include in the calculation.

    public class TardyRateHelper : DailyAttendanceRateHelperBase
    {
        private static readonly HashSet<AttendanceEventCategoryDescriptor> Tardy = DescriptorResolver.GetSet<AttendanceEventCategoryDescriptor>("Tardy");

        public TardyRateHelper()
            : base(Tardy) {}

        public override int GetNumerator(int events, int total)
        {
            return events;
        }
    } 
  • Update the TardyRateHelper class in the TardyHelper.cs file to also accept the "Early departure" category and rebuild the solution.
    public class TardyRateHelper : DailyAttendanceRateHelperBase
    {
        private static readonly HashSet<AttendanceEventCategoryDescriptor> Tardy = DescriptorResolver.GetSet<AttendanceEventCategoryDescriptor>("Tardy", "Early departure");

        public TardyRateHelper()
            : base(Tardy) {}

        public override int GetNumerator(int events, int total)
        {
            return events;
        }
    }
  • Re-run the SpecFlow tests for the Student Tardy Rate feature.

Student Tardy Rate will now include the "Early departure" attendance category. 

Example 2: Extend the Student Failing Subject Area Course Grade Metric

In this example, we'll be extending the Student Failing Subject Area Course Grades metric to Create a Separate "Foreign Language and Literature" Course metric calculation.

In the as-shipped configuration, the Student Failing Subject Area Course metric calculation only provides failing course grade calculations for Mathematics, Reading/ELA, Science, Social Studies, and Writing. We'll create a new student failing course Translator for "Foreign Language and Literature" course grades.

Prerequisites

This lab has the following prerequisite steps:

Create New Metric ID 

Using the Metric Configuration Tool, create a new metric ID for the Foreign Language and Literature Student Failing Course Grades metric. For this example, we'll create the metric ID 10001.

Update SpecFlow Tests

To ensure that the Translator is written correctly, we will update the existing SpecFlow test to include failing grades for a Foreign Language and Literature Student Failing course.

  • Navigate in File Explorer to where you have cloned the code from GitHub. 
  • Open the "EdFi ETL.sln" file in "Etl\src".
  • Open the StudentFailingSubjectAreaCourseGrades.feature file in the Edfi.MetricBusinessLogic.Tests project under the StudentCourseGrades\FailingSubjectAreaCourseGrades folder.

You will see the first SpecFlow test described below. Based on the business rules defined in Student - Failing Subject Area Grades, any grades with a rank equal or lower than the metric threshold will be included in the metric calculation. For this SpecFlow scenario grading scale, a C or lower is considered a failing grade. 

  • Enroll the student in a Foreign Language and Literature course and give the student a failing grade.
  • Save the SpecFlow feature file, it will regenerate the StudentFailingSubjectAreaCourseGrades.feature.cs file which contains the NUnit test representation of the SpecFlow feature file. 

In this example we are only updating the first SpecFlow scenario. For full test coverage, all scenarios in the StudentFailingSubjectAreaCourseGrades should be updated to test for the failing Foreign Language and Literature course metric.


Execute SpecFlow Tests

  • Execute the SpecFlow tests for the StudentFailingSubjectAreaCourseGrades.feature file by right-clicking on the StudentFailingSubjectAreaCourseGrades.feature.cs file in the Solution Explorer and select Run Unit Tests (see How To: Execute SpecFlow Tests in the ETL Solution for more information). The BusinessRuleStudentSubjectAreaCourseGrades_Failing scenario will fail since the Student Failing Course Translator is not calculating a metric for the Foreign Language and Literature Student course.

Add New Metric to Metric Enumerations

  • Navigate to EdFi.Common/Enumerations/Metric.cs and locate the existing metric enumerations for student subject area failing subject area grade metrics. 
  • Add the new metric enumeration. Specify the metric ID, metric description, and default goal value. The default goal is not used for this metric, so it can be set to 0.
public static readonly CourseGradeMetric StudentFailingSubjectAreaCourseGradesForeignLanguageAndLiterature = new CourseGradeMetric(10001, "Foreign Language and Literature", 0);

Add New FailingSubjectForeignLanguageAndLiteratureTranslator Class

  • Add the new Failing Foreign Language and Literature Course Grade metric Translator by expanding the Core Metrics folder, opening the StudentCourseGrades project, and expanding the FailingSubjectAreaCourseGrades folder.

  • Create the new FailingSubjectForeignLanguageAndLiteratureTranslator class. The base class takes the arguments IBus, the student failing subject area course grade container metric, and the metric that was created in the step above. Since this is a granular metric, it does not publish a container-level metric. We will need to provide the academic subject type to which the Translator corresponds.
  • Rebuild the solution.
    public class FailingSubjectForeignLanguageAndLiteratureTranslator : FailingSubjectAreaCourseGradesCalculator
    {
        public FailingSubjectForeignLanguageAndLiteratureTranslator(IBus bus)
            : base(bus, Metric.StudentFailingSubjectAreaCourseGrades, Metric.StudentFailingSubjectAreaCourseGradesForeignLanguageAndLiterature) { }

        protected override bool ShouldPublishContainerLevelMetric
        {
            get { return false; }
        }

        protected override IEnumerable<AcademicSubjectDescriptor> SubjectTypes()
        {
            yield return DescriptorResolver.Get<AcademicSubjectDescriptor>("Foreign Language and Literature");
        }
    }
  • Re-run the SpecFlow tests for the Student Failing Subject Area Course Grades feature.

At this point, the Student Failing Subject Area Course Grades metric calculation has been extended to generate a metric calculation for Foreign Language and Literature course grades.