Skip to end of metadata
Go to start of metadata

This documentation covers the steps required for loading the Dashboard v3.0 for implementations using the Ed-Fi ODS v3.1. These instructions assume that you have already followed the UI Developers Guide - Installation.

The steps can be summarized as follows:

Detail about each step follows.

Step 1. Restore Sample Database

  • Glendale Sample Data Set. A robust sample set with around 47,000 students. This data set is used by the Alliance for dashboard development, unit testing, and integration testing.

To restore the sample data set:

  • Open a PowerShell window and navigate to C:\Ed-Fi\Database\ (presuming the installation path used in the Getting Started documentation was the recommended C:\Ed-Fi\).
  • If the SQL Server is not set up as the default instance (i.e., MSSQLSERVER), then run the command $env:db_server = ".\MyNamedInstance" to set up the named SQL Server instance.
  • By default, the script will restore the Glendale data set.
    • To restore the Glendale sample data set, execute $env:db_agency = "Glendale" from the PowerShell command window.
  • Run the command .\build rebuild 3.0  to restore the following:
    • The ODS v3.2 database  with the necessary views to support the ETL process.
    • The Application database with the necessary data to support the ETL process.
    • Blank copies of the Dashboard, Dashboard DW, and ETLLog databases.

Step 2. Configure the ETL app.config Settings

Locate the app.config file in C:\Ed-Fi\Etl\src\EdFi.Runtime\ and verify the following parameters are configured correctly. The most common configuration values to verify are the database connection strings and the OdsVersion value.

Database Connection Strings

NameDatabase (Default value is listed)
DashboardEdFi_Dashboard
WarehouseEdFi_DashboardDW
OdsEdFi (for Glendale sample ODS database)
ApplicationEdFi_Application
EtlLogDbEtlLogDb

Connection Strings
 <connectionStrings>
    <add name="Dashboard" connectionString="Data Source=(local);Initial Catalog=EdFi_Dashboard;Integrated Security=SSPI;Application Name=ETLRuntime" providerName="System.Data.SqlClient"/>
    <add name="Warehouse" connectionString="Data Source=(local);Initial Catalog=EdFi_DashboardDW;Integrated Security=SSPI;Application Name=ETLRuntime" providerName="System.Data.SqlClient"/>
    <add name="Ods" connectionString="Data Source=(local);Initial Catalog=EdFi;Integrated Security=SSPI;Application Name=ETLRuntime" providerName="System.Data.SqlClient"/>
    <add name="Application" connectionString="Data Source=(local);Initial Catalog=EdFi_Application;Integrated Security=SSPI;Application Name=ETLRuntime" providerName="System.Data.SqlClient"/>
    <add name="EtlLogDb" connectionString="Data Source=(local);Initial Catalog=EtlLogDb;Integrated Security=SSPI;Application Name=ETLRuntime" providerName="System.Data.SqlClient"/>
  </connectionStrings>

Application Configuration Settings

Config SettingsPossible ValuesDescription
MinimumLogLevelVerbose, Debug, Information, Warning, Error, FatalSets the logging level for the ETL. Performance may be affected if setting the logging level to 'Verbose'. The default is 'Error'.
EnableConsoleLoggingbooleanShows log output in console. The default is true.
SqlQueryCommandTimeoutintSets the SQL query command timeout. The default is 120.

The Dashboard v3.x is not compatible with previous versions of the ODS (v1.2, v2.0)

Metric Calculation Configuration Settings

Config SettingPossible ValuesDescription
ReportingPeriodLastXDaysint

For attendance calculations this provides range of instructional days to perform the metric calculation. The default reporting period for Last X Days in dashboards core is 4 weeks (20 instructional days)

ReportingPeriodLastYDaysintFor attendance calculations this provides range of instructional days to perform the metric calculation. The default reporting period for Last Y Days in dashboards core is 8 weeks (40 instructional days)
APScoreMasteryLevelint

For student advanced course mastery calculations, provides the threshold for AP score mastery. The default is 3.

IBScoreMasteryLevelint

For student advanced course mastery calculations, provides the threshold for IB score mastery. The default is 4.

DaysNeededForLateEnrollmentintFor student information calculations, provides the threshold to determine if a student has enrolled late. The default is 14.
IncludeWithdrawnStudentstrue, falseWhen true, students who have withdrawn from school or are not enrolled will be processed normally. If false, students not enrolled in school will be excluded from output and metric calculations. The default is true.

Advanced Configuration Settings

