The TRS is a database of people who work in Education in the UK. It is the primary source of teaching records for DfE. It holds data to meet UK Government statutory obligations as well as allow individuals working in the UK education system (including, but not limited to) teachers in schools within England, Wales, Scotland and Northern Ireland to access digital services provided by the DfE. It is also a DfE web service used by DfE support teams. It is the source of Teaching Reference Number (TRN) used in a number of Education services and processes both inside and outside of DfE.
The TRN is a unique 7-digit reference given to identify a person whose data is in the Teaching Record System (formerly Database Of Qualified Teachers). TRNs are given to trainee teachers, qualified teachers (QTS and many other teaching related qualifications), and anyone eligible for a teaching pension and other related services.
It is a character string of len(7) e.g.:
'1234567', '0001234'- High Level Data Integrations
- Low level example using Access Your Teaching Qualifications
- Low level example showing Teacher Pensions Service
The API is versioned and each endpoint is prefixed with the version number e.g. /v3/. V3 is further split into minor versions; a header should be added to your requests indicating which minor version you want e.g.
X-Api-Version: 20240101
Wherever possible you should call the latest version.
You can view the API specifications for each version by visiting /swagger (see Environments below for the base addresses).
An API key is required for calling the API; speak to one of the developers to get one. The key must be passed in an Authorization header e.g.
Authorization: Bearer your_api_key
See the changelog for the details of what has changed between versions.
| Name | API URL |
|---|---|
| Production | https://teacher-qualifications-api.education.gov.uk |
| Pre-production | https://preprod.teacher-qualifications-api.education.gov.uk |
| Test | https://test.teacher-qualifications-api.education.gov.uk/ |
| Development | https://dev.teacher-qualifications-api.education.gov.uk/ |
The API is an ASP.NET Core 8 web application. To develop locally you will need the following installed:
- Visual Studio 2022 (or the .NET 8 SDK and an alternative IDE/editor);
- a local Postgres 15+ instance;
- NPM.
A justfile defines various recipes for development. Ensure just is installed and available on your $PATH as well as PowerShell v7+.
If you're working on infrastructure you will also need:
- make;
- Terraform;
- Azure CLI;
- bash.
A just recipe will install the required local tools:
just install-toolsAs well as NuGet packages, there are some client-side libraries required. A just recipe will install both:
just restoreThe Support UI uses Azure Blob Storage for storing files. For local development, you can use the Azure Storage Emulator - Azurite. If you use Visual Studio 2022 you probably have it installed already otherwise you can install it from here. Run it before starting the Support UI.
Playwright is used for end-to-end testing. Install it with a just recipe:
just install-playwrightNote: the solution must be built first as the recipe requires the existence of bin/Debug/net8.0/playwright.ps1 which is generated when the Microsoft.Playwright package is built.
Install Postgres then set a connection string configuration entry in user secrets for running the apps and another for running the tests. Note you should use a different database for tests as the test database will be cleared down whenever tests are run.
e.g.
# local settings
just set-secret ConnectionStrings:DefaultConnection "Host=localhost;Username=postgres;Password=your_postgres_password;Database=trs"
# test settings
just set-tests-secret ConnectionStrings:DefaultConnection "Host=localhost;Username=postgres;Password=your_postgres_password;Database=trs_tests"To set up the initial trs database schema run:
just build
just cli migrate-dbThe trs_tests database will be created automatically when running the tests.
If you need to change the Postgres database tables, the best way to do this is to update the Model files, in TeachingRecordSystem.Core\DataStore\Postgres\Models\, and update the appropriate Entity Framework mapping file in TeachingRecordSystem.Core\DataStore\Postgres\Mappings\.
Once the model/mapping files have been changed, a migration file will need to be created - this can be done automatically by running:
just ef migrations add <a migration name>where the migration name is conventionally a title-case short description of the change, e.g. AddUserRoleColumn.
If you are seeing the error DbContext has pending changes not covered by a migration when running the tests or the web application locally, it usually means a change has been made to the model without an appropriate migration file. Running the recipe above to add the migration should fix this.
In order for the local trs database to pick up the change, the migrate recipe will need to be run:
just cli migrate-dbThe trs_tests database for the tests should be migrated automatically when running the tests.
The trs_tests database for the tests should be migrated automatically, however sometimes it gets stuck and the tests may fail with the message:
Microsoft.EntityFrameworkCore.DbUpdateException : An error occurred while saving the entity changes. See the inner exception for details.
---- Npgsql.PostgresException : <some Postgres error, e.g. missing table or column>
If this happens, regenerating the test cache usually fixes this, there's a just recipe:
just remove-tests-schema-cacheThis solution contains a service that synchronises changes from CRM into a SQL Server database used for reporting (this replaces the now-deprecated Data Export Service). It also synchronises selected tables from TRS. By default, this is disabled for local development. For the tests to pass, you will need a test database and a connection string defined in user secrets e.g.
just set-tests-secret DqtReporting:ReportingDbConnectionString "Data Source=(local);Initial Catalog=DqtReportingTests;Integrated Security=Yes;TrustServerCertificate=True"Your postgres server's wal_level must be set to logical:
ALTER SYSTEM SET wal_level = logical;
You will have to restart the server after amending this configuration.
To run the service locally override the configuration option to run the service and ensure a connection string is provided e.g.
just set-secret DqtReporting:RunService true
just set-secret DqtReporting:ReportingDbConnectionString "Data Source=(local);Initial Catalog=DqtReporting;Integrated Security=Yes;TrustServerCertificate=True"The service will now run as a background service of the Worker project.
It is a good idea to remove the replication slot when you're not working on this service to avoid a backlog on unprocessed changes accumulating in postgres.
just set-secret DqtReporting:RunService false
just cli drop-dqt-reporting-replication-slotAdd yourself to your local database as an administrator:
just create-admin "[email protected]" "Your Name"There are several external dependencies required for local development; these are listed below. Ask a developer on the team for the user secrets for these dependencies.
The build CRM environment is used for local development and automated tests.
The secrets you will need to set are as follows:
# local settings
just set-secret ConnectionStrings:Crm "AuthType=ClientSecret;Url=https://ent-dqt-build.crm4.dynamics.com;ClientId=<REDACTED>;ClientSecret=<REDACTED>;RequireNewInstance=true"
just set-secret CrmClientId "<REDACTED>"
just set-secret CrmClientSecret "<REDACTED>"
just set-secret CrmUrl "https://ent-dqt-build.crm4.dynamics.com"
# test settings
just set-tests-secret ConnectionStrings:Crm "AuthType=ClientSecret;Url=https://ent-dqt-build.crm4.dynamics.com;ClientId=<REDACTED>;ClientSecret=<REDACTED>;RequireNewInstance=true"
just set-tests-secret CrmClientId "<REDACTED>"
just set-tests-secret CrmClientSecret "<REDACTED>"
just set-tests-secret CrmUrl "https://ent-dqt-build.crm4.dynamics.com"The API calls the TRN Generation API to generate a TRNs.
The secrets you will need to set are as follows:
# local settings
just set-secret TrnGenerationApi:BaseAddress "https://dev.trn-generation-api.education.gov.uk/"
just set-secret TrnGenerationApi:ApiKey "<REDACTED>"
# test settings
just set-tests-secret TrnGenerationApi:BaseAddress "https://dev.trn-generation-api.education.gov.uk/"
just set-tests-secret TrnGenerationApi:ApiKey "<REDACTED>"Azure AD is used for authenticating users in the Support UI.
The secrets you will need to set are as follows:
just set-secret AzureAd:ClientSecret "<REDACTED>"
just set-secret AzureAd:ClientId "<REDACTED>"There are additional secrets you will need to set are as follows:
# local settings
just set-secret AccessYourTeachingQualifications:BaseAddress "https://dev.access-your-teaching-qualifications.education.gov.uk/"
just set-secret AccessYourTeachingQualifications:StartUrlPath "/qualifications/start"
just set-secret GetAnIdentity:WebHookClientSecret "dummy"
just set-secret GetAnIdentity:TokenEndpoint "https://dev.teaching-identity.education.gov.uk/connect/token"
just set-secret GetAnIdentity:ClientSecret "<REDACTED>"
just set-secret GetAnIdentity:ClientId "dqt-api"
just set-secret GetAnIdentity:BaseAddress "https://dev.teaching-identity.education.gov.uk/"
just set-secret Webhooks:CanonicalDomain "https://localhost:5001"
just set-secret Webhooks:SigningKeyId "devkey"
just set-secret Webhooks:Keys:0:KeyId "devkey"
just set-secret Webhooks:Keys:0:CertificatePem "<REDACTED>"
just set-secret Webhooks:Keys:0:PrivateKeyPem "<REDACTED>"
just set-secret BuildEnvLockBlobUri "https://s165d01inttests.blob.core.windows.net/leases/build.lock"
just set-secret BuildEnvLockBlobSasToken "<REDACTED>"
# test settings
just set-tests-secret BuildEnvLockBlobUri "https://s165d01inttests.blob.core.windows.net/leases/build.lock"
just set-tests-secret BuildEnvLockBlobSasToken "<REDACTED>"A tool is used to generated proxy classes for the entities defined within the DQT CRM.
The tool generates the TeachingRecordSystem.Dqt.Models.GeneratedCode.cs and TeachingRecordSystem.Dqt.Models.GeneratedOptionSets.cs files.
A configuration file at crm_attributes.json whitelists the entities and their attributes which are included on the generated types.
Run just generate-crm-models to run the code generator against the build environment using the configuration file above.
The CRM user secrets described within Developer setup must be correctly set for the tool to run successfully.
The tool is a .NET Framework application and requires .NET 4.6.
Note: Make sure Visual Studio is closed before running this recipe as otherwise it may fail due to these files being already in use by the Visual Studio process.
Environment-specific configuration is stored in Key Vault inside a single JSON-encoded key named 'AppConfig'. This is retrieved via Terraform at deployment time and is set as an environment variable so it can be accessed by the application.
Pull request builds will run format checks on .NET and Terraform code changes; if there are any issues the build will fail.
Before committing you can format any changed files by running:
just format-changedTo format the entire codebase run
just formatFor either of these recipes to work, the Terraform tool must be installed - on Windows, download the binary, copy into an appropriate location and update the PATH environment variable to point to the downloaded file.
If you're using Visual Studio 2022 you can also set up Code Cleanup, this will use the settings defined in the .editorconfig file in the repository root (this is also added to the Solution Items folder in the solution).
To set this up, go to Tools > Options > Text Editor > Code Cleanup and click Configure Code Cleanup. This will present you with a window with two profiles to configure, the easiest thing to do is to select Profile 1 (default), and select all the "Available fixers" (bottom panel), and add them to the "Included fixers" (top panel). Now you can use the "paintbrush" icon in the text editor status bar (to the left of the horizontal scrollbar) to format the document you're working on (keyboard shortcut: Ctrl+K, Ctrl+E) - or you can go to Tools > Options > Text Editor > Code Cleanup and check Run Code Cleanup profile on Save.
Note: just format and just format-changed call dotnet dotnet-format - this is different to dotnet format so be aware that calling dotnet format may produce different results.