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

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 /wiki/spaces/METAED/pages/18940477 before beginning. If you prefer to generate extended artifacts manually instead of using MetaEd, steps are listed in Appendix A of this page.
• This example assumes knowledge of the basic concepts described in the How To: Extend the ODS / API - Student Transportation Example. If you're new to the Ed-Fi technology stack, or if you haven't used MetaEd before, then we suggest you run through that example first. 
• 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 0. Design Your Extension

In a real project, you would take the preliminary step of designing your extension, and analyzing how your needs map to the Ed-Fi ODS / API data model. We'll propose a design.

This example will create a new Student Transcript entity, which will carry information about where students enroll in college after graduation, a new element indicating whether graduates were part of a special education program, and some additional information about whether a transmitted record is an official or unofficial submission.

Based on our needs, we require a new entity (to contain information about postsecondary institutions) and we need to add some elements to existing entities. The following is a diagram is a sketch showing the additional entity and the new elements we're bolting on to existing Ed-Fi entities.

You'll notice that a few elements are shown with a type of "ed-fi descriptor." The Ed-Fi Descriptor is analogous to an enumeration. It's an Ed-Fi-specific design pattern that allows for enumeration-like within an operational context, but may vary between contexts. We'll see more about how these are implemented below.

This example is somewhat complex, but illustrates most of the advanced concepts required to extend the Ed-Fi ODS / API. Let's continue with the mechanics.

Step 1. Author Your Extension Using MetaEd

In this step, we'll create a new project in MetaEd, and author our new entity. You do need to /wiki/spaces/METAED/pages/18940477 to do this step. Do that now if you haven't already.

Step 1a. 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 /wiki/spaces/METAED/pages/18942405 documentation for the MetaEd IDE. 

The desired model for the latest ODS / API is "Ed-Fi-Model-3.0".

Step 1b. Create a New Extension Project

In the MetaEd menu, click Create New Extension Project. These steps are the same as the Student Transportation Example, so we won't cover the detail here. 

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

Step 1c. Update the metaEd.json File

Open the metaEd.json file by double-clicking on the file in the tree view to the left and provide an appropriate title and namespace for your project.

Click "Save" under the "File" menu or press Ctrl + S to save your changes.

Step 1d. Add MetaEd Source Files to Your Project

We're going to add seven new .metaed source files to the project we just created. You'll recall that MetaEd files are required to be organized into subfolders named after their entity type. The core ed-fi-model project provides examples of subfolder naming.

1d.1. Add Domain Entities.

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

Name the folder DomainEntity and press Enter.

Now we'll add two MetaEd source files to the folder we just created. Each type of file has a template that already contains source code basics.

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

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

Name the file "PostSecondaryOrganization" 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:

Note that errors will be listed in the linter panel until the referenced descriptors are created in a future step.

Domain Entity PostSecondaryOrganization
    documentation "PostSecondaryOrganization"
    shared string NameOfInstitution
        documentation "The name of the institution."
        is part of identity
    descriptor InstitutionLevel
        documentation "The level of the institution."
        is required
    descriptor InstitutionControl
        documentation "The type of control of the institution (i.e., public or private)."
        is required
    bool AcceptanceIndicator
        documentation "An indication of acceptance."
        is required

We'll now create a Domain Entity source file to add our new elements to the existing Student Academic Record entity. Note that we can extend an existing entity using the additions keyword (line 1 in the example below).

Domain Entity StudentAcademicRecord additions
    domain entity PostSecondaryOrganization
        documentation "A reference to the postsecondary organization."
        is optional
    descriptor SubmissionCertification
        documentation "The type of submission certification."
        is optional
    common extension ClassRanking
        documentation "Class Ranking Extension"
        is optional

1d.2. In this step, we'll extend the Class Ranking entity to add our new Special Education Graduation Status element. The steps are generally the same as the ones you used to add the domain entities above.

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

This time, we're extending an existing Common type, so we'll name the folder Common.

Right-Click on the new Common folder, select Add MetaEd File > Common. Name your new file "ClassRankingExtension.metaed."

Similar to how you extended the Student Academic Record domain entity above, you'll extend the Class Ranking entity with the keyword additions. Replace the template text in your new Common source file with the following code.

Common ClassRanking additions
    descriptor SpecialEducationGraduationStatus
        documentation "The graduation status for special education."
        is required

1d.3. In this step, we'll add the new Ed-Fi Descriptor entities.

If you're new to Ed-Fi technology, it's worth understanding the Ed-Fi Descriptor pattern because it occurs throughout the model. In essence, Descriptors provide states, districts, vendors, and other platform hosts with the flexibility to use their own enumerations and code sets. A Descriptor is consistent within an operational context such as a single district, but may be different in another operational context.

