Date: Fri, 29 Mar 2024 06:19:07 -0500 (CDT) Message-ID: <1870040290.30332.1711711147956@PUBEDFIPRDWEB5.public.local> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_30331_90132865.1711711147950" ------=_Part_30331_90132865.1711711147950 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
In this example, we will create a new domain entity called Student Trans= portation. This entity will be exposed in Ed-Fi ODS / API through a new API= resource called studentTransportations.
Before you begin:
The steps can be summarized as:
Each step is outlined in detail, below.
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 ent= ity and a Student entity), but there is no means to store student bus assig= nments, 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 mo= del.
The following is a diagram is a sketch showing the new Student Transport=
ation entity (on the left), along with its properties. Our new entity relat=
es to School and Student, entities which are already present in the ODS / A=
PI data model. These existing entities are shown in gray (on the right).
In this step, we'll create a new project in MetaEd, and author our new e= ntity. It's easy =E2=80=94 but you do need to download and install MetaEd&n= bsp;to do this step. Do that now if you haven't already.
MetaEd allows you to target different versions of the Ed-Fi technology s= tack and data model. Confirm that your MetaEd IDE is targeting v5.1 by foll= owing the instructions in the Version Ta= rgeting documentation for the MetaEd IDE.
The desired model for the latest ODS / API is "ed-fi-model-= 3.2c".
In the MetaEd menu, click Create New Extension = Project.
Navigate to the desired location for the extension project and c=
lick New folder.
Create a folder for the extension project, sele= ct the new folder, and click Select Folde= r.
The new extension project appears in the tree view below the core model.=
Open the package.json file by double-clicking on the file in the tree vi= ew to the left and provide an appropriate name for your project. In this ca= se we will call it "SampleStudentTransportation".
Click File > Save (Ctr= l + S) to save your changes.
We're going to add a Domain Entity source file to the project we just cr= eated.Note that MetaEd files are required to be organized into subfolders. = Folders are generally named after their entity type. The core ed-fi-mo= del project provides examples of subfolder naming.
Right-click on the extension project folder and cl= ick New Folder.
Name the folder DomainEntity and press <= strong>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 contai= ns source code basics.
Right-click on the new folder, choose Add MetaE= d File > DomainEntity. This creates the source= file including the template language.
Note the new file appears in the tree view to the left. Double-c= lick on the file in the tree view to open it. The opened file prov= ides a short sample of the appropriate syntax for a Domain Entity.
Right-click on the newly created MetaEd file in th= e tree view to the left and click Rename.
Name the file StudentTransportation to match the name o= f the new entity to be created. Press Enter.
We'll replace the template text with the details about the resource we'r= e trying to create. Note that the blue dot on the tab for the open file ind= icates 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= :
=20 Domain Entity StudentTransportation documentation "StudentTransportation" domain entity EdFi.School documentation "The school to and from which the student is being transp= orted." is part of identity domain entity EdFi.Student documentation "The student being transported." is part of identity string AMBusNumber documentation "The bus that delivers the student to the school in the m= orning." 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
If you want to bulk load this extension, you need to create an interchan=
ge file. Right-click on the extension project fo=
lder and click New Folder, and name it
Right-click on the new Interchange folder, select&= nbsp;Add MetaEd File > Interchange. Name your file StudentTransportation.metaed. Replace the template text in your new In= terchange source file with the following code:
Interchange StudentTransportation documentation "StudentTransportation" extended documentation "StudentTransportation" use case documentation "StudentTransportation" domain entity StudentTransportation
Click File > Save (
In this step, we'll build our new MetaEd project. This is fairly straigh= tforward.
Click Build in the MetaEd menu to gene= rate artifacts.
Artifacts build successfully.
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 u= pdated documentation such as data dictionaries that add your extension defi= nitions to the ODS / API documentation.
We'll look at how to use this MetaEd output in your code below. First, w= e'll need to set up our extension project in Visual Studio.
This step will create the C# Extension files necessary to build your ext= ended solution. This step assumes you've successfully downloaded and c= an run the ODS / API in a local development environment per the instruction= s in the Getting Sta= rted documentation. Do that now if you haven't already.
Visual Studio Project Templates can be installed by following steps= in Getting Started - Project Templates Installation = section of this documentation.
4b.1. To add a project to your Ed-Fi-Ods Visual Studio = Solution, right-click on the Ed-Fi Extensions Fo= lder. Select Add > New Project= strong>.
4b.2. Search and select the Ed-Fi API= Extensions Project Template option and click Ne= xt.
In the Project Name field enter EdFi.Ods.Extensions.SampleS= tudentTransportation and click Create.
Note
To ensure MetaEd outputs are correctly deployed to ODS / API extension p= roject, the last section of the project name should match the namespace you= provided in Step 2.c.
4c.1. Right-click on the = Marker_EdFi_Ods_Extensions_ExtensionName.cs file in newly cre= ated EdFi.Ods.Extensions.SampleStudentTransportation <= /strong>project and Rename the file to Marker_EdFi_Ods_Ext= ensions_SampleStudentTransportation.cs.
4c.2. When prompted choose to rename all reference= s to the code element Marker_EdFi_Ods_Extensions_ExtensionName.
In this step, we'll integrate the extension into the solution.
4d.1. Locate the EdFi.Ods.WebApi&= nbsp;project, within the "Entry Points" folder. Right-click, select Add > Projec= t Reference..., then s= elect the EdFi.Ods.Extensions.SampleStudentTransportat= ion project.
4d.2. Locate any profile projects in the solution. =
;Right-click, select Add &=
gt; Project Reference...,
In this step, we'll use the MetaEd "Deploy" feature and integrate the fi= les 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 p= roject. These include the generated SQL, generated XSD, and other material.=
You can easily configure the MetaEd IDE to copy the generated files to t= he correct locations for the ODS / API project.
Ensure that your Ed-Fi ODS / API source directory is set properly in the=
MetaEd IDE settings. Under the "MetaEd" menu, select "
As noted above, deployment will remove existing SQL scripts =E2=80=94 in= cluding modifications to establish the authorization strategy as described = in the next step. Verify that you have a source control copy or file backup= of previous work before running deployment.
Deploy by selecting MetaEd > Deploy= from the menu bar. Click OK in the confirmation dialog.= p>
This will run a new build of all artifacts, and the artifacts required f= or your Extended ODS / API project will be copied over to the correct locat= ions. For instructions on how to perform the steps manually, see Appendix A, below.
The Ed-Fi ODS / API is secure by default. One implication of this design= principle is that new entities and elements may not be accessed until an a= uthorization strategy is applied. This prevents accidental release of confi= dential information, but does require active steps on the part of system de= velopers to enable access to Extensions.
Create a security SQL script called 0001-StudentTransportation_R= esourceClaims.sql and place it in the Ed-Fi= -ODS-Implementation/Application/ EdFi.Ods.Extensions.SampleStudentTransport= ation/Artifacts/MsSql/Data/Security folder (Create 'Security' f= older if it does not exist). Copy the contents of the following SQL DML scr= ipt into the newly created file and save.
DECLARE @ApplicationId INT SELECT @ApplicationId =3D ApplicationId FROM [dbo].[Applications] WHERE ApplicationName =3D 'Ed-Fi ODS API' =20 DECLARE @ParentResourceClaimId INT SELECT @ParentResourceClaimId =3D ResourceClaimId FROM [dbo].[ResourceClaims] WHERE ResourceName =3D 'relationshipBasedData' INSERT INTO [dbo].[ResourceClaims] ( [DisplayName] ,[ResourceName] ,[ClaimName] =20 ,[ParentResourceClaimId] ,[Application_ApplicationId] ) VALUES ('studentTransportation' ,'studentTransportation' ,'http://ed-fi.org/ods/identity/claims/sample-student-transportatio= n/studentTransportation' ,@ParentResourceClaimId ,@ApplicationId )
With MetaEd 2.0, it is po= ssible to create extension resources that use the same name as an Ed-Fi sta= ndard resource. The authorization metadata supports this through a change i= n behavior so it no longer uses just the resource name to identify the reso= urce, but instead uses the ClaimName. To prevent possible naming conflicts,= the claim name's URI value should include the schema representation, using= the following format:
http://ed-fi.org/ods/identity/claims/{schema}/{resourceName}
The URI representation of the schema name should be derived by splitting= the terms in the name of the extension, inserting hyphens and converting t= o lower case. For example, "SampleStudentTransportation" would be separated= into "Sample", "Student" and "Transportation" and then combined with hyphe= ns and converted to lower case as "sample-student-transportation".
The resource name should be the camel-cased (also known as "medial capit= als"), singularized name of the resource (e.g., "studentTransportation" not= "StudentTransportation" or "studentTransportations").
Note that in 0001-StudentTransportation_ResourceClaims.sql<= /strong> script above, the resulting ClaimName value is "http://ed-fi.= org/ods/identity/claims/sample-student-transportation/studentTransportation= ".
Save all modified files, close Ed-Fi-ODS.sln, and re-run the code genera=
tion steps outlined in the Getting Started Guide (i.e., from a Po=
werShell prompt run Initialize-PowershellForDevelopment.ps
script, followed by the initdev
command). The=
n, run the application and view the Ed-Fi ODS / API in the Swagger UI.=
The following new API resource should be visible:
Congratulations, you've successfully extended an instance of the Ed-Fi O= DS / 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 gett= ing the development work into production.
Visual Studio Project Templates can be installed by following steps= in Getting Started - Project Templates Installation = section of this documentation.
2.1. To add a project to your Ed-Fi-Ods Visu= al Studio Solution, right-click on = the Ed-Fi Extensions Folder. Select Add&= nbsp;> New Project.
2.2. Search and select the Ed-Fi =
;API Extensions Project Template option and click
In the Project Name field, enter EdFi.Ods.Extensions.Sample= StudentTransportation and click Create.=
3.1. Right-click on th= e Marker_EdFi_Ods_Extensions_ExtensionName.cs fi= le in newly created EdFi.Ods.Extensions.Sample= StudentTransportation project and Rename th= e file to Marker_EdFi_Ods_Extensions_SampleStu= dentTransportation.cs.
3.2. When prompte= d choose to rename all references to the code element Marker_EdFi_Ods_Extensions_SampleStudentTransportation.
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-clic= k, select Add > Project= Reference..., then se= lect the EdFi.Ods.Extensions.SampleStu= dentTransportation project.
4.2. Locate any profile projects in the solution. = Right-click, select Add &g= t; Project Reference..., then select the&nb= sp;EdFi.Ods.Extensions.SampleStudentTransportation pr= oject. This step is needed only if any of the Profile resources in the= Profiles.xml document are extended, or extension entities are being constr= ained by a particular Profile.
The code listings in this section use the sample extension material from= Ed-Fi-ODS/Samples/Extensions/StudentTransportation.
5.1. Map Artifacts
xcopy= /y "Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTransportati= onMetaEd\MetaEdOutput\samplestudenttransportation\Database\SQLServer\ODS\St= ructure" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Extensions.SampleSt= udentTransportation\Artifacts\MsSql\Structure\Ods\*" =20 xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTranspo= rtationMetaEd\MetaEdOutput\samplestudenttransportation\Database\PostgreSQL\= ODS\Structure" "Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Extensions.Sa= mpleStudentTransportation\Artifacts\PgSql\Structure\Ods\*" xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTranspo= rtationMetaEd\MetaEdOutput\samplestudenttransportation\ApiMetadata" "Ed-Fi-= ODS-Implementation\Application\EdFi.Ods.Extensions.SampleStudentTransportat= ion\Artifacts\Metadata\*" =20 xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTranspo= rtationMetaEd\MetaEdOutput\samplestudenttransportation\XSD" "Ed-Fi-ODS-Impl= ementation\Application\EdFi.Ods.Extensions.SampleStudentTransportation\Arti= facts\Schemas\*" =20 xcopy /y "Ed-Fi-ODS\Samples\Extensions\StudentTransportation\StudentTranspo= rtationMetaEd\MetaEdOutput\samplestudenttransportation\Interchange" "Ed-Fi-= ODS-Implementation\Application\EdFi.Ods.Extensions.SampleStudentTransportat= ion\Artifacts\Schemas\*"
The Ed-Fi ODS / API is secure by default. One implication of this design= principle is that new entities and elements may not be accessed until an a= uthorization strategy is applied. This prevents accidental release of confi= dential information, but does require active steps on the part of system de= velopers to enable access to Extensions.
Create a security SQL script called 0001-StudentTransportat= ion_ResourceClaims.sql and place it in the Ed-Fi-ODS-Imp= lementation/Application/ EdFi.Ods.Extensions.SampleStudentTran= sportation/Artifacts/MsSql/Data/Security folder (Create 'Securi= ty' folder if it does not exist). Copy the contents of the following SQL DM= L script into the newly created file and save.
DECLARE @ApplicationId INT SELECT @ApplicationId =3D ApplicationId FROM [dbo].[Applications] WHERE ApplicationName =3D 'Ed-Fi ODS API' =20 DECLARE @ParentResourceClaimId INT SELECT @ParentResourceClaimId =3D ResourceClaimId FROM [dbo].[ResourceClaims] WHERE ResourceName =3D 'relationshipBasedData' INSERT INTO [dbo].[ResourceClaims] ( [DisplayName] ,[ResourceName] ,[ClaimName] =20 ,[ParentResourceClaimId] ,[Application_ApplicationId] ) VALUES ('studentTransportation' ,'studentTransportation' ,'http://ed-fi.org/ods/identity/claims/sample-student-transportatio= n/studentTransportation' ,@ParentResourceClaimId ,@ApplicationId )
Save all modified files, close Ed-Fi-ODS.sln, and re-run the code genera=
tion steps outlined in the Getting Started Guide (i.e., from a Po=
werShell prompt run Initialize-PowershellForDevelopment.ps
script, followed by the initdev
command). The=
n, run the application and view the Ed-Fi ODS / API in the Swagger UI.=
The following new API resource should be visible:
The following GitHub links contain source files for this extensibility s= ample.