Lesson Plan

Options and Prerequisites

(Highly Recommended) Prerequisites

Bring a laptop!

This lab is intended to be hands-on for everyone who attends, therefore all attendees are expected to bring a laptop.

Attendees will use their computer to either connect remotely to provided Virtual Machines to follow the steps in this lab, or use their own Windows laptop for those who are able to.

Prepare your computer or your cloud environment!

Some attendees will want to focus on an enterprise deployment while others will want to use the one of the options provided on the Ed-Fi Exchange for cloud deployments (AWS, Azure) or local install.

Azure tenancy prerequisite:

You can use an existing Azure subscription and login provided you are Co-Owner (Co-Admin is not sufficient)
Or, you can setup free Azure subscription at portal.azure.com, that provides a $200 credit (you will be owner Global Admin). You can choose to do this ahead of time or wait for the session, where we will answer any questions.

Note that the free Azure subscription requires a credit card!

AWS tenancy prerequisite:

AWS requires rights to add permissions to the global <updating>

Laptop prerequisites:

  • Install a Remote Desktop Client for your platform. Available in the App Store for Macs.  Options include VNC or Remmina for Linux platforms.
  • If using a Windows laptop, install Powershell support.


Use a provided virtual machine to:

  1. Follow the enterprise deployment for the first time.
  2. Use the Windows Installer (community-based) on the virtual machine if you aren't able to load the prerequisites on a Windows-based computer.
  3. Create your Microsoft Azure-based cloud environment but you don't have a Windows laptop with Powershell support.
  4. You don't need a VM for an AWS deployment unless you are having trouble with your laptop.

Use your own workstation to:

  1. Deploy to Amazon AWS.
    1. You will need a Remote Desktop Client for your platform (available for Mac and Linux) if you wish to connect to your instance but no special configuration is needed.
  2. Deploy on Azure if you have a Windows laptop.
    1. You must configure your Windows laptop with Powershell support. 
    2. Windows should also have a Remote Desktop Client installed.
  3. Use the Windows Installer
    1. You must complete the download and installation of prerequisites found in the installation doc on the Exchange.
  4. Create a development environment with the enterprise deployment prior to attending the session
    1. You must follow the steps to download, configure and deploy the Ed-Fi ODS/API as found in the Getting Started Guide for either version 3 or version 2.5.  

"I'm supposed to deploy something..?"

(or - Governance is the Answer.  What was the question?)

The Ed-Fi ODS/API is a reference implementation of the Ed-Fi Universal Data Model and API specification.  It is provided as downloadable source code on GitHub, using Microsoft .NET, SQL Server, and appropriate deployment scripts for an enterprise Windows environment.  The members of the community built and shared deployment artifacts for compatible cloud providers in addition to a standalone installer package, all of which are hosted on the Ed-Fi Exchange.  During this lab, you will choose one of these approaches and deploy your own Ed-Fi ODS/API.

Becoming an effective Ed-Fi Agency

Becoming an effective Ed-Fi Agency means adopting a mindset across the entire district of:

  • Focusing on value for instructors, curriculum, assessment, and leadership teams
  • Starting with the ends in mind and delivering on promises
  • Communicating with stakeholders, including vendors, partners, administrators, and your community.
  • Sharing your experiences, good or bad.

These are the foundation of governance that education agencies often look to their IT departments to implement.  However, governance is not an IT process, it is an institutional mindset of implementing patterns of success.

Explaining data interoperability to your instructors and administrators

The hardest job for a technical team member is convincing your instructional or assessment staff of why they should care about the Ed-Fi Standard, about how a common language to work with other teams helps get what they want done.  Until you can show them, you'll have to use some specific examples of how the lack of interoperability wastes their time and limits their ability to act.

Deployment scenarios and example solutions

The Ed-Fi ODS/API is a multi-tenant solution which can be deployed for statewide use or use by individual districts.  For the purposes of this lab, we'll focus on setting up a development environment for you to use while developing and testing API connections from your source systems or ETL processes.

For more information on production deployments, refer to the Platform Development Guide for the version you are interested in on Techdocs.

Hands-On with the Ed-Fi ODS

Connecting to your development environment

Virtual Machines are provided during the live lab to make it easy to dive in.  These VMs are provided with the following software: Window 10, Microsoft SQL Server 2014 Developers Edition, Visual Studio 2017 Community, Git client, and any dependencies.

Get Running

Standard development build

Go directly to the Getting Started Guide if you want to go for it with a local install on your laptop.

