Student ID to Identification Code Translation allows clients to interact with the Ed-Fi-ODS / API using their chosen student identifier. Internally, the Ed-Fi-ODS / API uses StudentUSI, an integer-based surrogate identifier, to represent each person entity. This value is then translated to the StudentUniqueId seen in API requests and responses.
The Student ID to Identification Code Translation feature of the ODS / API allows users to configure this translation process by associating an API client with a specific student identification system. As a result, clients will see their chosen student identifier in place of StudentUniqueId.
This article provides an overview and technical information for users and developers to use and configure the Student ID to Identification Code Translation behavior.
For more information on the motivation and design behind this feature, see the article Student ID to Identification Code Translation (Ed-Fi ODS / API).
A few key points:
- Once configured, an API client will see the identification codes from the configured student identification system in place of StudentUniqueIds .
- Missing identification codes or ambiguous identification code matches may result in error response or masked StudentUniqueId of "??????". See here for details.
- An API client configured with student identification system will have some limitations on Student resource creation and update. See here for details.
Configure the API Client
Get Available Student Identification Systems
The student identification system is defined by the StudentIdentificationSystemDescriptor.
Use the following query to find the list of available StudentIdentificationSystemDescriptor URIs:
Update the API Client With a Student Identification System
Cloud ODS / API Admin App or Ed-Fi ODS / API Admin App could be used to configure API client to use student identification system. Alternatively API client can be configured to use your selected student identification system by modifying the ApiClients.StudentIdentificationSystemDescriptor column of the Admin Database.
In this example, we will update ALL clients to use the http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local Descriptor:
API clients associated with a student identification system may only be associated with ONE education organization. API clients associated with multiple education organization are NOT supported by this feature and will most likely lead to API errors.
Run the following query to check for any API clients that violate this requirement:
Any results are API clients that will require modification to be associated with a single education organization.
Before configuring an API client with the StudentIdentificationSystemDescriptor, an API call to the
/students endpoint would give you the existing StudentUniqueId as shown:
After configuration, the StudentUniqueId will be translated into the IdentificationCode associated with http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local.
API Responses and Error Handling
Due to the current state of Identification code collection and storage in ODS, the student identification code to StudentUniqueId translation may encounter No match or multiple match scenarios. These scenarios will be handled as described bellow:
PUT/POST (Resources other than Student Resource)
- No match (Status code: 400 - e.g. error message "Validation of 'StudentAssessment' failed.\n\tStudent reference could not be resolved.")
- Multiple match (Status code: 400 - e.g. error message "The uniqueId value provided (using the student identification system of 'http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local') matched to multiple students.")
- PUT/POST with masked value of "??????" (Status code: 409 - e.g. error message "The value supplied for the related 'student' resource does not exist.")
Get By Key and Get by Example with specified StudentUniqueId
- No match GetByKey results in Status code 404, Get by Example returns all results as though the studentUniqueId filter was not provided
- Multiple match (Status code: 400 - error message e.g. ("The uniqueId value provided (using the student identification system of 'http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local') matched to multiple students.")
Get All, Get by Example without specified studentUniqueId, Get by Id
- No match ( Status code: 200 - returns results where studentUniqueId is masked with ‘??????')
- Multiple match ( Status code: 200 - returns results where studentUniqueId is masked with ‘??????')
The support for transparent transformations of the StudentUniqueId values in references for affected API clients, creates a technical challenge for supporting those clients with updates to the Student resource (where the raw StudentUniqueId value is stored). PUT and POST scenarios for Student resource is handled as described bellow:
PUT/POST (Student Resource)
- New students cannot be created with POST/PUT and will result in an error when the API client is associated with any student identification system.
- Existing students cannot be updated via POST when configured with any student identification system.
- Existing students can be updated via PUT using the resource id.
- No labels