Skip to content

UC1: Configureren project

Functioneel ontwerp use case: UC1: Configureren project

1. Front-end componenten

Voor deze use case is een nieuwe instelling pagina gemaakt, die tevoorschijn komt als er op de "Koppelingen" tab in de instellingen pagina geklikt wordt. In de VersionControlSettings zijn de volgende componenten aangemaakt en aangepast voor de selectie van het project:

  • ProjectOption & ProjectControl: Dit component wordt gebruikt om een project te selecteren uit de projecten die in het versiebeheer systeem staan. Dit component gebruikt als basis nog steeds het template FormSelect component, maar de Option en Control componenten daarbinnen zijn vervangen om de projecten mooi weer te kunnen geven.
  • RepositoryTypeOption & RepositoryTypeControl: Dit component wordt gebruikt om een versiebeheersysteem te selecteren uit de versiebeheersystemen die ondersteund worden. Dit component gebruikt als basis nog steeds het template FormSelect component, maar de Option en Control componenten daarbinnen zijn vervangen om de versiebeheersystemen mooi weer te kunnen geven.
  • StorageZoneOption & StorageZoneControl: Dit component wordt gebruikt om een opslag zone uit de CDN te selecteren. Dit component gebruikt als basis nog steeds het template FormSelect component, maar de Option en Control componenten daarbinnen zijn vervangen om de opslagzones mooi weer te kunnen geven.
  • FormSelect: Dit component is aangepast zodat er een model aan meegegeven kan worden, dit is gedaan zodat alle informatie van het model in de andere componenten gebruikt kan worden.
Front-end componenten
Afbeelding: Front-end componenten van UC1

2. Back-end componenten

In het volgende diagram zijn de verschillende onderdelen van de back-end van UC1 weergegeven. In de VersionControlService zit een abstractie laag die de koppeling met Git versiebeheer systemen afhandelt (klik hier voor meer informatie over de abstractielaag). Hierdoor is het mogelijk om in de toekomst eenvoudig een ander Git versiebeheer systeem te koppelen.

Back-end componenten
Afbeelding: Back-end componenten van UC1

3. API endpoints

3.1. VersionControlController

Ophalen ondersteunde versiebeheer systemen

Endpoint: /api/VersionControl/systems
Method: GET
Rechten: Admin
Beschrijving: Haalt alle ondersteunde versiebeheer systemen op.

Responses

Status code: 200 (OK), ondersteunde versiebeheer systemen zijn opgehaald. 

1
2
3
4
5
6
7
[
    {
        "name": "string",
        "type": "VersionControlType",
    }
    ...
]

Status code: 400 (Bad Request), er zijn geen versiebeheersystemen ingesteld.

1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

3.2. ProjectSettingsController

ProjectSettingsController

Valideren en opslaan access token versiebeheersysteem

Endpoint: /api/ProjectSettings/{projectId:guid}/token
Method: POST
Rechten: Admin
Beschrijving: Valideert de meegegeven access token, en slaat deze bij het bijhorende project op als deze valide is.

Request 
1
2
3
4
{
    "repositoryType": "VersionControlType",
    "repositoryAccessToken": "string"
}
Responses

Status code: 200 (OK), access token is gevalideerd en opgeslagen.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • Het opgegeven versiebeheersysteem wordt niet ondersteund
  • De access token is ongeldig
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 422 (Unprocessable Entity), een van de gegeven waardes is incorrect.

  • repositoryType is niet opgegeven of te lang
  • repositoryAccessToken is niet opgegeven of te lang
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Ophalen versiebeheersysteem koppeling instellingen van project

Endpoint: /api/ProjectSettings/{projectId:guid}/repository
Method: GET
Rechten: Ingelogd
Beschrijving: Haalt de versiebeheersysteem koppeling instellingen van het project op.

Responses

Status code: 200 (OK), versiebeheer instellingen zijn opgehaald. 

1
2
3
4
5
6
{
    "repositoryProjectId": "string",
    "repositoryType": "VersionControlType",
    "repositoryAccessToken": "string",
    "repositoryDefaultBranch": "string",
}

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), is niet ingelogd.

Opslaan versiebeheersysteem project koppeling