If you want to use the VM to build and play, follow along here

  1. Connect to your VM
  2. All of the steps to download and configure your development environment, including installation of software prerequisites SQL Server 2014 and Visual Studio 2015, have been done.
  3. The projects in the Ed-Fi-ODS-Implementation repository are configured to run the desktop version of Internet Information Server (i.e., IIS Express). This server is installed with Visual Studio and facilitates easy debugging with minimal configuration.
  4. Confirm the startup projects are set, right-click on the
  5. You are ready to run or debug the Ed-Fi ODS / API.
    • To run the Ed-Fi ODS / API without debugging, press Ctrl+F5.
    • To interactively debug the Ed-Fi ODS / API solution, press F5 (or press Start in the Standard Toolbar).

  • The first time you build the solution, you may get a build error related to the Ed-Fi-Common project. If this occurs, simply building the solution again will generally result in a successful build.

The solution builds and starts each of the projects that were added to the startup projects list. Each web application starts an instance of IIS Express. By default, the websites are configured according to the following table:







Sandbox Administration



Ed-Fi ODS API Documentation



Congratulations! You are up and running!

Cloud installation on Azure

If you encounter any errors the Troubleshooting and Tuning an Installation guide may be able to help diagnose and correct.

Know your Azure login and setup:

  • Download the Cloud ODS and API
  • Open PowerShell in Admin mode and setup your workstation correctly with AzureRM: 

Install-Module -Name AzureRM -RequiredVersion 4.3.1 -AllowClobber

  • You may need to "Unblock" the ZIP file you downloaded. To do that:
    • In Windows Explorer, right-click each of the downloaded ZIP files and select Properties.
    • On the General tab, press Unblock to allow the contents of the contained scripts to execute properly.
    • Note that Windows 10 will display an "Unblock" checkbox only if necessary. If you don't see that checkbox then unblocking is not necessary.

  • From the place where you downloaded the package, (unpack it and) run:

.\Deploy-EdFiOds.ps1 -ResourceGroupLocation "South Central US" -InstallFriendlyName "My ODS"

  • And in a short bit:

  • Copy the URL shown in the PowerShell window:

  • And launch the Admin App to continue setup. (Click the button to continue of course.)

  • Now get your license

Congratulations! You are up and running!

Cloud installation on Amazon AWS

Prerequisite Steps

There are two important prerequisites that must be done before you can provision your Ed-Fi ODS/API environment.

First, you need an encryption key pair for administrative access to your AWS EC2 deployment. If you haven't already setup your AWS EC2 key pair, follow that step below.
Second, you must have SSL certificates available in your AWS Certificate Manager for use by the Ed-Fi endpoints. It is possible to use a self-signed certificate for initial setup, but due to the high security requirements of AWS, you will not be able to use the Admin App, but it will be installed. Once you have a properly configured certificate, the Admin Panel will function normally.

You should also make sure that if you are using the AWS IAM-based login, that your IAM account has sufficient privileges to create S3 "storage buckets" and to create EC2 instances (i.e., servers).

Get started

