This document provides a basic getting started outline to setting up AeriesWeb to communicate with an Ed-Fi ODS Server instance using the version 2.6 Ed-Fi data standard.

Scope

This document assumes a basic understanding of Ed-Fi. The document's focus is on how to connect to an Ed-Fi ODS instance using the Ed-Fi Configurations form, map values to Ed-Fi descriptors, and test the uploading of data to an Ed-Fi ODS server.


Ed-Fi specific information can be found at www.ef-fi.org. 


Prerequisites

The District will need access to a running instance of an Ed-Fi v2 ODS server. The following information is needed to establish a connection to the Ed-Fi ODS instance. 

  • ODS Version 
  • ODS API Url
  • Oauth Url
  • Client Key
  • Client Secret
  • District ID

Note:  Aeries Admin level security is required to access the Ed-Fi related forms in Aeries.


Process

The District will first need to add the required connection information provided by their Ed-Fi ODS services provider to the Ed-Fi Configuration form in Aeries. The Ed-Fi Test page can then be used to test connectivity to the Ed-Fi ODS and upload data from AeriesWeb to the connected Ed-Fi ODS instance. 


Before meaningful data can be uploaded to an Ed-Fi ODS, the District will also need to map/translate their Aeries codes to available Ed-Fi codes using the Ed-Fi Mappings form in Aeries. Ed-Fi mappings/translations are stored in the XRF table. 


Ed-Fi Configuration


Aeries supports the use of multiple simultaneous Ed-F ODS connections and configurations. This feature allows the District to setup simultaneous yet independent mappings and configurations to different Ed-Fi ODS instances if desired. These configurations are created using the Ed-Fi Configurations form. The connection configurations are stored in Aeries' EFO table.



Add a Connection

To add a new Ed-Fi configuration, select the Add button in the blue bar on the Ed-Fi ODS Configuration form. 


The following form will display where the configuration information can be added and the schools to be sync'd with the ODS instance can be defined. Also, specifically what data is to be shared/uploaded to the ODS is set using the configuration's form.  



  • Read Only - Turn on/off the ability to write to the ODS
  • Synchronization - Turn on/off scheduled or Real-time* uploads to the ODS


* Real-Time Synchronization - (Aeries Data that has changed within the last 15 mins)


Entities

Once an Entity has been selected for inclusion in the upload process, updating of the Entity's uploaded data can be disable/enabled independently using the green/red slider to the left of the entity's check box. Green indicates active while a red slider would indicate the Entity is selected for inclusion in the process but related data changes in AeriesWeb will not be uploaded to the Ed-Fi ODS.


Note: For the initial upload of data, it is recommended that only a few entities be enabled starting from the top of the list of entities. Following adopting the practice will greatly reduce the amount time spent on dependance errors. Best practice would be to eliminate as many errors in the data as possible beginning from the top of entities list to also reduce required processing time.


When you have finished configuring the ODS connection,  select the Save button at the bottom center of the form


Ed-Fi Schedule

You can choose the times when the daily schedule will run by closing the Configurations bar and the selecting the Schedule bar.


Selecting the Edit icon to make changes to the schedule will reveal the following form.

 


  • The Scheduled  Sync process can be toggled between enabled and disabled by clicking the Enable/Disable Scheduled Process button.
  • The RealTime Sync process can be toggled between enabled and disabled by clicking the Enable/Disable RealTime Process button.
  • The Scheduled Process can be run immediately by clicking the Run Scheduled Process button.

When finished making your selections click the Save button to save your changes and close the window.


Ed-Fi Code Mappings Page


Data in the Aeries database consists of raw data and codes. The code values will need to be mapped to Ed-Fi descriptors or Ed-Fi types before they can be uploaded to the ODS.

For this we have created the Ed-Fi Code Mappings page.

A link to it can be found at the top of the Ed-Fi Test page.

Getting Started

The first thing to do when you open the Ed-Fi Code Mappings page is to select an Ed-Fi Configuration. It may already be selected if it's the firs one in your list of configurations.

Then you need to select a Code Set to map.

When you select a Code set for the first time there will be no code mappings to map. As shown below.

Adding Default Codes

Click the 'Add Default Mappings' to see if any default mappings exist. If any are found, they will be listed.


Adding Aeries Codes

When you select a Code set for the first time there will be no code mappings to map. As shown above.