By now, the steps to create a new subfolder will seem familiar: Right-Click on the extension project folder and click "New Folder".

This time, we're adding Descriptors, so we'll name the folder Descriptor.

Right-Click on the new Descriptor folder, select Add MetaEd File > Descriptor. We''l be adding four Descriptor files in total. Name your first file "InstitutionControl.metaed."

Replace the template text in your new Descriptor source file with the following code.

Descriptor InstitutionControl
    documentation "The type of control for an institution (e.g., public or private)."

Voilà! Almost done. Follow the steps above and add the remaining three Descriptors.

Add an InstitutionLevel.metaed file.

Descriptor InstitutionLevel
    documentation "The typical level of postsecondary degree offered by the institute."

Add a SpecialEducationGraduationStatus.metaed file.

Descriptor SpecialEducationGraduationStatus
    documentation "The graduation status for special education."

Add a SubmissionCertification.metaed file.

Descriptor SubmissionCertification
    documentation "The type of submission certification."

At this point, your project in the MetaEd IDE should look like the following:

Step 2. Generate Extended Technical Artifacts Using MetaEd

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

Step 2a. Build Your Project

Click "Build" in the "MetaEd" menu to generate artifacts.

Artifacts build successfully.

Step 2b. 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 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 3. 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 3a. Set Up the C# Project Template

3a.1. Determine the location of the Visual Studio ProjectTemplates folder on your machine as follows:

• Open Visual Studio and go to Tools > Options > Projects and Solutions. 
• Get the value in the "User project templates locations". (The default location is C:\Users\[User]\Documents\Visual Studio 2015\Templates\ProjectTemplates.)

3a.2. Navigate to the location of the Extension template <source directory>\Ed-Fi-ODS\Utilities\VisualStudioProjectTemplates\Ed-Fi-Extension-Templates. Copy Ed-Fi-Extension-Assembly-Template folder to the  Visual Studio Project Templates folder (determined above). 

3a.3. Verify the Ed-Fi Extension Templates project type has been registered, by selecting File > New > Project and navigating to Installed >Templates > Visual C#.

Step 3b. Create new Extension Project

3b.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.

3b.2. Select  the Ed-Fi Extension Assembly Template option. In the Name: field enter EdFi.Ods.Standard.Extensions.Exttwo and click OK. 

Step 3c. Rename the "marker" interface file

3c.1.  Right click on the Marker_EdFi_Ods_Standard_Extensions file in newly created EdFi.Ods.Standard.Extensions.Exttwo project and Rename the file to Marker_EdFi_Ods_Standard_Extensions_Exttwo.

3c.2. When prompted choose to rename all references to the code element Marker_EdFi_Ods_Standard_Extensions.

Step 3d. Integrate Extension into the Solution

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

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

3c.2. Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file.

First, add a line to include the Exttwo assembly:

using EdFi.Ods.Standard.Extensions.Exttwo;

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.

AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Standard_Extensions_Exttwo>();

Step 4. 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 4a. 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 4b. 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 5. Security Configuration

PostSecondaryOrganization has no relationship to people or education organizations and therefore has no authorization strategy that can be applied to it.  It is in effect a stand alone table and will need an authorization strategy of 'NoFurtherAuthorizationRequired' for API requests to be made against it.  If security is desired, another authorization strategy can be implemented to handle this entity.  

To enable NoFurtherAuthorizationRequired, first create a security SQL script called 0001-PostSecondaryOrganization_No_Further_Auth_Required.sql and place it in the C:\Ed-Fi-ODS-Implementation\Database\Data\EdFiSecurity folder (Create 'EdFiSecurity' folder if it does not exist).  Copy the contents of the following SQL DML script into the newly created file and save.

DECLARE @AuthorizationStrategyId INT
DECLARE @ResourceClaimId INT
 
SELECT @AuthorizationStrategyId = AuthorizationStrategyId
FROM   AuthorizationStrategies
WHERE  AuthorizationStrategyName = 'NoFurtherAuthorizationRequired'
 
SELECT @ResourceClaimId = resourceclaimid
FROM   ResourceClaims
WHERE  ResourceName = 'postSecondaryOrganization'
 
INSERT INTO ResourceClaimAuthorizationMetadatas
SELECT ActionId,
       @AuthorizationStrategyId,
       @ResourceClaimId,
       NULL
FROM   Actions a
WHERE  NOT EXISTS (SELECT 1
                   FROM   ResourceClaimAuthorizationMetadatas
                   WHERE  Action_ActionId = a.ActionId
                          AND AuthorizationStrategy_AuthorizationStrategyId = @AuthorizationStrategyId
                          AND ResourceClaim_ResourceClaimId = @ResourceClaimId)

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 new postSecondaryOrganizations API resource should be visible, as well as the postSecondaryOrganizationReference in the studentAcademicRecord resource.

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.

