Overview

Ed-Fi Field Mapping by Domain

Security

Terminology

Configure Connections & Schedule

Map Codes

Sync Data

Overview

The Aeries Ed-Fi pages facilitate data extracts for the Texas Student Data System (TSDS) upgrade to the Ed-Fi standard.

The Ed-Fi Data Standard is a nationally adopted common language that allows education technology systems to securely exchange data. The TEA has adopted Ed-Fi as the standard for district reporting of state requirements.

The Texas State Reporting Ed-Fi pages are for the new requirements starting in the 2024-25 School Year. Refer to Texas State Reporting documentation for prior school years using the XML submissions. 

To extract data:

• Configure Aeries to communicate with the TEA Ed-Fi Individual Operational Data Store (IODS) server.
• Set up the time(s) when data will be uploaded to the IODS server on a schedule.
• Map codes.
• Sync data. 

Detailed steps are listed below.

Ed-Fi Field Mapping by Domain:

The following documents provide the specific Aeries table.field where each element is stored, as well as Level 1 Error troubleshooting.

See also: 

• Ed-Fi - Troubleshooting Errors
• Ed-Fi - Frequently Asked Questions

Security ↑

Aeries admin-level security allows full access to the Ed-Fi related pages.

For non-admin users, the following Table Permission must be set:

Terminology ↑

The following terminology has changed:

The following terminology is associated with APIs and may appear in error message generated by the Ed-Fi IODS.

• Array: A set of the same Data Elements with different values, such as a bell schedule.
• Association: Two Entities that are related via one or more shared keys.
• Data Element: A specific piece of information, such as a student's first name.
• Descriptor: A Data Element that has a specific set of codes, such as GradeLevel.
  
• Domain:  A group of related Entities.
• Endpoint: The URI that indicates the path to a specific Data Element.
• Entity: A group of related Data Elements.
• Namespace: The portion of the URI that indicates the governing entity (ed-fi.org) and the Descriptor.
• Natural key: A column that uniquely identifies a record and contains content that is meaningful to the users, such as Student Last Name, as opposed to a key that has less meaningful data such as an ID.
• Payload: The data that is sent in an API request or received in an API response.
• Sync/Synchronization: The process of comparing local Aeries data to data that exists on the Ed-Fi IODS server. When syncing occurs, data that has been added, changed, or deleted in Aeries is updated on the Ed-Fi IODS server.
• Attribute/Property: The Data Elements and their Values for a particular Entity. For example, the attributes for the AssessmentResults entity are Assessment Date, Score Accommodations, etc.
• URI (Uniform Resource Identifier): Similar to a URL but identifies any type of resource, not just one on the internet.
• Value: 
  • String: User-entered value with a specified maximum number of characters
  • Code Set: The list of defined values allowed for a particular Descriptor. If local codes are used they must be mapped to state-defined codes.
  • Date: A value formatted as a date
  • Boolean: Yes/No indicators

Configure Connections & Schedule ↑

Before proceeding, Aeries must be configured correctly to communicate with a running instance of an Ed-Fi iODS server. Multiple simultaneous Ed-Fi IODS connections and configurations can be set up with independent mappings for different Ed-Fi IODS instances if needed.

You will need to create an application in your Data Management Center (DMC). See TSDS Security Management Reference Guide before creating an ODS Configuration in Aeries.  This will give Aeries the permissions to sync the entities based on the claim set chosen and generate the Key and Secret needed to access your IODS.

There are 2 TEA Pre-Defined Claim Sets that may be used for Aeries access and 1 customized claim set that you may import into your DMC:

Navigate to School Info > Imports and Exports > Ed-Fi ODS Configurations