Click the 'Add Default Mappings' to see if any default mappings exist. If any are found, they will be listed.

Then click the 'Add Local Codes' button to bring in any custom mappings that may exist from the 'Update Local Codes' page. If none are found, you probably need to add some on that page.

Code Mapping

Mapping the Aeries codes to the Ed-Fi descriptors and types.



Note: Ed-Fi descriptors can exist in multiple namespaces. So, we always store the Ed-Fi descriptors and their namespace together (as shown below).




When you are done with your mappings click the 'Save' button at the bottom of the page and your changes will be saved.

Remove Mapping

You can click the delete icon  to remove Aeries code mappings.

Add Mapping

If you wish to add a new Aeries code for mapping, you must first go to the Update Local Codes page
(a link to it available in the upper right corner of the Ed-Fi Code Mapping page)





Then come back to the Ed-Fi Mappings page and click the 'Add Local Codes' button and they will appear in the list.

Now you can map them to an associated Ed-Fi Type (or descriptor)


Ed-Fi Test Page


The Ed-Fi Test page is available to help test the Ed-Fi ODS configuration and mappings, to make sure you can connect to the ODS and push and pull data from the ODS.

Getting Started

The first thing to do when landing on this page is to click on the 'Get ODS Configurations' button.



You it will get all of the active Ed-Fi configurations defined on the Ed-Fi Configurations page, as well as a list of all the schools that are associated with each configuration, and their active/inactive status.

By default, once you select an ODS configuration, the schools entity is selected and all schools that are in the ODS are retrieved. The enabled/disabled flag is added that matches the ODS configuration settings.

Note: this is not the enabled/disabled status of the school in the ODS. Just the local configuration status.



School Entity Details

To see details about a specific school that is stored in the ODS you simple select it from the list.

When you click on it a details panel will appear below the schools list in the right panel, providing you with every property that comes back from the ODS.

In the left panel is the primary table in the Aeries database where most, if not all, of the Aeries data comes from. It's provided to help your understanding of the fields in the associated Aeries table that are mapped to the Ed-Fi entity properties.

NOTE: the data, if any is present in the left panel, may not match the properties in the right panel. It is more to show you the fields and data samples. It's not intended to be a 1 to 1 match. It's only to show the fields available in Aeries for mapping.



If you click the 'Update' button it will send the school information up to the ODS and return the status result, along with a refresh of the school details.



Update Entity

Next to the 'School' entity label is a button to 'Update ODS'. Clicking this button will update all the active schools that are associated to this ODS configuration defined in the Ed-Fi Configurations page.

It will start a job that will run in the background. Depending upon the type and amount of data to be pushed up to the ODS this can take anywhere from a few seconds to a few hours or more. That's why we run them in separate asynchronous jobs.



Recent Jobs

You can check the status of the job, or any recent job, by selecting it from the Jobs dropdown list.



Once the job completes the results will appear in the list below. That is if you were watching the status to completion. Or you might select another job from the dropdown list to see it's status or results.

In this example below we see that the 2 active schools were uploaded to the ODS successfully. There were no failures.



The refresh button is to refresh the list of jobs.  Each displays the current status and percent complete of the 1000 most recent jobs.

Ed-Fi Entities 

We've demonstrated the basic Ed-Fi Test page functionality for the School Entity above to view the list of schools, update the schools in the ODS, and drill down into the details of a single school.

The UI works the same for all entities. Simply select the entity from the Entity dropdown list then follow the same steps above.



Ed-Fi Descriptors and Types

Many Aeries codes will need to be mapped to Ed-Fi descriptors or types. The mapping will be performed using the Ed-Fi Code mappings page. A link to it can be found at the top of the Ed-Fi Test page.

For convenience, all the Ed-Fi descriptors, and many of the Ed-Fi Types, that are stored in the ODS can be viewed by selecting them from the dropdown lists. Descriptors are not uploaded to the ODS using the Ed-Fi Test page. There is a separate process and tool for that.



Results List Filters

You can now filter the list of Entity results to see all results, only successes, or only failures.

Not: only the contents of the current list, which is limited by the Max Results value, are filtered.

If you want to see all results, successes, or failures then you must first increase the Max Results value to a number greater than the total number of results.

Example showing all results (both successes and failures together)

Click on the 2589 total results link




Example showing only successful results

Click on the (2418 Successes) link




Example showing only failed results

Click on the (171 failures) link