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

Overview

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.

Setup

This guide assumes that the Ed-Fi ODS / API has been successfully /wiki/spaces/ODSAPI25/pages/23053035 or /wiki/spaces/ODSAPI25/pages/23052966 and the user has database access.

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:

SELECT (Namespace + '/' + CodeValue) as StudentIdentificationSystemDescriptorUri
FROM [edfi].[Descriptor] d
JOIN [edfi].[StudentIdentificationSystemDescriptor] sisd
	ON [d].[DescriptorId] = [sisd].[StudentIdentificationSystemDescriptorId]

For example:

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:

USE [EdFi_Admin]

UPDATE [dbo].[ApiClients]
SET [StudentIdentificationSystemDescriptor] = N'http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local'

USE [EdFi_Admin]

SELECT ApiClientId, ApplicationEducationOrganizationId, EducationOrganizationId
FROM [dbo].[ApiClients]
JOIN [dbo].[ApiClientApplicationEducationOrganizations]
	ON [ApiClientId] = [ApiClient_ApiClientId]
JOIN [dbo].[ApplicationEducationOrganizations] 
	ON [ApplicationEducationOrganizationId] = [ApplicationEducationOrganization_ApplicationEducationOrganizationId]
WHERE ApiClientId IN (
	SELECT ac.ApiClientId
	FROM [dbo].[ApiClients] ac
	JOIN [dbo].[ApiClientApplicationEducationOrganizations] acaeo 
		ON ac.[ApiClientId] = acaeo.[ApiClient_ApiClientId]
	JOIN [dbo].[ApplicationEducationOrganizations] aeo 
		ON aeo.[ApplicationEducationOrganizationId] = acaeo.[ApplicationEducationOrganization_ApplicationEducationOrganizationId]
	WHERE ac.StudentIdentificationSystemDescriptor IS NOT NULL
	GROUP BY ac.ApiClientId
	HAVING COUNT(DISTINCT aeo.EducationOrganizationId) > 1
)

Before configuring an API client with the StudentIdentificationSystemDescriptor, an API call to the /students  endpoint would give you the existing StudentUniqueId as shown:

[
	{
    	"studentUniqueId": "604921",
    	"firstName": "Kenya",
    	"lastSurname": "Sweeney",
    	"middleName": "Kellie",
		...
    	"identificationCodes": [
        	{
            	"assigningOrganizationIdentificationCode": "Local",
            	"studentIdentificationSystemDescriptor": "Local",
            	"identificationCode": "921"
        	},
        	{
            	"assigningOrganizationIdentificationCode": "SSN",
            	"studentIdentificationSystemDescriptor": "SSN",
            	"identificationCode": "2738427539"
        	}
    	],
 		...
	}
]

After configuration, the StudentUniqueId will be translated into the IdentificationCode associated with http://ed-fi.org/Descriptor/StudentIdentificationSystemDescriptor.xml/Local.

[
	{
	    "studentUniqueId": "921",
    	"firstName": "Kenya",
    	"lastSurname": "Sweeney",
    	"middleName": "Kellie",
		...
    	"identificationCodes": [
        	{
            	"assigningOrganizationIdentificationCode": "Local",
            	"studentIdentificationSystemDescriptor": "Local",
            	"identificationCode": "921"
        	},
        	{
            	"assigningOrganizationIdentificationCode": "SSN",
            	"studentIdentificationSystemDescriptor": "SSN",
            	"identificationCode": "2738427539"
        	}
    	],
 		...
	}
]

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.