This document explains how to upgrade an existing v2.x ODS / API to version 3.1. The ODS v3.1 database update includes the latest enhancements based on feedback from the Ed-Fi Community. 

The steps can be summarized as:

 A compatibility reference chart, a command-line parameter list, and a troubleshooting guide are included. Each upgrade step is outlined in detail below. 

Step 1. Read the Ed-Fi ODS v3.1 Upgrade Overview

Before you get started, you should review and understand the information in this section.

Target Audience

These instructions have been created for technical professionals, including software developers and database administrators. The reader should be comfortable with performing the following types of tasks:

• Creating and managing SQL Server database backups
• Performing direct SQL commands and queries 
• Execution of a command-line based tool that will perform direct database modifications
• Creating a configuration file for upgrade (.csv format)
• Writing custom database migration scripts (Extended ODS only)

General Notes

• Your v2.x of the Ed-Fi ODS / API will checked for compatibility automatically during the migration process. If changes are needed, you will be prompted at the command line by the migration utility. A summary of commonly encountered compatibility conditions has been included in this section for reference.
• The new v3.1 schema contains upgrades to the structure of primary keys on several tables. In most instances, these new uniqueness requirements will be resolved automatically for you with no action required.
• There are some areas where new identities cannot be generated automatically on your behalf during upgrade. These tables will need to be updated manually.
   

Step 2. Install Required Tools

• Ensure that you have an instance of the Ed-Fi ODS / API running locally that has been set up following the instructions in Getting Started - Installation Steps.

Step 3. Build the Ed-Fi ODS Migration Tool

• Open <source directory>\Ed-Fi-ODS\Utilities\Migration\Migration.sln in Visual Studio and build in Release mode.

Step 4. Back Up and Create a Working Copy of the 2.x Target Database

• Create a full backup of the target v2.x EdFi_Ods database.

• Restore this backup to your SQL Server instance as a copy, in a new location.
• Make note of the database connection string as it will be required for a later step.

Step 5. (Multi-Year ODS Only) Create a Calendar Configuration File

In most cases, you can skip this step if the ODS contains valid calendar data for only one school year. The migration tool will usually be able to resolve this item automatically for you.

The v3.x ODS upgrade includes enhancements to the calendar, including tracking of school year information for every calendar event and session. To ensure that your new calendar is accurate, the migration tool will need to know which school year to associate with every calendar item in your ODS. 

Example calendar configuration files can be downloaded from the download panel on the right. 

The following is an example of a calendar configuration file (CSV) for Grand Bend ISD:

SchoolId,SchoolYear,StartDate,EndDate
255901001,2011,2010-08-23,2011-05-27
255901044,2011,2010-08-23,2011-05-27
255901107,2011,2010-08-23,2011-05-27

Note that each line contains a SchoolId, SchoolYear, the first calendar day and the last calendar day of the school year.

• Create a new calendar configuration file (.CSV) by referencing the above examples. Your configuration file must match the following format (including header row):

SchoolId,SchoolYear,StartDate,EndDate
{Your_First_School_Id},20XX,{FirstDayOfSchoolYear},{LastDayOfSchoolYear}
{Your_Second_School_Id},20XX,{FirstDayOfSchoolYear},{LastDayOfSchoolYear}
...

• Store the configuration file in a location that is accessible by your SQL server

Step 6. (ODS with NO Extensions Only) Run the Migration Tool 

• Open a new command prompt and navigate to the Ed-Fi ODS Migration Console tool build location:

  CD {YourDevFolderHere}\Ed-Fi-ODS\Utilities\Migration\EdFi.Ods.Utilities.Migration.Console\bin\Release

• Launch the console tool. Modify the below example parameters to match your environment. Replace the example "uri://ed-fi.org" with the Namespace Prefix to insert for your new descriptors:

  .\EdFi.Ods.Utilities.Migration.Console.exe --Database "YOUR_DATABASE_CONNECTION_STRING_HERE" --CalendarConfigPath "C:\PATH\TO\YOUR\CALENDAR_CONFIG_IF_APPLICABLE.csv" --DescriptorNamespace "uri://ed-fi.org" --CredentialNamespace "uri://ed-fi.org"

• Notes for upgrades performed on a remote database
  • The calendar configuration file path provided during upgrade must be accessible by your SQL server for importing and validation.
  • The XML files used to create v3.1 descriptors are by default located in "\Utilities\Migration\Descriptors\3.1". This directory must also be accessible by your SQL server for importing. If you need to copy this directory to a new location, you may make use of the --DescriptorXMLDirectoryPath "C:\PATH\TO\YOUR\DESCRIPTOR\XML" parameter to point the migration tool to the new location of these items
