This section outlines the steps necessary to integrate and activate the Composite definitions for use in an Ed-Fi ODS / API. It is assumed that the Ed-Fi ODS / API has been successfully downloaded and is running in a local environment per the instructions in the Tech Preview Installation Guide documentation.  

The steps can be summarized as:

Each step is outlined in detail, below. 

Step 1. Create the Composites Project

1. To add a project to your Ed-Fi-Ods Visual Studio Solution, right-click on the "Composites" folder. Select Add > New Project.
2. In the "Add New Project" dialog, find the "Class Library" entry.
3. Enter the project name for the new project and click OK. The suggested naming convention for this type of project is something like EdFi.Ods.Api.Composites.MyComposites.
   

4. Create a "marker" interface file in the root of your Composites project named Marker_EdFi_Ods_Api_Composites_MyComposites.cs  (named to match your assembly). Alternately, you can modify the "Class1.cs" file created in Step 1.3, above. This interface is an idiom used in the Ed-Fi Visual Studio Solution to enable a strongly typed mechanism for obtaining a reference to the .NET assembly. The marker interface file should contain the following code:

   Code Block
   language c#
   namespace EdFi.Ods.Api.Composites.MyComposites { public interface Marker_EdFi_Ods_Api_Composites_MyComposites { } }

   
   

5. Add an XML file named Composites.xml to the root of the project, then add the appropriate composite definition. It should look something like the following:

   Code Block
   language xml
   <?xml version="1.0" encoding="utf-8"?> <CompositeMetadata organizationCode="ed-fi"> <Category displayName="My Sample Composites" name="MyComposite"> <Routes> <Route relativeRouteTemplate="/sections/{Section.Id}/{compositeName}" /> </Routes> <Composites> <Composite name="Student"> <Specification> <Parameter name="Section.Id" filterPath="StudentSectionAssociation->Section.Id" /> </Specification> <BaseResource name="Student"> <Property name="StudentUniqueId" /> <Property name="FirstName" /> <Property name="LastSurname" /> <Property name="BirthDate" /> </BaseResource> </Composite> </Composites> </Category> </CompositeMetadata>

   *Notice 

   The CompositeMetadata attribute 'organizationCode' is a required attribute and indicates the 'Organization' the composite belongs to.   This value is carried from the xml definition all the way into the API route definitions.  The organizationCode in combination with the Category name are used to identify the composite being requested from the API.  

6. In the Composites.xml Properties, change the "Build Action" setting to "Embedded Resource".
    

7. Edit the project properties and ensure that the target framework is set to .NET Framework 4.6.
   
   
   

8. Add the build task section to .csproj file.
   Right click on the created project and choose Unload Project.Edit the project file by right clicking on the project then choose Edit option.

   The .csproj will be opened on the editor now. Add the following build task section text and save.

   Code Block
   <UsingTask TaskName="EdFi.Ods.CodeGen.BuildTasks.CompositeValidationTask" AssemblyFile=".\..\..\..\Ed-Fi-ODS\Application\libs.codegen\EdFi.Ods.CodeGen.dll" /> <Target Name="AfterBuild"> <Copy SourceFiles="@(myLibraries)" DestinationFolder="$(ttLibsFolder)" SkipUnchangedFiles="true" /> <CompositeValidationTask CompositeDefinitionPath="$(ProjectDir)Composites.xml"/> </Target>

   After saving it, right click on the project and reload it.

9. Save the Project.

Step 2. Integrate Composites into the Solution

To integrate the Composite Resources into the solution, perform the following tasks in the EdFi.Ods.WebApi project (located in the "Entry Points" folder):

1. Add a reference to the new Composites project you constructed in the previous step.
2. Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file and add the following code in the following steps.

   1.  Add a line to include MyComposites assembly:

      Code Block
      language c# title EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
      using EdFi.Ods.Api.Composites.MyComposites;

      
      

   2. 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. The line should read something like the following:

      Code Block
      language c# title EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs
      AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Api_Composites_MyComposites>();

      
      

Step 3. Rebuild the Solution and Verify Changes 

Save all modified files and rebuild the Ed-Fi-ODS solution. Then, run the application and view the Ed-Fi ODS / API using the Swagger UI. The following new API Composite resource should be available.

a.  The 'organizationCode' (ed-fi) mentioned in Section 1 step 5 can be seen in the Composite urls above.  To successfully retrieve a composite this value (defined in the xml definition) must be present as the first segment of a composite url.