Endpoint: /api/ProjectSettings/{projectId:guid}/repository
Method: POST
Rechten: Admin
Beschrijving: Slaat de koppeling tussen het project en het versiebeheer project op.

Request 
1
2
3
4
{
    "repositoryProjectId": "string",
    "repositoryDefaultBranch": "string",
}
Responses

Status code: 200 (OK), koppeling is opgeslagen.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • Er is geen versiebeheersysteem of access token ingesteld
  • Het versiebeheersysteem project of de defaultBranch zijn leeg
  • Het opgegeven versiebeheersysteem wordt niet ondersteund
  • De access token is ongeldig
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 422 (Unprocessable Entity), een van de gegeven waardes is incorrect.

  • repositoryProjectId is niet opgegeven of te lang
  • repositoryDefaultBranch is niet opgegeven of te lang
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Verwijderen versiebeheer project koppeling

Endpoint: /api/ProjectSettings/{projectId:guid}/repository
Method: DELETE
Rechten: Admin
Beschrijving: Verwijdert de koppeling tussen het project en het versiebeheer project.

Responses

Status code: 200 (OK), koppeling is verwijderd.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • Er is geen versiebeheersysteem ingesteld
  • Er is geen versiebeheersysteem project gekoppeld
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Ophalen ondersteunde projecten van versiebeheer systeem

Endpoint: /api/ProjectSettings/{projectId:guid}/projects
Method: GET
Rechten: Ingelogd
Beschrijving: Haalt alle publieke projecten op, inclusief het project met de gekoppelde access token.

Responses

Status code: 200 (OK), ondersteunde versiebeheer systemen zijn opgehaald. 

1
2
3
4
5
6
7
8
9
[
    {
        "id": "string",
        "name": "string",
        "defaultBranch": "string",
        "namespace": "string",
    }
    ...
]

Status code: 400 (Bad Request), mogelijke oorzaken:

  • project ID is incorrect
  • er is geen versiebeheersysteem ingesteld
  • het versiebeheersysteem dat is opgeslagen wordt niet ondersteund
  • de access token is ongeldig
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), is niet ingelogd.

Ophalen opslagzones van CDN

Endpoint: /api/ProjectSettings/cdn/storage-zones
Method: GET
Rechten: Admin
Beschrijving: Haalt alle storage zones uit de huidig ingestelde CDN op.

Responses

Status code: 200 (OK), storage zones zijn opgehaald. 

1
2
3
4
5
6
7
[
    {
        "id": 0,
        "name": "string",
    }
    ...
]

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 500 (Internal Server Error), mogelijke oorzaken:

  • Kon geen opslag zones ophalen
  • Geen opslag zones gevonden

Ophalen opslagzone van CDN voor project

Endpoint: /api/ProjectSettings/{project:guid}/cdn
Method: GET
Rechten: Ingelogd
Beschrijving: Haalt huidige CDN koppeling op, deze kan ook leeg zijn.

Responses

Status code: 200 (OK), huidige storage zone is succesvol opgehaald. 

1
2
3
4
5
6
7
8
[
    {
        "id": 0,
        "name": "string",
        "apiKey": "string",
    }
    ...
]

Status code: 400 (Bad Request), mogelijke oorzaken:

  • Project ID is incorrect
  • Opgeslagen CDN opslagzone bestaat niet
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), is niet ingelogd.

Status code: 500 (Internal Server Error), mogelijke oorzaken:

  • Kon geen opslag zones ophalen
  • Geen opslag zones gevonden

Koppelen opslagzone van CDN aan project

Endpoint: /api/ProjectSettings/{project:guid}/cdn
Method: POST
Rechten: Admin
Beschrijving: Koppelt CDN opslagzone aan project.

Responses

Status code: 200 (OK) koppeling is succesvol opgeslagen.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • Project ID is incorrect
  • Opslag zone id is leeg
  • Opslag zone key is leeg
  • Geselecteerde CDN opslag zone bestaat niet
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 500 (Internal Server Error), mogelijke oorzaken:

  • Kon geen opslag zones ophalen
  • Geen opslag zones gevonden

Ontkoppelen opslagzone van CDN van project

Endpoint: /api/ProjectSettings/{project:guid}/cdn
Method: DELETE
Rechten: Admin
Beschrijving: Verwijdert de huidige CDN koppeling van het project.