• Users who are running the migration tool on an extended ODS must use the --BypassExtensionValidationCheck option during upgrade in order to allow the tool to make changes when extension dependencies are present.  
  • Details on upgrading an extended ODS are included in the steps below.

• The console tool will check your ODS for compatibility, and then proceed to perform an in-place upgrade on the specified database.
• If you encounter any compatibility messages or errors during upgrade
  • During the upgrade process, your ODS will be checked for compatibility with the latest version.  If changes are required, you may encounter a compatibility message, and the upgrade will stop.  
    Example
    
  • After making the required changes (or writing custom scripts), simply launch the upgrade utility again.  The upgrade will proceed where it left off and retry with the last script that failed.
  • See the Troubleshooting Guide below for additional guidance
• Once the process runs to completion with no errors, your upgrade is complete 
  
• For a summary of all available parameter options for the Ed-Fi ODS console-based migration tool, please see the included reference below.

Step 7. (Extended/Modified ODS Only) - Perform a Test Migration Without Extensions

• It is highly recommended that you first perform a test migration without your extension tables present in order to ensure that all core upgrade requirements have been met
  • On your ODS copy, temporarily drop all extension tables. 
  • Complete the migration process exactly as detailed in Step 6, above.
  • Once the migration has completed successfully on the core Ed-Fi data, restore your v2.0 ODS working copy from backup, including all extension tables, and proceed with the next step

Step 8. (Extended/Modified ODS Only) - Write Custom Migration Scripts for Extensions

Step 8a. Locate the Ed-Fi Migration scripts and review the current upgrade conventions

• The edfi migration scripts are located by default in <source directory>\Ed-Fi-ODS\Utilities\Migration\Scripts\.
• All SQL scripts are run in numerical order, with version-specific upgrade further categories.
• The v2.0 to V3.1 upgrade passes though v2.5 on the way. It will execute scripts in the following version directories:
  • v24_to_v25
  • v25_to_v31
    

The directory structure appears as follows:

Version-Specific Upgrade Step Details for v2.x to v3.1

The core upgrade script directory, 02 Upgrade, contains several upgrade steps for each version which are detailed below. You can insert custom scripts at any point in the process as needed for custom Extensions.

Step 8b. Write scripts to drop ALL foreign keys on your extension tables that depend on the edfi schema

• All edfi primary keys and indexes are dropped automatically during upgrade. The existence of any external constraint that depends on edfi data will result in an error state.
• You may insert these scripts in the following directory
  • Option 1: Insert with similar Ed-Fi scripts in directory/step: Scripts/02 Upgrade/{version}/## Drop Constraints
  • Option 2:  (To run before all upgrade tasks begin):  Scripts/00 Setup/{version}
    
• Scripts will be executed in numerical order. Number your scripts such that they run before the edfi scripts are executed. This will prevent a sql exception from occurring when dependent items on the edfi schema are dropped.
•  Tip: The following query can quickly identify all constraints that need to be dropped for migration to proceed. Use this as a guide when writing your custom migration scripts.

SELECT DISTINCT
		parentSchema.name AS 'External Schema Name',
		parentObject.name AS 'Table Name',
		constraintObject.name AS 'Constraint Name',
		CONCAT('References ', referencedSchema.name, '.', referencedObject.name) AS [Conflict Reason],
		CONCAT('ALTER TABLE ', parentSchema.name, '.', parentObject.name, ' DROP CONSTRAINT ',  constraintObject.name) AS [Example Code For Reference]
	FROM sys.foreign_key_columns fk
	INNER JOIN sys.objects parentObject
	ON fk.parent_object_id = parentObject.object_id
	INNER JOIN sys.objects referencedObject
	ON fk.referenced_object_id = referencedObject.object_id
	INNER JOIN sys.schemas parentSchema
	ON parentObject.schema_id = parentSchema.schema_id
	INNER JOIN sys.schemas referencedSchema
	ON referencedObject.schema_id = referencedSchema.schema_id
	INNER JOIN sys.objects constraintObject
		ON constraintObject.object_id = fk.constraint_object_id
	WHERE referencedSchema.name = 'edfi'
		AND parentSchema.name NOT IN ('edfi', 'migration_tempdata')
		AND parentObject.type = 'U'
		AND referencedObject.type = 'U'