/wiki/spaces/METAED/pages/18940507 This documentation provides excellent examples of common scenarios, from the simple to very complex.

Appendix A: Adding Manually Created Extensions

Step 1. Set Up the C# Project Template

1.1. Determine the location of the Visual Studio ProjectTemplates folder on your machine as follows:

• Open Visual Studio and go to Tools > Options > Projects and Solutions. 
• Get the value in the "User project templates locations". (The default location is C:\Users\[User]\Documents\Visual Studio 2015\Templates\ProjectTemplates.)

1.2. Navigate to the location of the Extension template <source directory>\Ed-Fi-ODS\Utilities\VisualStudioProjectTemplates\Ed-Fi-Extension-Templates. Copy Ed-Fi-Extension-Assembly-Template folder to the  Visual Studio Project Templates folder (determined above). 

1.3. Verify the Ed-Fi Extension Templates project type has been registered, by selecting File > New > Project and navigating to Installed >Templates > Visual C#.

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 Extension Assembly Template option. In the Name: field enter EdFi.Ods.Standard.Extensions.Exttwoand click OK. 

Step 3. Rename the "marker" interface file

3.1.  Right click on the Marker_EdFi_Ods_Standard_Extensions file in newly created EdFi.Ods.Standard.Extensions.Exttwo project and Rename the file to Marker_EdFi_Ods_Standard_Extensions_Exttwo.

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

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.Standard.Extensions.Exttwo project.

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

First, add a line to include the Extone assembly:

using EdFi.Ods.Standard.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.

AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Standard_Extensions_Extone>();

Step 5. Add Extension metadata

If you chose to generate Extension artifacts manually, copy them to SupportingArtifacts folder of Extension project you created in the previous step. For the purpose of this example we can use MetatEd Generated Extension Artifacts from the Download section.

Open command prompt and navigate to root of the ODS/API repository on your local drive. This is the folder that contains both Ed-Fi-ODS and Ed-Fi-ODS-Implementation repositories. Run the following copy commands:

xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTranscript\StudentTranscriptMetaEd\MetaEdOutput\exttwo\Database\SQLServer\ODS\Structure" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Standard.Extensions.Exttwo\SupportingArtifacts\Database\Structure\EdFi\*"
 
xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTranscript\StudentTranscriptMetaEd\MetaEdOutput\exttwo\ApiMetadata" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Standard.Extensions.Exttwo\SupportingArtifacts\Metadata\*"
 
xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTranscript\StudentTranscriptMetaEd\MetaEdOutput\exttwo\XSD" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Standard.Extensions.Exttwo\SupportingArtifacts\Schemas\*"
 
xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTranscript\StudentTranscriptMetaEd\MetaEdOutput\exttwo\Interchange" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Standard.Extensions.Exttwo\SupportingArtifacts\Schemas\*"

Step 6. Security Configuration

PostSecondaryOrganization has no relationship to people or education organizations and therefore has no authorization strategy that can be applied to it.  It is in effect a stand alone table and will need an authorization strategy of 'NoFurtherAuthorizationRequired' for API requests to be made against it.  If security is desired, another authorization strategy can be implemented to handle this entity.  

To enable NoFurtherAuthorizationRequired, first create a security SQL script called 0001-PostSecondaryOrganization_No_Further_Auth_Required.sql and place it in the C:\Ed-Fi-ODS-Implementation\Database\Data\EdFiSecurity folder (Create 'EdFiSecurity' folder if it does not exist).  Copy the contents of the following SQL DML script into the newly created file and save.

DECLARE @AuthorizationStrategyId INT
DECLARE @ResourceClaimId INT
 
SELECT @AuthorizationStrategyId = AuthorizationStrategyId
FROM   AuthorizationStrategies
WHERE  AuthorizationStrategyName = 'NoFurtherAuthorizationRequired'
 
SELECT @ResourceClaimId = resourceclaimid
FROM   ResourceClaims
WHERE  ResourceName = 'postSecondaryOrganization'
 
INSERT INTO ResourceClaimAuthorizationMetadatas
SELECT ActionId,
       @AuthorizationStrategyId,
       @ResourceClaimId,
       NULL
FROM   Actions a
WHERE  NOT EXISTS (SELECT 1
                   FROM   ResourceClaimAuthorizationMetadatas
                   WHERE  Action_ActionId = a.ActionId
                          AND AuthorizationStrategy_AuthorizationStrategyId = @AuthorizationStrategyId
                          AND ResourceClaim_ResourceClaimId = @ResourceClaimId)

Step 7. 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: