Skip to end of metadata
Go to start of metadata

In this example, we will create a new domain entity called Student Transportation. This entity will be exposed in Ed-Fi ODS / API through a new API resource called studentTransportations. 

Before you begin:

  • This example uses MetaEd to generate extended artifacts and documentation. MetaEd is a free tool developed by the Ed-Fi Alliance, and is the recommended way to add new fields to the Ed-Fi ODS / API. You should download and install MetaEd before beginning. This example goes step-by-step, so it's okay if you've never used MetaEd before. If you prefer to generate extended artifacts manually instead of using MetaEd, steps are listed in Appendix A of this page.
  • This example assumes that the Ed-Fi ODS / API has been successfully downloaded and is running in a local development environment per the instructions in the Getting Started documentation.

The steps can be summarized as:

Each step is outlined in detail, below. 

Step 1. Design Your Extension

In a real project, you would take the preliminary step of designing your extension. We'll propose a design.

This example will create a new Student Transportation entity. The ODS / API data model has elements related to transportation (such as a School entity and a Student entity), but there is no means to store student bus assignments, or the distance from a student's home to school. We'll add those in our new entity, and relate our new entity to existing parts of the data model.

The following is a diagram is a sketch showing the new Student Transportation entity (on the left), along with its properties. Our new entity relates to School and Student, entities which are already present in the ODS / API data model. These existing entities are shown in gray (on the right).This example is simple, but illustrates most of the essential concepts required to extend the Ed-Fi ODS / API. Let's continue with the mechanics.

Step 2. Author Your Extension Using MetaEd

In this step, we'll create a new project in MetaEd, and author our new entity. It's easy – but you do need to download and install MetaEd to do this step. Do that now if you haven't already.

Step 2a. Set or Confirm MetaEd Target Version

MetaEd allows you to target different versions of the Ed-Fi technology stack and data model. Confirm that your MetaEd IDE is targeting v3.0 by following the instructions in the Version Targeting documentation for the MetaEd IDE.

The desired model for the latest ODS / API is "ed-fi-model-3.0".

Step 2b. Create a New Extension Project

In the MetaEd menu, click Create New Extension Project.

Navigate to the desired location for the extension project and click New folder.

Create a folder for the extension project, select the new folder, and click Select Folder.

The new extension project appears in the tree view below the core model.


Step 2c. Update the package.json File

Open the package.json file by double-clicking on the file in the tree view to the left and provide an appropriate name for your project. In this case we will call it "Extone".

Click File > Save (Ctrl + S) to save your changes.

Step 2d. Add a Domain Entity File to Your Project

We're going to add a Domain Entity source file to the project we just created.Note that MetaEd files are required to be organized into subfolders. Folders are generally named after their entity type. The core ed-fi-model project provides examples of subfolder naming.

Right-click on the extension project folder and click New Folder.

Name the folder DomainEntity and press Enter.

Now we'll add a MetaEd source file to the folder we just created. Adding source files is easy: each type of file has a template that already contains source code basics.

Right-click on the new folder, choose Add MetaEd File > DomainEntity. This creates the source file including the template language.

Note the new file appears in the tree view to the left. Double-click on the file in the tree view to open it. The opened file provides a short sample of the appropriate syntax for a Domain Entity. 

Step 2e. Author and Save Your Extension

Right-click on the newly created MetaEd file in the tree view to the left and click Rename.

Name the file StudentTransportation to match the name of the new entity to be created. Press Enter.

We'll replace the template text with the details about the resource we're trying to create. Note that the blue dot on the tab for the open file indicates the file has been changed but the changes have not been saved.

Type or copy and paste the code listing below into your MetaEd file:


MetaEd Source for StudentTransportation Entity
Domain Entity StudentTransportation
    documentation "StudentTransportation"
    domain entity School
        documentation "The school to and from which the student is being transported."
        is part of identity
    domain entity Student
        documentation "The student being transported."
        is part of identity
    string AMBusNumber
        documentation "The bus that delivers the student to the school in the morning."
        is part of identity
        max length 6
    string PMBusNumber
        documentation "The bus that delivers the student home in the afternoon."
        is part of identity
        max length 6
    decimal EstimatedMilesFromSchool
        documentation "The estimated distance, in miles, the student lives from the school."
        is required
        total digits 5
        decimal places 2

 Click FileSave (Ctrl + S) to save your changes.

Step 3. Generate Extended Technical Artifacts Using MetaEd

In this step, we'll build our new MetaEd project. This is fairly straightforward.

Step 3a. Build Your Project

Click Build in the MetaEd menu to generate artifacts.

Artifacts build successfully.

Step 3b. View MetaEd Output

You can expand the project in the tree view and click "MetaEdOutput" to explore generated artifacts. The artifacts include technical output such as SQL scripts, API metadata and XSD used by the code generation, but also updated documentation such as data dictionaries that add your extension definitions to the ODS / API documentation.

We'll look at how to use this MetaEd output in your code below. First, we'll need to set up our extension project in Visual Studio.

Step 4. Create Extension Project in ODS / API Solution

This step will create the C# Extension files necessary to build your extended solution. This step assumes you've successfully downloaded and can run the ODS / API in a local development environment per the instructions in the Getting Started documentation. Do that now if you haven't already.

Step 4a. Set Up the C# Project Template

 Visual Studio Project Templates can be installed by following steps in Getting Started - Project Templates Installation section of this documentation.

Step 4b. Create new Extension Project

4b.1. To add a project to your Ed-Fi-Ods Visual Studio Solution, right-click on the Ed-Fi Extensions Folder. Select Add > New Project.

4b.2. Select  the Ed-Fi  API Extensions Project Template option. Make sure you choose Microsoft .NET Framework 4.6.2 or above. In the Name: field enter EdFi.Ods.Extensions.Extone and click OK. 