1. Under Configurations, any existing configurations are listed.
2. Click Add to add an Ed-Fi IODS configuration, or click the Edit icon to edit an existing configuration.
   Each year your ODS Configurations will copy during the New Year Rollover process.  Edit the ODS configuration with the new ODS connection information each year.
   
   A window opens allowing you to enter or update the required information for each configuration.
   
   

   ODS Configuration Name	A user-assigned name for the Ed-Fi IODS configuration
   ODS Version	The version of the Ed-Fi IODS.  For Texas State Reporting choose TSDS Ed-Fi 4.x This will only display the Entities needed for Texas State Reporting
   ODS API Url*	The URL/URI of the Ed-Fi IODS API endpoints provided by the TEA.   For 2024-25 it is this for all LEA's: https://odsprod.tea.texas.gov/odsedfiapi2025/data/v3/
   OauthUrl*	The URL/URI of the Ed-Fi IODS OAuth endpoints as provided by the TEA.  For 2024-25 it is this for all LEA's:https://odsprod.tea.texas.gov/odsedfiapi2025
   Client Key*	Client Key to access the Ed-Fi IODS server, as provided from DMC Application
   Client Secret*	Client Secret to access the Ed-Fi IODS server, as provided by the DMC Application.  This Secret will be masked on the page & encrypted in the EFO table.   Note: If you forget the secret, generate a new one from the Ed-Fi IODS.
   District ID	The unique ID of the district
   Out Of District ID	The code used to indicate an unknown out-of-district school. The record must match a school in the district Ed-Fi IODS.
   Read Only	If selected, read-only access to the IODS is allowed. If unselected, data can be written to the IODS server.
   Synchronization	Scheduled If selected, Aeries data is uploaded to the IODS server according to the schedule. If unselected, Aeries data is not uploaded to the IODS server according to the schedule. If unselected, synchronization is not occurring automatically.
   Scheduled	The selected synchronization schedule is displayed.
   Entity Synchronization	Select the entities to be included when uploading data to the IODS. Unselect any entities that should not be included. Once selected for inclusion, use the green/red slider to independently enable/disable data uploads for that entity. Green - (Active) The entity is selected for inclusion, and data changes in Aeries will be uploaded to the Ed-Fi IODS.  Red - (Inactive) The entity is selected for inclusion, but data changes in Aeries will not be uploaded to the Ed-Fi IODS. 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, in order to reduce the time spent on dependency errors and processing time.
   Schools Synchronization	Select the schools to be included when uploading data to the IODS. Unselect any schools that should not be included. Once selected for inclusion, use the green/red slider to independently enable/disable uploading data for that school.  Green - (Active) The school is selected for inclusion, and data changes in Aeries will be uploaded to the Ed-Fi IODS.  Red - (Inactive) The school is selected for inclusion, but data changes in Aeries will not be uploaded to the Ed-Fi IODS.

   
   * ODS Configuration information from the TSDS Data Management Center (DMC)

Schedule

Under Schedule the current schedule is displayed.

The Schedule feature allows the district the option to set a schedule for uploading entities to the IODS on specific days of the week.

1. Click the Edit icon to modify the schedule.
   
   A window opens allowing you to set up the schedule.
   
   
   
   

   Days to Run Scheduled Synchronization	If running scheduled synchronization, select the day(s) of the week to run the process.
   Time	If running scheduled synchronization, enter the time of day at which to run the synchronization process on the selected days.
   Email Address	If running scheduled synchronization, enter the email address where the notifications will be sent.
   Scheduled Synchronization	If running scheduled synchronization, click Enable Schedule Process to upload/synchronize the data according to the set schedule. The messaged "Enabled" is displayed. When enabled, the synchronization process runs automatically according to the selected Days and Time. Click Disable Scheduled Process to stop running the schedule process automatically.
   Run Schedule Process	Click to immediately run the scheduled process if needed.

   
   
   
2. Click Save.
3. To delete a configuration, click the Edit icon, then click Delete. The configuration is deleted.
   
   
   

   NOTE: Aeries Updates will interrupt the sync. Normal updates are scheduled for Tuesdays 10:00-10:30 PM. Ensure the sync will complete by 10:00 PM or start after 10:30 PM
   
   TEA does not recommend syncing between 7-8 PM as this has been a peak time for processing.

   
   

   
   

   
   
   
   

Map Codes ↑

Most TEA Ed-Fi codes are hard-coded in Aeries and do not need to be mapped. Any local codes used by the district must be mapped to TEA Ed-Fi codes.

Code sets that allow local codes are indicated with an asterisk in the Ed-Fi Field Mapping Page in the Label & Aeries Table.Field column.

Local Codes

Navigate to School Info > Configurations > Update Code Table

• Add any local codes that will be mapped to Ed-Fi Descriptors, including any necessary language translations.

Ed-Fi Codes

Navigate to School Info > Imports and Exports > Ed-Fi Code Mappings

