Jobindsats – Softwarearkitektur

Indholdsfortegnelse

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": "RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content ",

"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"

]

}

HTTP STATUS: 500

{

"type": "RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content ",

"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/