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.
Customer Getting Started
"Dos and Don'ts" to assist the new Ed-Fi user (Click Here)
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 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-Fi 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. To assist with this process, we have created the Ed-Fi Code Mappings 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 is the first one in your list of configurations. You will then select a Code Set to map. When a Code set is selected for the first time, there will be no existing codes 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 is 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 the codes will appear in the list.
Now you can map the codes to an associated Ed-Fi Type (or descriptor)
Note: Detailed Aeries mappings for Ed-Fi v2 is available for download here
Ed-Fi Test Page
The Ed-Fi Test page is available to help test the Ed-Fi ODS configuration and mappings. To test, select an available configuration, then test by connecting to the ODS and push / pull data from the ODS.
Getting Started
The first step on this page is to click on the 'Get ODS Configurations' button.
All of the active Ed-Fi configurations defined on the Ed-Fi Configurations page will be displayed, 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 school's entity is selected and all schools that are in the ODS are retrieved.
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, 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.
Sync Entity
Next to the 'School' entity label is a button to 'Sync'. Clicking this button will update all the active schools that are associated to this ODS configuration defined in the Ed-Fi Configurations page. Selecting this button, 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. In this example below we see that the school was 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 filter the list of Entity results to see all results, only successes, or only failures.
Note: 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 only successful results
Click on the (2418 Successes) link
Example showing only failed results
Click on the (171 failures) link