Responses

Status code: 200 (OK), gekoppelde storage zone is succesvol ontkoppeld.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • Project ID is incorrect
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 500 (Internal Server Error), mogelijke oorzaken:

  • Kon geen opslag zones ophalen
  • Geen opslag zones gevonden

Verwijderen cache CDN van project

Endpoint: /api/ProjectSettings/{project:guid}/cdn/cache
Method: DELETE
Rechten: Admin
Beschrijving: Verwijdert de cache van de CDN die gekoppeld is aan het project.

Responses

Status code: 200 (OK), cache is succesvol verwijderd.

Status code: 400 (Bad Request), mogelijke oorzaken:

  • Project ID is incorrect
  • Project heeft geen gekoppelde CDN opslagzone
  • Gekoppelde opslagzone kon niet gevonden worden
  • Key van de zone is niet ingesteld
1
2
3
4
5
6
7
8
9
{
    "errors": [
        {
            "key": "string",
            "message": "string"
        }
        ...
    ]
}

Status code: 401 (Unauthorized), heeft geen Admin rechten.

Status code: 500 (Internal Server Error), mogelijke oorzaken:

  • Kon geen opslag zones ophalen
  • Geen opslag zones gevonden

4. Technische keuzes

4.1. Abstractie voor koppeling met Git versiebeheer systemen

De applicatie maakt gebruik van een extern Git versiebeheer systeem om onder andere de vertalingen op te halen en de slaan. In de huidige planning voor de MVP wordt de applicatie alleen gebouwd om GitLab te ondersteunen. Er is tijdens het vastleggen van de functionele eisen echter wel duidelijk geworden dat de applicatie in de toekomst mogelijk ook gebruikt gaat worden met andere Git versiebeheer systemen. Om de applicatie hierop voor te bereiden is er een abstractie laag gemaakt die de koppeling met Git versiebeheer systemen afhandelt. Hierdoor is het mogelijk om in de toekomst eenvoudig een ander Git versiebeheer systeem te koppelen.

In Sprint 7, Week 14 op Dinsdag 10 December is besloten om de een integratie voor Azure DevOps te schrijven.

Voor de abstractie is gebruik gemaakt van het (Adapter Pattern, n.d.). Dit patroon zorgt ervoor dat er gemakkelijk meerdere implementaties toegevoegd kunnen worden. De interface van de adapter zorgt er ook voor dat meerdere versiebeheersystemen tegelijk gebruikt kunnen worden.

Het volgende diagram geeft een idee over hoe de abstractie laag werkt, in het diagram zijn verschillende modellen, methoden en properties weggelaten om het diagram overzichtelijk te houden. Het ProjectRepositorySettingsModel bevat alle velden die vereist zijn om een project te koppelen met een versiebeheer systeem. De VersionControlService bevat een lijst van alle versiebeheer systemen die ondersteund worden. De ValidateAndReturnVersionControlSystemAsync methode valideert de access token en geeft het versiebeheer systeem terug.

VersionControlType is een enum met alle verschillende ondersteunde versiebeheer systemen.

classDiagram
    IVersionControlSystemService <|.. GitlabVersionControlService : implements
    GitlabVersionControlService : public VersionControlType GetVersionControlType()
    GitlabVersionControlService : ...
    GitlabVersionControlService : ...()
    IVersionControlSystemService <|.. AzureDevOpsVersionControlService : implements
    AzureDevOpsVersionControlService : public VersionControlType GetVersionControlType()
    AzureDevOpsVersionControlService : ...
    AzureDevOpsVersionControlService : ...()
    VersionControlService --> IVersionControlSystemService : contains
    ProjectRepositorySettingsModel <-- VersionControlService : uses
    IVersionControlSystemService : public VersionControlType GetVersionControlType()
    IVersionControlSystemService : ...
    IVersionControlSystemService : ...()
    <<interface>> IVersionControlSystemService

    class VersionControlService{
        private readonly IVersionControlSystemService[] versionControlSystems
        ...

        public async Task IVersionControlSystemService ValidateAndReturnVersionControlSystemAsync(ProjectRepositorySettingsModel projectRepositorySettingsModel)
        ...()
    }

    class ProjectRepositorySettingsModel{
        VersionControlType RepositoryType
        string RepositoryAccessToken
        string RepositoryProjectId
        string RepositoryDefaultBranch
        string RepositoryBranchAwaitingMerge
    }