1. Ed-Fi Configuration - Select a configuration from those set up on the Ed-Fi ODS Configurations and Schedule page under Configurations.
   
   
2. Code Set - Select the local code set to map, which is identified by the Ed-Fi descriptor name and the Aeries table.field. Initially each code set will have no existing codes.
   
   NOTE: Because Ed-Fi descriptors can exist in multiple namespaces, both the descriptor and namespace are displayed in the Code Set dropdown.
   
   
3. Click Add Local Codes to retrieve any custom mappings previously entered on the Update Code Tables page.
   
   
4. Map each local codes to the corresponding Ed-Fi Type or Descriptor.
   
   
5. To add a new code, it will first need to be added on Update Code Tables. Then return to Ed-Fi Code Mappings and click Add Local Codes. The new code will appear in the list.
   
   You can click Update Local Codes link to open the Update Code Tables page.
   
6. To remove a mapping, click the Delete icon.
   
   
7. Repeat for each Code Set.

Sync Data ↑

Navigate to School Info > Imports and Exports > Ed-Fi System Init and Testing

The Ed-Fi Test Initialization and Testing page allows the district to upload data from Aeries to the connected Ed-Fi IODS instance.

Aeries local codes must already be mapped to Ed-Fi descriptors, as described above, before proceeding.

1. Click Get ODS Configurations.
   
   All active Ed-Fi configurations and selected schools defined on the Ed-Fi ODS Configurations and Schedule page are listed. Inactive schools are listed as "disabled."
   
   
2. Click the configuration name or school.
   Set the following as needed:
   
   

   Descriptors	(Optional) The descriptors stored in the Ed-Fi IODS server are listed. Select a descriptor to view its details. The details are displayed in the lower-half of the page. The information is for informational purposes only. Descriptors are updated in a separate process.
   Jobs	Any previously run jobs are listed. Select to view the status or results of prior jobs.
   Entities	The active entities selected for this IODS configuration are listed. Select the entity to sync, then click Sync Entity. Or, you can click Sync All Entities to do a full sync.
   Full Sync	Click Sync All Entities to update all active schools selected for this IODS configuration as defined on the Ed-Fi Configurations page. A job runs in the background that syncs all selected entities for all selected schools. Depending upon the type and amount of data to be uploaded to the IODS, this can take anywhere from a few seconds to a few hours. Running separate asynchronous jobs is recommended.
   Clear Cache	Click Mappings to ensure the latest mapping changes are refreshed. Click Configurations to ensure the latest configuration changes are used.

   
   
   

3. Once the job is completed, results are displayed in the lower-half of the page.
   • Counts are provided for total results, successful results, and failed results.
     
     NOTE: For a full sync, only summary results are listed for each entity. To see details for a particular entity, it must be synced individually.
     
     
   • To filter results, click N total results, N successes, or N failed to view a specific results list.
     
     IMPORTANT: When filtering, the results are limited to the Max Results value. To see all results, successes, or failures, increase the Max Results value.
     
     
   • Any failed records with Level 1 errors may be viewed by selecting the Export Failed Records To Excel button.
     Select Download or View Report and the failed records will download to your C:/Downloads folder.
     
     
     
     These errors are stored in the EdfiTransationErrors table, which is a log of all errors for each entity generated each time the entity is synced. See also Ed-Fi - Troubleshooting Errors. You may also query this table directly.
     
     Query the error table:
     
     To see Level 1 errors for a specific entity, run this query:
     
     

     LIST  EdFiTransactionErrors IF ENM = 'Entity' AND DTS >= "MM/DD/YYYY"

     
     where:
     • 'Entity' is the entity where the errors occurred, such as PROGRAMS or PARENT.
     • MM/DD/YYYY is the date you last synced that entity.
       IMPORTANT: Because the DTS field includes both date and time, be sure to use the >= operator and
       always include the Date Timestamp criteria or you may get duplicate errors if that same error has occurred from multiple syncs without being resolved.
     • The JSON generated from Aeries is included in the RQJ field to aid in troubleshooting errors.
       
       
   • When you sync a single entity, records are marked for deletion, but they are not actually deleted from the IODS server.
   • When you do a full sync, the records marked for deletion are actually deleted from the IODS server. This check ensures that records with data dependencies are deleted in the correct order.
      
4. To adjust a configuration, click Ed-Fi Configurations to open the Ed-Fi ODS Configurations and Schedule page.
   
    
5. To view or update mapping of local codes to Ed-Fi descriptors, click Ed-Fi Code Mappings to open the Ed-Fi Code Mappings page.