Procedure og format for dataleverancer

Dataleverancer beskrives som følgende:

• https://starwiki.atlassian.net/wiki/display/FYS/AbsenceRegistrationService

Dataleverancer via SFTP

Dataleverancerne via SFTP anvender grundlæggende samme procedure som beskrevet af KOMBIT i:

• https://share-komm.kombit.dk/P013/Delte%20dokumenter/Vejledning%20til%20Serviceplatformens%20SFTP%20Service.docx

Dette afsnit indeholder generel information om Serviceplatformens SFTP server, samt en beskrivelse af de to typer filudveksling.

Brug af SFTP serveren

Adgang til SFTP serveren

Et it-system logger på SFTP serveren ved brug af it-systemets SSH nøgle. Denne SSH nøgle skal genereres, før et it-system kan blive registreret som it-system, der kan anvende SFTP serveren. Serviceplatformen skal kende den offentlige del af SSH nøglen i forbindelse med registrering af it-systemet og muligheden for anvendelse af SFTP.

Generering af SSH nøgler

Der findes flere forskellige fremgangsmåder der kan bruges til at generere SSH nøgler. Serviceplatformens SFTP server kræver at SSH nøglerne er generet med OpenSSH. Den følgende metode kan bruges på både Windows, Linux og OSX, givet at OpenSSH er installeret på maskinen.

På Windows skal det bemærkes at OpenSSH ikke er en del af standard installationen. Proceduren kan dog udføres i programmet Cygwin, der kan findes på følgende hjemmeside: http://cygwin.com/install.html.

1. Åben en terminal (Cygwin terminal på Windows maskiner) og indtast følgende kommando:

2. Du bliver bedt om at specificere hvor nøglen skal gemmes. Det anbefales blot at trykke enter og bruge den foreslåede placering:  

3. Du bliver bedt om at indtaste et passphrase, hvilket er en adgangskode. Indtast den ønskede passphrase (bemærk det er også muligt at indtaste en tom passphrase) og tryk enter:  

4. Herefter genereres SSH-nøglen og placeringen af den offentlige nøgle og private del af nøglen angives.

Den offentlige del af nøglen som i dette eksempel ligger i filen id_rsa.pub i mappen /home/EPM/.ssh/, skal Serviceplatformen have i forbindelse med registrering af et it-system, der skal kunne benytte SFTP. Dette er beskrevet nærmere i afsnit 4. 

I eksemplet ovenfor findes den private del af nøglen i filen id_rsa i mappen /home/EPM/.ssh/.

Mappestruktur

Når et it-system er registret og kan anvende SFTP har it-systemet adgang til to private mapper på SFTP serveren:

• IN: Den indkommende mappe, hvor it-systemet modtagerfiler sendt til it-systemet. 

• OUT: Den udgående mappe, hvor it-systemet uploader de filer, det ønsker at sende til andre it-systemers mapper på SFTP serveren.

Upload af filer

Når dit it-system ønsker at sende filer til andre registrerede it-systemer på Serviceplatformen, er der følgende krav i forbindelse med upload af filer til SFTP serveren.

• Hver fil skal have et unikt navn: En fil kan kun overføres til modtagersystemets IN-mappe, hvis filnavnet er unikt. Filen afvises hvis der allerede findes en fil ved samme navn i IN-mappen hos modtagersystemet. Dette er for at undgå, at den nye fil overskriver en eksisterende fil i IN-mappen. For at undgå at få filoverførsler afvist grundet enslydende filnavne, anbefales det at definere en navnekonvention for filnavne, eksempelvis ved at præ- eller postfixe filnavne med en unik tekststreng. Et eksempel på dette kunne være, at it-systemet Kombit uploader filen med navnet eksempel.txt til SFTP serveren med navnet Kombit_eksempel.txt.

• Filer skal uploades til OUT-mappen: Det er kun filer uploadet til OUT-mappen som bliver videresendt til andre it-systemers IN-mapper. Uploades filen fejlagtig til IN-mappen vil den ikke blive behandlet.
• Triggerfil overføres efter endt filupload: Alle filoverførsler hvor it-systemet anvender typen simpel overførsel af filer, skal forsynes med en triggerfil. Filen skal først være færdig uploadet i OUT-mappen før, der skal sendes en triggerfil for filoverførslen. Sendes triggerfilen før endt filupload kan overførslen risikere at blive afvist.