Bekijk de algemene technisch keuzes

5. Test cases

De end-to-end tests valideren de flow van de use case. De reden dat alle flows getest worden is omdat dit een van de belangrijkste functionaliteiten is van de applicatie. Als deze functionaliteit niet werkt, kunnen er geen projecten opgehaald worden, en kunnen er geen vertalingen opgehaald worden. Hierdoor kan een klant zijn vertalingen dus ook niet beheren.

Voor deze use case is gekozen om zowel end to end tests als unit tests te schrijven. De end to end tests zijn geschreven om de flow van de use case te valideren, terwijl de unit tests geschreven zijn om de verbinding met GitLab te valideren.

Test cases
Afbeelding: Testcases van UC1

5.1. End to end tests

Er is een keuze gemaakt om end to end tests te schrijven voor deze use case, omdat de koppeling tussen het project en het systeem vereist is om vertalingen te kunnen beheren. Als deze functionaliteit niet werkt, kunnen de vertalingen ook niet beheerd worden. De meest gemakkelijke manier om alle scenario's te testen is door de flow van de use case te testen. Omdat de back-end en front-end in verbinding met elkaar staan aan de hand van de API endpoints, is het belangrijk dat deze verbinding goed werkt. De end to end tests valideren of de flow van de use case werkt, en of de back-end en front-end goed met elkaar communiceren.

Voor sommige testen is het nodig om een access token te valideren bij een extern versiebeheersysteem, in situaties waarbij de token geldig moet zijn wordt een gemockte versie van een versiebeheersysteem gebruikt. Hierdoor kunnen scenario's die na de validatie van de token komen ook getest worden zonder gevoelige gegevens in de code op te slaan. De service accepteert alle tokens als een valide token, behalve als de token het woord "invalid bevat". Als de token geldig is geeft de service een lijst van projecten terug. Hierdoor kan de flow van de use case getest worden zonder dat er een echte token nodig is.

5.1.1. De tests

  • Test 1: Admin kan de instellingen pagina bereiken
  • Test 2: Gebruiker kan de instellingen pagina niet bereiken
  • Test 3: Token opslaan bij project met niet bestaand versiebeheersysteem
  • Test 4: Token opslaan bij project met invalide access token
  • Test 5: Project koppelen met correcte access token en versiebeheersysteem
  • Test 6: Project ontkoppelen met valide koppeling naar versiebeheersysteem
  • Test 7: Project koppelen zonder valide koppeling naar versiebeheersysteem
  • Test 8: Project koppelen met valide koppeling naar versiebeheersysteem
  • Test 9: Project koppeling bijwerken met correcte access token
  • Test 10: Project koppeling bijwerken met incorrecte access token
  • Test 11: Project ontkoppelen zonder valide koppeling naar versiebeheersysteem
  • Test 12: CDN koppelen aan project met valide opslagzone en key
  • Test 13: CDN koppelen aan project met valide opslagzone zonder key
  • Test 14: CDN koppeling van project bijwerken met nieuwe valide key
  • Test 15: CDN koppeling van het project bijwerken met lege key
  • Test 16: CDN ontkoppelen van project met gekoppelde opslagzone

5.2. Unit tests

Er is één unit test geschreven om de verbinding met GitLab te valideren. Dit is gedaan, omdat GitLab een grote afhankelijkheid is voor dit onderdeel van de applicatie. Doordat deze test bestaat is sneller te achterhalen of het probleem bij GitLab of bij ons ligt. De test valideert of de verbinding met GitLab werkt, en of de projecten opgehaald kunnen worden. Als deze test faalt, is het duidelijk dat de verbinding met GitLab niet werkt, en kan er direct actie ondernomen worden.

5.2.1. De tests

  • Test 1: Test of de verbinding met GitLab werkt.
  • Test 2: Test of de verbinding met BunnyCDN werkt.

Bronnen

  1. Adapter Pattern. (n.d.). Geraadpleegd op 16 December 2024, van https://refactoring.guru/design-patterns/adapter