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 (real time or scheduled).
  • 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


Security ↑

Aeries admin level security is required to access the Ed-Fi related pages.


Terminology ↑


The following terminology has changed:


Former Term Ed-Fi Term
Interchange >Domain
Complex Type >Entity
Data Element >Data Element
Code Table >Descriptor Table


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. 


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




  • Under Configurations, any existing configurations are listed. 
  • Click Add to add an Ed-Fi IODS configuration, or click the Edit icon to edit an existing configuration.

    A window opens allowing you to enter or update the required information for each configuration.


    ODS Configuration NameA 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, as provided by the TEA
    Format example: http://10.0.54.131:10030/data/v3
    OauthUrl
    		The URL/URI of the Ed-Fi IODS OAuth endpoints, as provided by the TEA
    This is the same as the ODS API URL, but without the information after the /'s at the end
    Format example: http://10.0.54.131:10030
    Client Key
    		Client Key to access the Ed-Fi IODS server, as provided by the TEA  
    Client Secret
    		Client Secret to access the Ed-Fi IODS server, as provided by the TEA.  This Secret will be masked on the page & encrypted in the EFO table.  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.
    • Real Time
      • If selected, Aeries data is uploaded to the IODS server in real time (continuously every 10 minutes)
      • If unselected, Aeries data is not uploaded to the IODS server in real time.

    If both are unselected, synchronization is not occurring.

    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.


  • 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, or real-time synchronization where data that has changed is continuously updated every 10 minutes.
    1. Click the Edit icon to modify the schedule.

      A window opens allowing you to set up the schedule or enable real-time synchronization.



      Days to Run Scheduled SynchronizationIf running scheduled synchronization, select the day(s) of the week to run the process.
      TimeIf running scheduled synchronization, enter the time of day at which to run the synchronization process on the selected days.
      Email AddressIf running scheduled synchronization, enter the email address where the notifications will be sent.
      Scheduled SynchronizationIf 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 ProcessClick to immediately run the scheduled process if needed.
      Real Time SynchronizationIf running real-time synchronization, click Run Real Time Process to begin the automatic upload/synchronization of data continuously at 10 minute intervals.
      The messaged "Enabled" is displayed when the real time synchronization process is running.

      Click Disable Real Time Process to stop running the real time process.


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


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 SyncClick 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 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.

      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.


    • 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.