This is the API for persisted data related to academisation:
- Applications to Become an Academy
- Conversion Projects
- Advisory Board Decisions on Conversions
This API is intended to own the business logic and store data related to Preparing for Academisation: the process by which a Maintained School becomes an Academy. This fits within the responsibilities owned by the Regional Services Division:
The architecture of this solution is based on:
- Domain Driven Design
- Hexagon Architecture
The key aspiration of this architecture is to remove any references to technical frameworks (database implementations, web interfaces) from the Domain Layer, so that this layer can focus on the pure logic.
The following diagram shows the relationship between the projects in the solution:
Each of the layers in this architecture has a distinct set of responsibilities:
| Layer | Responsibility |
|---|---|
| Web | Mapping to HTTP |
| Service | Co-ordination of a complete operation |
| Domain | Validation and Mutation |
| Data | Persistence |
When running locally the webapp does not require authentication. Once deployed the authentication keys should be provided as a configuration setting. For best practice this key should be provided as a UUID:
"AuthenticationConfig__ApiKeys__0" -> "<Key>"
"AuthenticationConfig__ApiKeys__1" -> "<Key>"
Set your database connection string in user secrets:
"AcademiesDatabaseConnectionString": "connection string here"
Install the Entity Framework Core CLI Tools:
dotnet tool install --global dotnet-ef
To generate migrations, change to the WebApi directory and run the following command:
dotnet ef migrations add <MIGRATION_NAME> --project ..\Dfe.Academies.Academisation.Data\Dfe.Academies.Academisation.Data.csproj --startup-project Dfe.Academies.Academisation.WebApi.csproj --context Dfe.Academies.Academisation.Data.AcademisationContext
OR the following within Visual Studio package manager console with the the 'WebApi' project selected as a startup:-
dotnet ef migrations add WantConversionToHappenOnSelectedDate --project Dfe.Academies.Academisation.Data --startup-project Dfe.Academies.Academisation.WebApi --context Dfe.Academies.Academisation.Data.AcademisationContext
To apply a set of migrations to the database, change to the WebApi directory and run the following command:
dotnet ef database update --project ..\Dfe.Academies.Academisation.Data\Dfe.Academies.Academisation.Data.csproj --startup-project Dfe.Academies.Academisation.WebApi.csproj --context Dfe.Academies.Academisation.Data.AcademisationContext
OR the following within Visual Studio package manager console with the the 'WebApi' project selected as a startup:-
dotnet ef database update --project Dfe.Academies.Academisation.Data --startup-project Dfe.Academies.Academisation.WebApi --context Dfe.Academies.Academisation.Data.AcademisationContext
You must have the trams API docker container downloaded and running as this API uses the same database. Instructions to do this are here:- https://github.com/DFE-Digital/trams-data-api/
which has 2 main steps:-
- Creating a PAT token within GitHub as below:- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
- put that PAT token into an environment variable (windows)
- login to ghcr.io using command line:- docker login https://ghcr.io --username 'github username'
Above will prompt for password, this is the PAT token
- download & run docker image like so:- docker run -d -p 1433:1433 ghcr.io/dfe-digital/trams-development-database:latest
You may run into port issues if you have something else running on port 1433 i.e. a local install of SQL server. If this is the case, try the following command instead:- docker run -d -p 2401:1433 ghcr.io/dfe-digital/trams-development-database:latest
If you do this, remember to amend the DefaultConnection within the trams API codebase within BOTH appsettings.json files !!!
- run trams API EF migrations first to create default database:- trams API has 2 DB contexts (why?) So, firstly, you need to run the following migration:- dotnet ef database update --connection DefaultConnection --project TramsDataApi --context TramsDataApi.DatabaseModels.LegacyTramsDbContext
then:- dotnet ef database update --connection "Server=localhost,1433;Database=sip;User=sa;Password=StrongPassword905" --project TramsDataApi --context TramsDataApi.DatabaseModels.TramsDbContext
- run academisation EF migration to apply database changes specific to this API onto docker image database:-
Run npm install from the CypressTests directory
To run tests through the Cypress runner, run the following:
npm run cy:open -- --env url="BASE_URL_OF_APP",apiKey="SECRET_HERE"
To execute the tests in headless mode, run the following (the output will log to the console):
npm run cy:run -- --env url="BASE_URL_OF_APP",apiKey="SECRET_HERE"
We make use of eslint for the Cypress tests to ensure code quality. You can explicitly check for issues by running the following from the CypressTests directory:
npm run lint
Each 'it' block usually runs the test with a clear cache. For our purposes, we may need to maintain the user session to test various scenarios. This can be achieved by adding the following code to your tests:
afterEach(() => {
cy.storeSessionData();
});
The cypress.json file in the support folder contains functions which can be used globally throughout your tests. Below is an example of a custom login command
Cypress.Commands.add("login",()=> {
cy.visit(Cypress.env('url')+"/login");
cy.get("#username").type(Cypress.env('username'));
cy.get("#password").type(Cypress.env('password')+"{enter}");
cy.saveLocalStorage();
})
Which you can access in your tests like so:
before(function () {
cy.login();
});
Further details about Cypress can be found here: https://docs.cypress.io/api/table-of-contents
Nothing formal, but been using the following pattern:
AB#105435 - conversion target date - store whether target date has been chosen - 'description of this commit'