Once you have satisfied those prerequisites,

  1. Download the ZIP file from the Ed-Fi Exchange to your laptop and unpack it. (You'll use these files later.)
  2. Log into the AWS Management Console.
    1. IAM accounts: Log in at https://accountname.signin.aws.amazon.com/console.
    2. Root accounts: Log in at https://console.aws.amazon.com/.
  3. Click Services > CloudFormation.
  4. At the top right-hand corner, click the region selector, and choose one of the regions in the United States to hold all of your creation.

  5. Click the Create New Stack button.
  6. Select Upload a template to Amazon S3 radio button and click Choose File. Browse to the “odsnetwork.template” CloudFormation template file and upload. Click the button Next.

  7. Fill out the Specify Details form using the following steps for each field:
    1. Stack Name: "Ed-FiODSAPIv2-5".
    2. EdFi S3 Bucket and EdFi S3 Bucket Region: Leave this default value.
    3. Key Name: (drop-down menu) The name of the EC2 Key Pair in your AWS Account to secure all server passwords in the system. (Problems? See the step-by-step procedure for creating an EC2 Key Pair below.)
    4. Selected Instance Type: Economy
    5. SSL.CertId: Specify the AWS Resource Number (e.g., ars:aws:acm:… ) that identifies the X.509 Secure Socket Layer certificate used to encrypt/decrypt HTTPS communications.
      This identifier can be found in the AWS Certification Manager. (Problems? See the step-by-step instructions for creating and storing an SSL certificate below.)
    6. Finally, click Next.
  8. On the following Options screen, simply click Next.
  9. On the following Review screen, scroll to the bottom of the page, and check the checkbox to allow permission for the build.
    After you have launched your system, you are free to delete this role via the AWS Management Console ≫ Services ≫ IAM ≫ Roles ≫ ServerS3andRDSRole ≫ Delete.
  10. Click Next.
  11. Monitor the Outputs tab once active and use the WebServerSetupStatusURL which indicates completion of the build.
  12. Once that displays "The system is ready for use", congratulations! you have provisioned an Ed-Fi ODS/API !

Refer to the Outputs tab

WebAPIEndpointURL - The API URL you'll test next.
ODSAPIKeySecret - The Initial authentication credentials. (Normally you'd change these immediately after testing in database table EdFi_Admin.dbo.ApiClients.)
JumpServerPublicDNSName You will need to connect to this machine in order to use the Admin App, which runs on the BuildServer. The Build Server address can be found under CloudFormation service >> Stacks >> stack-name ≫ Instances.

Smoke test of your Ed-Fi ODS/API
  1. Open a Command Prompt on your laptop.
  2. Using the WebAPIEndpointURL from your Outputs tab, e.g. WebAPIEndpointURL = https://ed-fiodsa-odsapilo-fwkv3f9r7r81-1078570745.us-east-2.elb.amazonaws.com/EdFi.Ods.WebAPI
  3. $ signs indicate things to substitute (copy and paste) on the command line

curl {$WebAPIEndpointURL}/oauth/authorize -d "Client_id=productionAPIkey&Response_type=code"
curl {$WebAPIEndpointURL}/oauth/token -H "Content-Type: application/json" -d "{'Client_id':'productionAPIkey','Client_secret':'productionAPIkeySECRET','Code':'{$WebAPIKey}','Grant_type':'authorization_code'}"
curl {$WebAPIEndpointURL}/api/v2.0/2017/schools -H "Authorization: Bearer {$WebAPIAuthCode}"

If you see a list of schools, congratulations! Your Ed-Fi ODS is up and running!

Connect to the Admin App

Locate the Jump Server DNS Name and connect to that using RDP.

<detail here>

Connect from the Jump Server to the Build Server. You can find the Build Server in the list of EC2 machines.

On the build server, you can access the Admin App locally: https://localhost/EdFi.Ods.AdminApp.Web

Optional setup tasks

Setting up the EC2 Key Pair

To remotely log into the Windows servers in your Ed-Fi ODS system, you will need a user name and password with administrative-level access. The user name is always administrator. The password, however, is randomly generated, and must be retrieved from the EC2 Service Panel using something secret that you possess - the private key of an EC2 Key Pair. Let's create a key pair:

  1. In the AWS Management Console, ensure the Region Selector in the upper-right corner is the same region in which you will launch your Ed-Fi ODS network. Then, click Services, then click EC2, then click Key Pairs, then click Create.
  2. Enter "EdFi Key Pair" for the Key Pair to be created. Then click Create.

  3. The private key is automatically downloaded to your browser as a *.pem file which is a text file containing the private key. When prompted for this key later, you can paste the text or browse to and upload the *.pem file.
  4. You will use the private key you downloaded when you click the Connect / Action button (Management Console >> Services >> EC2) to retrieve the administrator password and use it to log into the system.

Creating a Self-Signed Certificate to test the API

Reminder: self-signed certificates can't be used by the Admin App without configuring the IIS application server to ignore SSL (Usually a bad idea!)

Note for Windows: Install the Git for Windows package which includes a Git Bash command line and the OpenSSL binaries. You can also download the openssl binaries from a third party.

Note for non-Windows: OpenSSL is normally installed by default on most systems. Use your normal system package manager to install OpenSSL if it is not installed.

  1. Substituting the appropriate region for "us-east-2", use this command at a prompt where OpenSSL is installed:
    openssl req -x509 -sha256 -newkey rsa:2048 -keyout yourPrivateKey.pem -out yourNewCertificate.pem -days 365 -nodes -subj "/C=US/ST=Texas/L=Austin/O=Company Name/OU=Org/CN=*.us-east-2.elb.amazonaws.com"
  2. Import the certificate and private key (from the two *.pem files created by the command in the previous step) to the AWS Certification Manager
  3. Returning to the AWS Management Console, click ServicesCertificate Manager in the section "Security & Identity".

  4. Next, click the button Import a certificate.

    1. Certificate Body: Using Notepad or other text file editor, open the yourNewCertificate.pem certificate file and copy and paste its contents into the Certificate Body text box.

    2. Certificate Private Key: Likewise, copy and paste the yourPrivateKey.pem file's contents into this text box.

    3. Certificate Chain: Leave this text box blank.

    4. Click the button Review and Import.

  5. Click Import on the resulting screen.

  6. Finally, RECORD the ARN value from the resulting screen. This is the text value that must be entered into the CloudFormation Template.

Using the Web Apps

Use the Admin App


Walk through of API

The API, subsets, and extensions

“Things I wish I had known."

Answers to Your Questions

Next Steps

  • No labels