Config SettingPossible ValuesDescription
ExcludeExtensionListNames of metric packages (e.g., StudentAttendance, StudentCourseGrades)Comma-separated list of container metric projects to exclude from the ETL execution.
CacheAllQueriesbooleanCaches streamed objects in bus. Commonly used for debugging the ETL.
DryRunbooleanWhen DryRun is true the ETL does not write to the output databases. Commonly used for debugging the ETL.
UseFileBufferbooleanWhen the streamed data reaches the BulkCopyBufferSizeMax, the data in the buffer will be written to a file, to free up memory. The file will be read into SQL Server using SQL Bulk Copy.
FileBufferLocationPath to folder (e.g., C:\Windows\Temp)When UseFileBuffer is true, FileBufferLocation specifies the directory into which the file will be written. SQL Server must have permissions to read the directory. The ETL Runtime must also have permissions to write to the directory. The disk on which the directory resides must be able to store the amount of data being buffered to the server; this depends on the amount of data in the ODS. The hard drive requirements listed above will be sufficient for this process.
CalculateDailyHistoricalAttendanceboolean

Determines if daily historical attendance calculations should be performed. For improving ETL performance, the feature can be turned off, however, the historical attendance calendar on the UI will not show daily historical attendance. The default is true.

RebuildHistoricalCalculationsbooleanWhen true, the ETL will recalculate historicals for all time periods in the current school year. When false, the ETL will only calculate historical metrics for time periods that have not been completed previously. The default is true.
DashboardLinkstring

Used for advanced linked server configurations only: for most configurations, this option should be left as default, which is empty.

Linked server name for the instance containing the Dashboard.

For users with a linked server configuration where the Data Warehouse and Dashboard exist on different instances, ensure that the Data Warehouse has a linked server configured by this name with access to the Dashboard.

OdsLinkstring

Used for advanced linked server configurations only: for most configurations, this option should be left as default, which is empty.

Linked server name for the instance containing the ODS.

For users with a linked server configuration where the Data Warehouse and ODS exist on different instances, ensure that the Data Warehouse has a linked server configured by this name with access to the ODS.

App Settings
  <appSettings>
    <add key="DailyAttendanceCalculationSource" value="Both"/>
    <add key="ReportingPeriodLastXDays" value="20"/>
    <add key="ReportingPeriodLastYDays" value="40"/>
    <add key="APScoreMasteryLevel" value="3"/>
    <add key="IBScoreMasteryLevel" value="4"/>
    <add key="IncludeWithdrawnStudents" value="true"/>
    <add key="MinimumLogLevel" value="Information"/>
    <add key="EnableConsoleLogging" value="true"/>
    <add key="DryRun" value="false"/>
    <add key="DaysNeededForLateEnrollment" value="14"/>
    <add key="CalculateDailyHistoricalAttendance" value="true"/>
    <add key="RunOnlyYearEndSnapshot" value="false"/>
    <add key="RebuildHistoricalCalculations" value="true"/>
    <add key="ExcludeExtensionList" value=""/>
    <add key="SqlQueryCommandTimeout" value="1200"/>
    <add key="OdsVersion" value="3.1"/>
    <add key="CacheAllQueries" value="false"/>
    <add key="SessionTraceFlags" value=""/>

    <!-- SQL insert properties -->
    <add key="BulkCopyBufferSizeMin" value="4096"/>
    <add key="BulkCopyBufferSizeMax" value="1000000"/>
    <add key="BulkCopyBatchSize" value="4096"/>
    <add key="UseFileBuffer" value="false"/>
    <add key="FileBufferLocation" value="C:\Windows\Temp"/>

    <!--Linked Server Configuration -->
    <add key="DashboardLink" value=""/>
    <add key="OdsLink" value=""/>

  </appSettings>

Step 3. Configure Application Database

The following should be set up to ensure a successful ETL execution:

  • Grading scales for all grade levels should be configured. They can be set up in the UI when logged in as an Admin user under the Metric Settings tab.
  • For Algebra metric calculations, the dashboard.CourseLevelMapping table needs to be populated with Course Identity Codes that map to Algebra courses. For more information, see Algebra Course Level Mapping in the Metric Metadata Configuration section of this documentation.

Step 4. Compile and Run the ETL Solution

  • Open a PowerShell window and navigate to C:\Ed-Fi\Etl\.
  • Run the command .\build compile to compile the solution.
  • Navigate to C:\Ed-Fi\Etl\src\EdFi.Runtime\bin\Release\ and execute EdFi.Runtime.exe
    • The ETL runtime may take several hours to complete depending on the size of the ODS. This process can be monitored by looking at row counts in the metric.MetricInstance table in the Edfi_Dashboard DB or errors and warnings logged to the dbo.LogEntries view in the EtlLogDb.

Step 5. Build and Launch the Dashboards Web Application 

Return to Step 7 in UI Developers' Guide - Installation and repeat the steps to view the metrics in the Ed-Fi Dashboard.

Troubleshooting

This section contains troubleshooting tips for a few situations:

  • The EdFi.Runtime.exe exits immediately. Confirm that the database connection strings are configured correctly. Query the dbo.LogEntries view in EtlLogDb database for any exception info.
  • Need to re-run the EdFi.Runtime.exe after a successful completion. Simply execute EdFi.Runtime.exe again.

Next Steps & Further Information

This section contains links to helpful information found in other sections of this documentation:


ETL Developers' Guide Contents

Read more about the ETL Developers' Guide: