Jobindsats – Softwarearkitektur
Indholdsfortegnelse
- 1 Indholdsfortegnelse
- 2 Introduktion
- 3 Arkitekturmæssige mål og rammer
- 3.1 Non-funktionelle krav
- 3.2 Krav
- 3.2.1 Software
- 3.2.2 Webtilgængelighed
- 3.2.3 UI/UX
- 3.3 Arkitekturprincipper
- 3.4 Arkitekturmodel
- 4 Use case perspektiv
- 5 Logisk perspektiv
- 5.1 Ansvarsfordeling
- 5.1.1 Umbraco
- 5.1.2 Datamart og Metadata API
- 5.1.3 Datamart
- 5.1 Ansvarsfordeling
- 6 Proces-perspektiv
- 7 Implementerings-perspektiv
- 7.1 Frontend
- 7.2 Backend
- 7.2.1 API
- 7.2.1.1 API action return types
- 7.2.1.2 POCO-modeller
- 7.2.1 API
- 7.3 Data-backend
- 7.4 Fælles komponenter
- 7.4.1 Logger
- 8 Deployment-perspektiv
- 9 Data-perspektiv
- 10 Sikkerhedsperspektiv
Introduktion
Dette dokument beskriver softwarearkitekturen for Jobindsats 3.0. Det færdige slutprodukt henvender sig til teknisk faglige stakeholders, som har behov for et overblik over softwarearkitekturen med fokus på sammenhængen mellem løsningens perspektiver.
Betegnelser
Front-end: Samling af systemer og komponenter der understøtter adgang til data, rapporter, information mv. Dette dækker databank, rapportbank.
Database: Umbraco
Back-end: Samling af systemer og komponenter
Målingsdatabase: MSSQL der indeholder data til databanken (betegnet som Datamart)
Metadata til tabeller vedr. Målingsdatabase.
Overordnet løsningsbeskrivelse
Jobindsats løsningen dækker helt overordnet over et frontend website der udstiller STAR's offentlige data fra arbejdsområdet med forskellige visninger samt filtreringsmuligheder, samt en række backend-databaser, der persisterer de udstillede data.
Arkitekturmæssige mål og rammer
De centrale krav for løsningen er angivet i dette afsnit, øvrige krav samt non-funktionelle krav er angivet på toolkit i listen Krav.
Non-funktionelle krav
Programmering og tilpasning af front-end grænseflade til jobindsats.dk’s backend, der understøtter, at STAR i fremtiden nemmere kan overgå til nye teknologiske muligheder.
Krav
Software
Webløsninger baseres på nyeste officielle .NET version, medmindre dette er eksplicit aftalt. I skrivende stund er dette .NET 5. Da Umbraco kun understøtter .NET Framework 4.7.2, undtages dette fra dette krav.
Webtilgængelighed
Offentlige hjemmesider skal være webtilgængelige og således overholde WCAG 2.1 på niveau A og AA. Som undtagelse herfra er administrationsgrænseflader, som fx Umbraco backend.
UI/UX
Videreudviklingen af jobindsats.dk skal ske i overensstemmelse med Beskæftigelsesministeriets designguide, så hjemmesiden fremstår indbydende, professionel og som en del af Beskæftigelsesministeriets visuelle identitet.
Optimering af jobindsats.dk UX- og UI-design, skal gøre jobindsats.dk mere brugervenlig ved, at det bliver nemmere at finde, hente, forstå og anvende data fra jobindsats.dk.
Jobindsats.dk skal desuden være responsiv, så hjemmesiden kan tilgås fra smartphone og tablet.
Arkitekturprincipper
Der anvendes flg. arkitektoniske principper:
Alle databaser tilgås via API'er for at mindske kobling mellem systemer
Umbraco bruges så vidt muligt til alt frontend, og der bruges så vidt muligt standardfunktionalitet således at STAR også kan vedligeholde løsningen selv via Umbracos backend
Klar opdeling mellem data og forretnings-funktionalitet (fx opsplitning i hhv. Metadata og Datamart, hvor der opsættes API'er foran disse)
Systemkomponenter der kan deployes selvstændigt har eget repository samt selvstændig CI/CD-pipelines for at undgå afhængigheder på tværs af komponenter
Afhængigheder laves hierarkisk, og kun mod mere stabile komponenter for at undgå cirkulære og ustabile afhængigheder
Arkitekturmodel
De forskellige interessenters behov for indsigt i systemet dækkes ved at belyse arkitekturen fra forskellige perspektiver. Opdelingen i perspektiver kaldes den arkitekturmæssige repræsentation eller arkitekturmodellen.
Perspektiverne beskrevet i dette dokument er følgende:
Use-case perspektiv
Beskriver de funktionelle scenarier ud fra use-cases. Perspektivet er relevant for alle.Logisk perspektiv
Beskriver en funktionel nedbrydning af systemet udtrykt i funktionelle begreber (problemdomænets eller brugernes sprog). Der gives et overblik over systemets komponenter og logiske klasser. Perspektivet er relevant for designere og udviklere.
Proces-perspektiv
Beskriver systemets run-time aspekter og diskuterer samtidighed. Perspektivet er relevant for udviklere.
Implementerings-perspektiv
Beskriver den statiske organisering af systemets kode i moduler, lag og pakker. Perspektivet er relevant for udviklere.
Deployment-perspektiv
Beskriver afbildningen af det logiske perspektiv og proces-perspektivet på det fysiske afviklingsmiljø. Perspektivet er relevant for udviklere og driftspersonale.
Data-perspektiv
Belyser den fysiske persistering af data. Perspektivet er relevant for udviklere og driftspersonale.
Sikkerhedsperspektiv
Belyser de sikkerhedsmæssige aspekter. Perspektivet er relevant for udviklere og driftspersonale.
Use case perspektiv
Use cases er specificeret i A0140 - Funktionelle scenarier.
Logisk perspektiv
Figur 2 - Logisk opdeling af komponenter i respektive områder
Komponenter er opdelt i flg. områder:
Frontend - denne består af det offentlige Umbraco website, hvor alt funktionalitet udstilles til slutbrugerne
Backend - består af databaser samt tilhørende API'er, der anvendes af Umbraco
Eksternt - disse løsninger er udenfor scope af Jobindsats 3.0 projektet og udvikles/håndteres af STAR. Dette inkluderer PowerBI løsning og datamart.
Ansvarsfordeling
Umbraco
Indhold i Jobindsats 3.0 består hovedsageligt af en databank med tilpasset UI til præsentation af data fra databaserne og Umbraco til redaktør indhold i form af Nyhedssider, Informationssider og Rapportsidder.
Umbraco har et minimalt kendskab og afhængighed til de underliggende datamodeller. Kender kun til ID/Navn for Måling og Rapporter og har ingen anden viden om data fra Datamart eller metadata. Data til præsentation hentes ud fra måling/rapport ID igennem de underliggende API’er.
Datamart og Metadata API
Udstiller forretningsdata og dennes metadata for Umbraco, og evt. andre aftagere, via REST API.
Håndterer integration til Datamart, hvor Stored Procedure benyttes.
Adgang til Metadata databasen igennem Entity Framework.
Entity Framework er et abstraktionslag mellem brugere af data og den underliggende datamodel, hvilket sikre en løs kobling mellem data og brugen af data.
Datamart
Udstiller statistisk data igennem en Stored Procedure. Værdier der kan gives med til denne, er angivet i metadatamodellen. Ved opdateringer til navngivning i Datamart, skal ændringer også indføres i metadatamodellen.
Proces-perspektiv
Rapporter
Rapporter udarbejdes i PowerBI (PBI) af STAR, og disse udstilles ved at oprette en side i Umbraco og tilføje det iframe element som peger på rapporten – dette uddybes nærmere i Jobindsats – Brugergrænseflade-design. For at fjerne offentliggørelsen af rapporten kan iframe’en enten fjernes eller siden kan af-publiceres.
Rapporter udstilles og administreres via Umbraco. For hver rapporter der ønskes udstillet, oprettes en Umbraco side med typen Rapport til formålet, hvori der angives iframe linket til PBI-rapporten.
Alt øvrig administration af rapporter foregår i PBI.
Data
Administration af metadata foregår direkte i databasen Metadatamodel. Alternativt, hvis dette tilvælges, via den nye backend-administration der via API kommunikerer med Metadatamodel-databasen. Uddybes i D0130 og DD130 – API.
Målinger
Administration af målinger foretages direkte i databasen JI3_Datamodel.
Implementerings-perspektiv
Løsningen består af en Frontend, en Backend og et offentligt API.
Frontend
Frontend består af flg. komponenter:
Jobindsats.dk Umbraco website
Extensions for Databank, Rapportbank, etc.
Frontend er baseret på Umbraco 8. Løsningen implementeres på .NET Framework 4.7.2 og Umbraco 8.12.0 fra NuGet.
Der benyttes så vidt muligt standardfunktionalitet i Umbraco, således STAR selv er i stand til at vedligeholde centrale dele af løsningen (fx tilretning af skabeloner), samt gøre opgraderingsprocessen for Umbraco enklere ved fremtidige versioner.
Backend
Backend består af flg. komponenter:
API til metadata og datamart
SQL databaser med metadata inkl. views og stored procedure til datamart
For at undgå for høj kobling mellem API og databasen, er API'et udviklet med henblik på højest mulige fleksibilitet som et genrisk mapping-lag mellem klienter og databasen.
API
Der oprettes API'er foran alle databaser for at gøre koblingen mellem applikationer og data løsere.
API'er baseres på .NET 5 WebAPI, og der oprettes OpenAPI/Swagger API-dokumentation.
API action return types
API implementationerne benytter sig af ActionResult<T> types. Dette er standard funktionalitet indbygget i ASP.NET Core.
Dette muliggør at sende data retur med standard response koder uden at skulle pakke elementerne yderligere ind hvis der er fejl. Strukturen af det returnerede JSON er opbygget automatisk af swagger på baggrund af den POCO-model, som relaterer sig til metoden (se Jobindsats – Softwarearkitektur | [inlineExtension][inlineExtension]POCO modeller).
Hvis der opstår fejl, vil der blive returneret en internal server error (kode 500). Dette opstår dog kun hvis der er deciderede datafejl som får databasekaldende til at bryde sammen. Der sendes ikke anden information til brugeren end at der opstod en fejl. Til internt brug logges den relevante fejlbesked information om hvilken funktion der fejlede samt hvilken exception der opstod.
Hvis der i Umbraco skrives et ID som ikke findes i databasen, vil der blive returneret en no content (kode 204). Denne vil udløse at indholdet ikke bliver vist i frontenden og der vil blive skrevet en fejl i konsol loggen. Det er et redaktøransvar at kontrollere at denne type af fejl ikke opstår.
Eksempel på koder:
HTTP STATUS: 500 { "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1 ", "title": "An error occurred while processing your request.", "status": 500, "traceId": "00-e64ce621a851ba4fb598494fd15749bf-0cc27b949253664a-00" } HTTP STATUS: 200 { "maalingId": "string", "updateInfo": { "lastUpdate": "2021-12-21T12:55:29.940Z", "nextUpdate": "2021-12-21T12:55:29.940Z" }, "period": { "firstAndLast": [ "string" ], "types": [ "string" ] }, "updateFreq": "string", "area": { "wholeCountry": true, "areas": [ "string" ] }, "mGroups": [ "string" ], "dimensions": [ "string" ] } |
---|
POCO-modeller
For at sørge for at frontend (Umbraco) skal lave så få API kald som muligt til backend laves der i POCO klasser/modeller i API laget. Disse benyttes til kun at sende den data op fra backend som er relevant for frontenden.
De struktureres således i datamart serviceprojektet:
De vil altid blive navngivet med DTO (data transfer object) for at tydeliggøre at de ikke er EF objekter men derimod en simplere type af objekter. Navngivningen foretages som suffix, fx KubeDto.
Data-backend
Data-backend er et underniveau af backend-laget, hvori der placeres komponenter uden snitflade.
Data-backend består af flg. komponenter:
Datamart
SMTP
Data-backend er administreret af STAR, og er ude af scope for projektet.
Fælles komponenter
Logger
Logning opsættes via Serilog med en fælles funktionalitet, således at alle komponenter logger ens.
Deployment-perspektiv
Deployment foregår vha. artefakts genereret af en CI/CD-pipeline som manuelt overføres til de respektive miljøer. Denne proces er nærmere beskrevet i https://starwiki.atlassian.net/wiki/download/attachments/3428122719/Jobindsats – Vedligeholdelsesvejledning.docx?api=v2i deployment afsnittet.
Opdeling i løsningskomponenter
Løsningen er opdelt i flg. komponenter, der hver især kan deployes individuelt. Hver løsning har sit eget Git-repository på Azure DevOps på https://source.netcompany.com/tfs/Netcompany/SFARJOBIN/.
Jobindsats.Datamart.Service
Indeholder API til Datamart samt Metadatadatabasen
Jobindsats.Web
Indeholder Umbraco-løsning samt database
Jobindsats.Util.Pivottable
Indeholder en modificeret udgave af PivoTable.js lavet til Jobindsats 3.0
Data-perspektiv
Umbraco er db-owner set fra Jobindsats 3.0
Datamart er read-only set fra jobindsats 3.0
Metadata er read-only set fra jobindsats 3.0
Metadata skal redigeres gennem SQL Server Management Studio.
Sikkerhedsperspektiv
Microsoft tilbyder et gratis værktøj til trusselsmodellering som er lavet for at hjælpe udviklere med at finde trusler i designfasen af et udviklingsprojekt. LINK til yderligere information: http://blogs.microsoft.com/cybertrust/2015/10/07/whats-new-with-microsoft-threat-modeling-tool-2016/