Note

To ensure MetaEd outputs are correctly deployed to ODS/ API extension project, the last section of the project name should match the namespace you provided in Step 2.c with the first character upper-cased. 

Step 4c. Rename the "marker" interface file

4c.1.  Right-click on the Marker_EdFi_Ods_Extensions_ExtensionName.cs file in newly created EdFi.Ods.Extensions.Extone project and Rename the file to Marker_EdFi_Ods_Extensions_Extone.cs.

4c.2. When prompted choose to rename all references to the code element Marker_EdFi_Ods_Extensions_ExtensionName.

Step 4d. Integrate Extension into the Solution

In this step, we'll integrate the extension into the solution.

4d.1. Locate the EdFi.Ods.WebApi project, within the "Entry Points" folder. Right-click, select Add > Reference..., then select the EdFi.Ods.Extensions.Extone project.

4d.2. Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file.

First, add a line to include the Extone assembly:

EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
using EdFi.Ods.Extensions.Extone;

Next, locate the EnsureAssembliesLoaded method in the same file and add a line for the new extension assembly marker to ensure it is loaded at runtime.

EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Extensions_Extone>();

Step 5. Deploy your Extended Artifacts to the ODS / API Solution

In this step, we'll use the MetaEd "Deploy" feature and integrate the files you've generated with the ODS / API Solution. The MetaEd IDE can deploy the generated artifacts necessary for an ODS / API build of an extension project. These include the generated SQL, generated XSD, and other material.

You can easily configure the MetaEd IDE to copy the generated files to the correct locations for the ODS / API project.

Step 5a. Confirm MetaEd Deployment Settings

Ensure that your Ed-Fi ODS / API source directory is set properly in the MetaEd IDE settings.Under the "MetaEd" menu, select "Settings..."

Update the "Ed-Fi ODS / API source directory" to point to the folder that contains the Ed-Fi-ODS and Ed-Fi-ODS-Implementation folders.

Step 5b. Deploy Your Extended Artifacts

Deploy by selecting MetaEd > Deploy from the menu bar. Click OK in the confirmation dialog.

This will run a new build of all artifacts, and the artifacts required for your Extended ODS / API project will be copied over to the correct locations.For instructions on how to perform the steps manually, see Appendix A, below.

Step 6. Run Code Generation and Verify Changes 

Save all modified files, close Ed-Fi-ODS.sln, and re-run the code generation steps outlined in the Getting Started Guide, (i.e., from a PowerShell prompt run Initialize-PowershellForDevelopment.ps script, followed by the initdev command). Then, run the application and view the Ed-Fi ODS / API in the Swagger UI. The following new API resource should be visible:

Next Steps & Further Information

Congratulations, you've successfully extended an instance of the Ed-Fi ODS / API.The Ed-Fi Extension in this example is fairly simple. It's a good place to start, but most enterprise users have more complicated needs. The following links are useful for developing more complex extensions and getting the development work into production.

Appendix A: Adding Manually Created Extensions

Step 1. Set Up the C# Project Template

Visual Studio Project Templates can be installed by following steps in Getting Started - Project Templates Installation section of this documentation.

Step 2. Create new Extension Project

2.1. To add a project to your Ed-Fi-Ods Visual Studio Solution, right-click on the Ed-Fi Extensions Folder. Select Add > New Project.

2.2. Select  the Ed-Fi  API Extensions Project Template option. Make sure you choose Microsoft .NET Framework 4.6.2 or above. In the Name: field enter EdFi.Ods.Extensions.Extone and click OK. 


Step 3. Rename the "marker" interface file

3.1.  Right-click on the Marker_EdFi_Ods_Extensions_ExtensionName.cs file in newly created EdFi.Ods.Extensions.Extone project and Rename the file to Marker_EdFi_Ods_Extensions_Extone.cs.

3.2. When prompted choose to rename all references to the code element Marker_EdFi_Ods_Extensions_ExtensionName.


Step 4. Integrate Extension into the Solution

In this step, we'll integrate the extension into the solution.

4.1. Locate the EdFi.Ods.WebApi project, within the "Entry Points" folder. Right-click, select Add > Reference..., then select the EdFi.Ods.Extensions.Extone project.

4.2. Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file.

First, add a line to include the Extone assembly:

EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
using EdFi.Ods.Extensions.Extone;

Next, locate the EnsureAssembliesLoaded method in the same file and add a line for the new extension assembly marker to ensure it is loaded at runtime.

EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Extensions_Extone>();


Step 5. Add Extension Metadata

The code listings in this section use the sample extension material from Ed-Fi-ODS/Samples/Extensions/StudentTransportation.

5.1. Map Supporting Artifacts

  • Copy the metadata files to the implementation project.
<source directory>\Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTransportationMetaEd\MetaEdOutput\extone\Database\SQLServer\ODS\Structure =>
<source directory>\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Extensions.Extone\SupportingArtifacts\Database\Structure\EdFi

<source directory>\Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTransportationMetaEd\MetaEdOutput\extone\ApiMetadata =>
<source directory>\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Extensions.Extone\SupportingArtifacts\Metadata

<source directory>\Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTransportationMetaEd\MetaEdOutput\extone\XSD =>
<source directory>\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Extensions.Extone\SupportingArtifacts\Schemas

Step 6. Run Initdev

Save all modified files, close Ed-Fi-ODS.sln, and re-run the code generation steps outlined in the Getting Started Guide, (i.e., from a PowerShell prompt run Initialize-PowershellForDevelopment.ps script, followed by the initdev command). Then, run the application and view the Ed-Fi ODS / API in the Swagger UI. The following new API resource should be visible:

Downloads

The following GitHub links contain source files for this extensibility sample.

  • No labels