Welcome to the Roster Starter Kit!

The Roster Starter Kit provides a step-by-step process that can be used to integrate rostering via the Ed-Fi ODS / API into a technology provider platform. 

Summary

Step 1. Analyze and Map Data

In this step, you will determine the data needs for the intended target platform and find resources on mapping that data to Ed-Fi.

Analyze

At this initial stage, you will need to determine the specific roster data elements that are needed to properly provision the target platform. If the platform is usually provided roster data via CSV files, remember that data from Ed-Fi in JSON format is much different. CSV files tend to repeat data and add elements that can otherwise be referenced in the Ed-Fi ODS / API. It may prove useful to start from the target platform's database schema in addition to, or instead of trying to use the CSV files to identify the set of data elements needed by the target platform.

Map

Once the specific data elements needed by the target platform have been determined, next you will go through the process of identifying the Ed-Fi source for each of those elements. Begin by looking through the Ed-Fi Enrollment API for Suite 3. This specification offers a synopsis of the Enrollment API, as well as, use cases, discussion, model diagrams, and additional considerations when pulling roster from the Ed-Fi ODS / API. There is also a public deployment of the Ed-Fi Enrollment API (as part of the Ed-Fi ODS / API Suite 3 v5.0.0). This deployment provides you with a way to interact with the Ed-Fi ODS / API via the Swagger UI and see sample data in the Ed-Fi JSON format. 

Step 2. Develop the Solution

In this step, you'll take the outputs from the previous step and use them during the development to transform the data retrieved from the Ed-Fi ODS / API to the persistence layer in the target platform. Also, additional functionality will be developed to ensure better usability by the end user.

API Client SDK

Using the OpenAPI specification files for the Ed-Fi Enrollment API, you can kick-start your development effort by generating an SDK using one of many tools available to generate API SDKs from an OpenAPI specification file. A thorough list of SDK generators is available in the SDK Generators section of the OpenAPI Tools page. You can also refer to the Ed-Fi ODS / API SDK Guide to walk through generating a SDK in C#. Once you have the foundational SDK generated, the data mapping information compiled in the previous step can be used to transform the data retrieved from the Ed-Fi API into the format needed by the target platform.

API Client Best Practices

Take the time to read through all the pages available in the Ed-Fi API Client Developers' Guide. It contains information that is helpful to round out the backend of the API client code that is being developed. The guide includes information from the initial OAuth2 client credentials flow authentication to obtain a bearer token to Error Handling and Best Practices. These best practices are drawn from experience gathered from implementation in the Ed-Fi community. 

Platform User Experience

Although some user experience is covered in the API Client Developers' Guide, platform-specific user experience features can be added after generating the SDK, and adding the translation layer to persist the data in the target platform. The user experience pieces are a crucial part of the development as this will determine the usability and functionality available to the users of the system. Usability best practices include having API configuration, API log, and error resolution screens, as well as auto or manual resend capabilities. All of these product features ensure the client can maximize their usage of the API integration. Though community experience, Ed-Fi has learned that the more information about the integration that you can make available to the clients, the more issues they are able to resolve on their own. In the end, the data standard defines the shape of the data, but user experience can determine the overall usefulness and value to the customer of that data integration in the platform. 

Testing

Initial testing can be done using the public deployment of the Ed-Fi ODS / API v5.0.0.

• Enrollment API

• Root URL

Additionally, if deeper testing and more control of the Ed-Fi ODS / API environment is needed, there are a number of ways to quickly set up an environment for internal testing purposes.

•  Ed-Fi ODS / API for Suite 3 v5.0.0 - Getting Started walks developers through setting up the Ed-Fi ODS / API codebase on a development machine.
• The /wiki/spaces/TSINSTALL/overview is a utility to run an installer on a server to have the Ed-Fi ODS / API installed on that server.
• A Quick Deploy of the Ed-Fi ODS / API Development Server has PowerShell scripts to initialize a server and install a development environment Ed-Fi ODS / API.

Step 3. Partner with a Client

In this step, you'll find a client partner and iterate the solution based on actual client usage feedback.

Find a Client Partner

The Ed-Fi Alliance has observed that the most successful Ed-Fi based native platform integrations have come out of working with a client partner on the final stages of development. When partnering with a client, you can better determine the needs of the customer based on their feedback and iterate the platform to make it more useable, relevant, and valuable to the customer. 

Conduct a Beta Phase

Once the client partner has been selected, begin by using a staging environment and the pre-release version of the Ed-Fi integration developed so far in the target platform. Next through feedback and customer use cases, iteratively refine the Ed-Fi integration. Though this work, finalize a solid, robust Ed-Fi component in the target platform that will benefit the customer's actual needs.

Move to Production

When both parties feel comfortable with the state of the Ed-Fi features in the target platform, move the system into production with the client. Maintain contact with the client during the early stages of the production deployment in the case other issues or needs are identified in that environment. Once all issues are identified and resolved in the production system, then support can be transitioned to the usual support channels of the target platform.

Step 4. Apply for an Ed-Fi Badge

Apply for an Ed-Fi Badge

At this stage, development has been rounded out and vetted through actual customer usage and the integration with a client partner has been promoted to the production environment. When this is achieved, the developed functionality of the target platform is eligible for an Ed-Fi API Consumer Badge. Review the requirements in Applying for a Badge in the Ed-Fi Badge Program space on the Ed-Fi Technical Documentation site and submit an application.