Oprydning på SFTP serveren

It-systemer skal regelmæssigt at rydde deres IN- og OUT-mapper på SFTP serveren. Det gøres ved at slette filer der er færdigbehandlede. 

SFTP Servicen stiller følgende begrænsninger for et it-systems brug af SFTP serveren:

• Et it-system må højst have 10.000 filer i dets IN-mappe på SFTP serveren. 

Serviceplatformen rydder dagligt op på SFTP serveren og sletter alle filer, der har ligget uændret på SFTP serveren i 30 dage.  På et Linux filsystem som SFTP serveren er baseret på har filer et tidsstempel, der siger hvornår de sidst er blevet ændret. Hvis en fil ikke er blevet ændret i 30 dage så notificeres it-systemet, der ejer filen om, at den vil blive slettet indenfor 10 dage. Hvis de 10 dage går og filen stadig ligger på serveren, vil den blive slettet.

Information omkring SFTP server

It-systemer skal tilgå Serviceplatformens SFTP server via dens offentlige IP adresse.

Simpel overførsel af filer

Ved simpel overførsel af filer sker udvekslingen af beskeder mellem modtagersystemet, afsendersystemet, og SFTP Servicen ved hjælp af filer på SFTP serveren.

For at give overblik over de forskellige trin, som indgår i udveksling af en fil ved typen simpel overførsel af fil, kan følgende brugseksempel konsulteres.

Brugseksempel

Dette brugseksempel dækker følgende scenarie: It-systemet med SFTP brugernavnet DemoAfsender ønsker at afsende filen info.txt til it-systemet DemoModtager.

Følgende figur viser de forskellige trin involveret ved simpel overførsel af filer. 

1. Upload af fil samt triggerfil: Afsendersystemet uploader filen info.txt til dets OUT-mappe på SFTP serveren sammen med triggerfilen info.trigger, der har indholdet vist nedenfor. Bemærk at ”Sender” feltet skal udfyldes med SFTP brugernavnet på afsendersystemet.

2. Teknisk kvittering uploades til afsendersystemet: Triggerfilen valideres af Serviceplatformen og en teknisk kvittering uploades til afsendersystemets IN-mappe. Hvis triggerfilen er valid ”låses” filen info.txt i afsendersystemets mappe, så den ikke kan ændres efter valideringen af triggerfilen er foretaget. I praksis sker ”låsningen” ved, at afsendersystemets skriverettigheder til filen fjernes. Efter valideringen af triggerfilen slettes den fra afsendersystemets IN-mappe.

Den tekniske kvittering vil have som udgangspunkt have filnavnet info.receipt, altså filnavnet på filen, der sendes, postfixet med ”.receipt”. Det skal dog bemærkes at hvis en teknisk kvittering med dette navn allerede ligger i afsendersystemets IN-mappe vil den tekniske kvittering få navnet info.receipt<TIMESTAMP>, hvor <TIMESTAMP> i praksis vil være erstattet af et timestamp i millisekunder for hvornår den tekniske kvittering er genereret. I dette scenarie vil den tekniske kvittering have følgende indhold:

3. Filen overføres til modtagersystemet sammen med en metadata fil: Filen info.txt overføres fra afsendersystemets OUT-mappe til modtagersystemets IN-mappe. Ved samme proces uploades der en metadata fil til modtagersystemets IN-mappe. Metadata filen vil have filnavnet info.txt.metadata og have følgende indhold:

4. Modtagersystemet tjekker dets IN-mappe og finder filen: Modtagersystemet vil ved simpel overførsel af filer ikke modtage nogen notifikation om, at filen er blevet overført til dets IN-mappe. Det er derfor selv ansvarlig for at opdage, at en fil er blevet overført til det. Modtagersystemet kan bl.a. gøre dette ved periodisk at downloade alle filer fra dets IN-mappe.

Dataformater i filerne

Hermed input til indhold af data-filer:

Derudover er der kommunenumre, som tidligere har været 4 cifre med foranstillet nul, hvis kommunenummeret er på 3 cifre.  I den fremtidige verden anvendes kommunernes cvr-numre som identifikation.

Sidst er der også et kontrol-element med følgende informationer:

Det har tidligere været håndteret som selvstændige kontrol-filer, men kan måske også håndteres som header i datafil.

Jeg håber du kan bruge det, og sig endelig til hvis derer spørgsmål, eller du har behov for yderligere input.