1. Formål

Formålet med dette dokument er at hjælpe udviklere, der skal i gang med at implementere import af en ny datakilde til NSP-platformen.
Dokumentet beskriver det framework og de sammenhænge der omgiver en typisk importer, samt beskriver de generelle krav og muligheder disse giver anledning til.

2. Introduktion

NSP-platformen tilbyder adgang til en række webservices og data med relevans for sundhedsvæsenet – sikret af en ensartet sikkerhedsmekanisme. Yderligere beskrivelse kan finder her: https://www.nspop.dk/display/web/Platformsintroduktion.
En væsentlig del af denne platform tilbydes af Stamdata modulet (SDM) der giver adgang til en række nationale registre, som f.eks. CPR-registret og autorisationsregisteret. Adgang til enkelte registre gives via specifikke webservices (CPR- og autorisations-registeret er eksempler på dette), mens adgang til andre registre tilbydes via en generisk Stamdata Kopiregister service (SKRS).
For hver datakilde er der implementeret en specifik importer, som parser og gemmer data – og er ansvarlig for "tilmelding", så data bliver tilgængelige vis SKRS. Dokumentet her beskriver netop en sådan importer.
NSP-platformen afvikles på flere forskellige JBoss-instanser. Det er derfor et krav, at en importer kan køre på JBoss7 eller Jboss 8 (wildfly) efter aftale med operatøren.

Forløb

Det overordnede program flow der gennemføres i SDM er følgende:

• Kildedata modtages fra ekstern leverandør via en transportkanal ved enten at afvente at data leveres (typisk via SFTP,hvilket er det foretrukne) eller ved at der sendes en forespørgsel til leverandøren i et fast interval.
• Den relevante importer scanner hyppigt filsystemet for nye data og igangsætter en parser, som parser og persisterer de modtagne data i MySql. Importeren implementeres ved hjælp af importerframeworket, som dels håndterer kontrol flow (dvs. styrer hvornår den specifikke parser skal kaldes), dels stiller et API til rådighed for bl.a. persistering.
• De persisterede data replikeres herefter ud til alle NSP-platforme – centrale og decentrale – og er herefter tilgængelige for udtræk – typisk via SKRS. Dette kræver dels at de relevante tabeller er tilmeldt replikeringsmekanismen, dels at SKRS ved hjælp af en konfiguration i MySql har fået fortalt, hvorledes data kan oversættes fra de specifikke tabeller til det generiske format i SKRS.

3. Relaterede komponenter

En importer står ikke alene, men indgår som del af NSP-infrastrukturen - i samarbejde med en række andre elementer. De vigtigste "samarbejdspartnere" er nævnt nedenfor:

SDM4-core framework

sdm4-core styrer det overordnede kontrolflow i import processen og stiller et API til rådighed for parseren (primært til persistering). Dette API skal benyttes, med mindre der kan angives gode grunde til andet (som i givet fald bør fremgå af dokumentation).
Frameworket indeholder bla. Parser interfacet der skal implementeres af importeren. Frameworket sørger for at parseren instantieres og kaldes når der kommer nye datafiler til import.
Frameworket (og flertallet af importerne) vedligeholdes pt af Trifork. Nyeste version kan findes under https://svn.nspop.dk/svn/public/components/sdm4-core/ (benyt nyeste navngivne version).
Udviklerguiden kan specielt være nyttig at læse: https://svn.nspop.dk/svn/public/components/sdm4-core/latest/doc/Guide%20til%20Udviklere.docx.

Bemærk at spring frameworket benyttes, så et beskedent kendskab til dette, kan være nyttigt.

SDM4-parent

Alle importere skal bygges ved hjælp af maven. Importerens pom-fil arver fra sdm4-parent, som hjælper med afhængighedsstyring og stiller diverse build-relaterede features til rådighed, f.eks. licens check og code coverage. Parent-projektet håndterer endvidere muligheden for i forbindelse med idriftsætning at overskrive importerens konfiguration med værdier relevante for det konkrete miljø.

Endelig tilbyder parent projektet mulighed for deployment og afvikling af integrationstests op mod et lokalt virtuelt miljø - implementeret ved hjælp af Vagrant, som er en scriptet konfiguration af en Virtual-Box VM.

sdm4-parent vedligeholdes pt. af Trifork. Nyeste version kan findes under https://svn.nspop.dk/svn/public/components/sdm4-parent/ (benyt nyeste navngivne version).

NSP-util

Dette er et hjælpe modul til SLA logning.
SLA loggen anvendes til overvågning af komponenter på NSP-platformen og rummer typisk information om opstart/nedlukning af en komponent samt kald udefra.Loggen skal overholde et bestemt format, som pt. dikteres af NSP-Util.
Import moduler bliver automatisk SLA logget mht. at synliggøre status af import jobbet. For importere omfatter SLA loggen typisk opstart og resultat af jobudførelse, herunder f.eks. antal gemte records.
Vedligeholdes af Trifork. Nyeste version kan findes under https://svn.nspop.dk/svn/public/components/nsp-util/. Den anvendte version af sdm4-parent bestemmer hvilken version der anvendes.

3.1. Replikering

De persisterede data replikeres af MySql rundt til de forskellige centrale og decentrale NSP-instanser. Herved sikres at de samme data er tilgængelige overalt (efter en beskeden forsinkelse), uanset om der kaldes fra et lægepraksissystem (benytter typisk central NSP), eller fra et EPJ på et hospital (benytter typisk en decentral, regional NSP).

3.2. SKRS (Stamdata kopi register service)

SKRS står for " Stamdata Kopi Register Service". Denne service giver mulighed for at hente komplette kopier af stamdata-registre. Dette giver anvendere mulighed for at ajourføre en lokal kopi af et stamdata-register. Adgangen er begrænset af den aftale der indgås med NSP-operatøren.
Yderligere beskrivelse kan findes her: https://www.nspop.dk/display/web/SKRS+-+Stamdata+Kopi+Register+Service.
Anvendes ikke direkte af importeren. I stedet gemmes Meta-data i MySql som beskriver for SKRS hvorledes registerets data kan udtrækkes.

SKRS anvendes som et feed, der giver anvender mulighed for at hente opdaterede værdier.

Husregler

På siden https://www.nspop.dk/display/web/Husregler findes en liste af krav/regler som generelt skal overholdes ved udvikling af moduler til SDS platformen. Krav beskrevet i dette dokument kan overstyre eller udvide krav beskrevet i husreglerne.

4. Opsætning af importer projekt

4.1. Template importer

Der findes et lille template importer projekt, som illustrerer væsentlige aspekter ved konstruktion af en ny importer og kan findes under https://svn.nspop.dk/svn/nsp/trunk/tools/templateimporter/. Ved oprettelse af en ny importer kan dette projekt kopieres og tilrettes.

Projektet illustrerer dels opsætning af maven, samt illustrerer typisk konfiguration og kode.

4.2. Maven opsætning

En importer bygges ved hjælp af Maven. Projektets pom.xml vil typisk have nedenstående form:

<?xml version="1.0" encoding="UTF-8"?> 
<project xmlns...> 
 <modelVersion>4.0.0</modelVersion> 
 <parent> 
  <groupId>dk.nsi.stamdata4</groupId> 
  <artifactId>sdm-parent</artifactId> 
  <version>4.12</version> 
 </parent> 
 <artifactId>myimporter</artifactId> 
 <packaging>war</packaging> 
 <version>4.1</version> 
 
 <repositories> 
  <repository> 
   <id>nsp-nexus</id> 
   <name>NSP repository</name> 
   <url>https://nexus.nspop.dk/nexus/content/groups/public/</url>
  </repository> 
 </repositories> 
 
 <dependencies> 
  <dependency> 
   <groupId>dk.nsi.stamdata4</groupId> 
   <artifactId>sdm-core</artifactId> 
   <version>4.19</version> 
  </dependency> 
  <dependency> 
   <groupId>dk.sdsd.nsp</groupId> 
   <artifactId>nsp-util</artifactId> 
  </dependency> 
  <dependency> 
   <groupId>dk.nsi.stamdata4</groupId> 
   <artifactId>testutils</artifactId> 
   <version>4.7</version> 
   <scope>test</scope> 
  </dependency> 
  <dependency> 
   <groupId>org.springframework</groupId> 
   <artifactId>spring-webmvc</artifactId> 
  </dependency> 
  ... 
 </dependencies> 
</project>

Bemærk at projektet arver fra sdm-parent og benytter sdm-core mm.

4.3. Opsætning af parser

Stamdata importer frameworket er implementeret som en spring-container og deployet som en web-applikation.
Opsætningen sker programmatisk ved hjælp af en konfigurationsklasse der definerer hvilke beans der indgår i denne. Nogle beans leveres af frameworket, mens andre defineres af den konkrete importer.

@Configuration 
@EnableScheduling 
@EnableTransactionManagement 
public class MyImporterConfig extends StamdataConfiguration { 
  @Bean 
  public SLALogger slaLogger() { 
    return new SLALogConfig("My importer", "myimporter").getSLALogger(); 
  } 
 
  @Bean 
  public Parser parser() { 
    return new MyImporterParser(); // den importer-specifikke parserklasse 
  } 
}

hvor MyImporterParser er den konkrete implementation af parser logikken. Denne har til formål at parse input filerne og så vidt muligt persistere dem i MySql.

public class MyImporterParser implements dk.nsi.sdm4.core.parser.Parser { 
  @Override 
  public void process(File dataSet, String identifier) { 
    try { 
      … 
    } catch (Exception e) { 
      // exceptions håndteres af frameworket 
      throw new RuntimeException(e); 
    } 
  } 
 
  @Override 
  public String getHome() { 
    return "myimporter"; 
  } 
}

Der findes kun 2 håndtag på interfacet, metoden "process" skal udføre konvertering af data og gemme resultatet i databasen, metoden "getHome" returnerer en tekst streng der angiver et sigende navn for import komponenten. Navnet anvendes af frameworket til eks. logning, opdatere status, m.m.

Opsætning af overvågning

Udover konfiguration af parseren er det nødvendigt at opsætte overvågning, så det er muligt for driften at monitorere om importeren fungerer.
Importerframeworket har indbygget en StatusReporter som benyttes til dette formål:

@Configuration 
@EnableWebMvc 
public class WebConfig { 
  @Bean 
  public StatusReporter statusReporter() { 
    return new StatusReporter(); 
  } 
}

Spring sørger nu for at klassen svarer på forespørgsler på denne adresse: http://<ip:8080>/<myimporter>/status/
StatusReporteren har indbygget mulighed for at checke at webapplikationen kører, at der er forbindelse til MySql, og at jobbet ikke er suspenderet grundet tidligere fejl. StatusReporteren returnerer HTTP statuskode 200 når alt fungerer, og HTTP statuskode 500 når noget er galt.

Såfremt status-siden fortæller at noget er galt, kan SLA-loggen og applikationsloggen efterfølgende benyttes til fejlsøgning.

Deployment som web applikation.

Importeren deployes som en webapplikation. Den typiske web.xml vil have nedenstående udseende:

<?xml version="1.0" encoding="UTF-8"?> 
<web-app ...> 
 <context-param> 
  <param-name>contextClass</param-name> 
  <param-value>org.springframework.web.context.support.AnnotationConfigWebApplicationContext</param-value> 
 </context-param> 
 <context-param> 
  <param-name>contextConfigLocation</param-name> 
  <param-value>dk.nsi.sdm4.myimporter.config</param-value> 
 </context-param> 
 
 <listener> 
  <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> 
 </listener> 
 
 <servlet> 
  <servlet-name>appServlet</servlet-name> 
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> 
  <init-param> 
   <param-name>contextConfigLocation</param-name> 
  </init-param> 
  <load-on-startup>1</load-on-startup> 
 </servlet> 
 <servlet-mapping> 
  <servlet-name>appServlet</servlet-name> 
  <url-pattern>/</url-pattern> 
 </servlet-mapping> 
</web-app>

Hvor dk.nsi.sdm4.myimporter.config er den pakke som indeholder MyImporterConfig og WebConfig.

5. Implementation af parser

5.1. SDM flow

Importeren kører skeduleret med korte mellemrum (pt hvert sekund).

• Importeren sætter først en start markering (opretter en fil med navnet WORKING). Dette sikrer mod flere samtidige imports af samme data.
• Herefter scannes den tilhørende indbakke for ankomst af nye filer. Ny ankomne filer vil herefter blive processeret hvis de over en periode har uændret størrelse (dvs filoverførsel kan forventes at være afsluttet).
• Nu aktiveres importerens parser, som parser og persisterer data, eventuel med historik. Hvis enkelte felter i en record ikke kan fortolkes (f.eks. ugyldigt cpr nummer), gemmes recorden, og feltet markeres som "unreliable". Parseren kaldes enten med en fil, eller en folder indeholdende et antal filer.
• Hvis importeringen gennemføres uden fejl fjernes start markeringen.

Opstår der fejl fra import modulet (dvs parseren smider en exception) låses import modulet (en fil med navnet LOCKED oprettes) således at fejlen kan analyseres og udbedres. Låsen skal manuelt fjernes (filen LOCKED slettes) igen før import genoptages.
Frameworket er ansvarlig for SLA logning af kørslen samt applikationslogning af fatale fejl. Parseren kan herudover vælge at logge yderligere detaljer i SLA loggen eller applikationsloggen.

5.2. Validering af kildedata

Import modulet skal sikre at kildedata er korrekt. Det kan f.eks. omfatte validering af filnavne og indholdet af filerne. Hvis kildedata modtages opdelt skal det sikres at de kan importeres i den korrekte rækkefølge.
Hvis kildedata er afhængig af allerede indlæste data (inkrementel import) bør tilstedeværelsen af disse kontrolleres.

Valideringen bør endvidere sikre at enkelte felters data har det korrekte format, så de kan mappes korrekt - f.eks. som en dato.

Såfremt kildedata ikke kan valideres, skal dette fremgå af SLA loggen.

5.3. Persistering af data

Modulet sdm4-core indeholder bla. hjælpe klasser til at gemme importerede værdier pr. række, og hjælper samtidig med håndterering af nogle af de SKRS specifikke felter. Se afsnit for definition af SKRS felter.
Anvendelse af disse øger læsbarhed og genbrug af koden. Persistens API'et bør derfor benyttes med mindre der er meget gode grunde til det.

RecordPersister

Klassen "RecordPersister" sikrer at data bliver valideret og gemt.
RecordPersistor er en spring-bean der out-of-the box er opsat af frameworket, og derfor kan anvendes fra importer-specifikke parser klasser.
Denne klasse indsætter/overskriver data, ønskes det at vedligeholde historik af data bør "UpdateExistingRecordPersister" anvendes i stedet.

5.3.1. UpdateExistingRecordPersister

Denne klasse sørger for at eksisterende rækker efterlades som historik, i stedet for at data overskrives.
I forhold til historik anvendes felterne validFrom og validTo til at angive perioden hvor værdierne var gyldige. Ved "opdateringer" markeres den gamle række som invalid (validTo sættes til aktuel tid) og en ny række indsættes med validFrom aktuel tid.
UpdateExistingRecordPersistor er en spring-bean der kan anvendes fra importer-specifikke parser klasser. Den er dog ikke opsat out-of-the-box, og anvendelse kræver derfor at importeren selv opsætter den.

5.3.2. RecordFetcher

Denne klasse sørger for henting af eksisterende records og giver dermed mulighed for at afgøre om nye records skal indsættes, eller eksisterende opdateres.
RecordFetcher er en spring-bean der out-of-the box er opsat af frameworket, og derfor kan anvendes fra importer-specifikke parser klasser.

5.3.3. Record/Field specification

Ved persistering angives en Record (et map af data) der skal persisteres, samt en RecordSpecification som er en tabelbeskrivelse af data.
En RecordSpecification validerer en record inden gemning og består af tabelnavn, samt et antal FieldSpecifications, der hver for sig beskriver en enkelt kolonne i tabellen og består af:

Name            (angiver kolonne navnet i database tabellen)
RecordFieldType (se nedenstående afsnit)
Length          (angiver maksimal tekst længde for tekst felter)
persistField    (true/false, angiver at feltet skal gemmes i databasen)
ignored         (true/false, angiver at feltet ikke tildeles data ved indlæsning)
optional        (true/false, angiver om feltet skal have en værdi eller kan være null)
calculatedField (true/false,angiver om feltet er beregnet)
defaultValue    (object, default værdi feltet skal tildeles ved instans oprettelse)

hvor RecordFieldType er en af typerne ALPHANUMERICAL (tekst), NUMERICAL (heltal), DECIMAL10_3 (decimaltal), DATETIME (dato og tid), DATE (kun dato).

5.3.4. Her et eksempel hvor 4 felter udgør en record.

RecordSpecification myRec = RecordSpecification.createSpecification(
 "tablename", 
 "Id", 
 field("Id", 21, false).calculated(), // primarykey 
 field("Besked", 50, false), 
 field("Tæller", 3, false).numerical(), 
 field("Unreliable", 2000, true).calculated(), 
 field("CreatedDate", 12, false).calculated().datetime() 
);

5.4. Konfiguration

Udover opsætning af parser, SLA logning og overvågning, vil det være nødvendigt at konfigurere importer-frameworket – og muligt at konfigurere parseren.
Frameworket kræver at følgende properties er definerede:

Dette sker ved at placere dem i en property-fil ved navn default-config.properties, som skal være placeret i web-applikationens classpath (f.eks. WEB-INF/classes). Samme property-fil kan af parseren anvendes til diverse konfigurationsstyring. Disses værdier injectes automatisk i parseren ved f.eks. at benytte

@Value("${spooler.cpr.file.pattern.person}") 
private Pattern personFilePattern;

som sikrer at den tilsvarende værdi fra property-filen anvendes (standard feature i spring-framework).

sdm-parent projektet sikrer, at disse properties på deployment tidspunktet kan overskrives af andre værdier. Dette sker ved at hooke importer-komponenten sammen med et JBoss-modul indeholdende filer det kan være relevant for driften at modificere. Disse omfatter

config.properties                  (optionel) indeholder miljøspecifikke værdier, som overskriver default-config.properties)
log4j.properties                   Konfiguration af applikationslogning - typisk en fillog - se templateimporter projektet
nspslalog-myimporter.properties   enabling af SLA logning.
log4j-nspslalog.properties         log4j konfiguration af SLA logning.
module.xml                         deployment descriptor for jboss modulet.	

Det anbefales at vedlægge flest muligt af disse filer til komponenten - man skal dog være opmærksom på at disse betragtes som "eksempler" der i en driftsituation kan blive overskrevet. De vedlagte filer skal ikke pakkes med i war-filen.

Operationelle aspekter

5.5. Transaktions styring

Det skal sikres at data altid er komplette, så der i fejlsituationer stadigvæk hentes konsistente data ved forespørgsler.
Vurderingen af hvorvidt det er hele tabeller eller enkelt rækker der skal være komplette bør ske i samarbejde med NSP operatøren og NSP driftsleverandøren.
Som default udføres en komplet import i en enkelt databasetransaktion.

Historiske data

Hvis data historik er understøttet skal det sikres at en genindlæsning af data kan håndteres uden at ødelægge historikken, uanset om det er en fuld genindlæsning eller en delvis indlæsning.

Håndtering af genindlæsningen kan f.eks. være fuldstændig eller delvis oprydning af data. Her skal det specielt bemærkes at anvendere af kopiregisterservicen benytter ModifiedDate til at identificere ændrede records. ModifiedData bør derfor så vidt muligt være uændret, da det ellers potentielt kan føre til duplikater i anvendernes system.

5.6. Overvågning / Status

Det er et krav at import modulet skal markere om importering af data gik godt eller skidt. Det sker automatisk af importer-frameworket, der fanger en eventuel exception og registrerer den som en fejl i SLA loggen. Kører parseren igennem uden exceptions gemmes blot en success markering i SLA loggen.
Derfor er det vigtigt ikke at behandle exceptions uden at sende dem videre til frameworket.

SLA loggen kommer således kun til at indeholde en markering af om kaldet til metoden "process" gik godt eller skidt.
Frameworket sørger endvidere for at hver kørsel får gemt tidspunktet for start og slut, samt en status for om importen gik godt eller skidt. Derfor er det nødvendigt at der oprettes en tilhørende status tabel som frameworket kan bruge til at gemme status. Se afsnittet "Database Design" for sql script til oprettelse af tabellen.
Da datafilerne kan indeholder store mængder data der skal importeres, er det et krav at der logges et linienummer eller entydig nøgle når der opstår kritiske fejl eller advarsler (Error og Warn).
Når der logges en kritisk fejl (Error) skal stacktrace altid gemmes i loggen.
Bemærk at når importer modulet fejler, så efterlades filen "LOCKED" som skal fjernes igen før modulet atter kan påbegynde import.

Alarmering

SDM aktiverer kun importer modulet når dette er inaktivt og der er nye kildedata klar.
Derfor skal det dokumenteres overfor driften hvis data forventes at komme på faste intervaller/tidspunkter så det bliver muligt at opsætte en form for alarm som driften kan reagere på hvis kildedata udebliver. Værdien af propertyen spooler.max.days.between.runs bør hænge sammen med dette.

5.7. Unreliable

Import af data bør så vidt muligt håndtere mangelfulde data således at det kun er uhåndterbare fejl der forhindrer indlæsningen af kildedata, eller gemning af data i databasen.
Nogle eksempler på håndterbare fejl er; ikke udfyldte værdier, for lang tekst længde, uventet værdi.

Det anbefales kraftigt at benytte unreliable-metoden til dette. Det betyder at hver datatabel bør have en ekstra kolonne "unreliable". Såfremt enkelte felter indeholder en ugyldig værdi, angives dette i unreliable-kolonnen, idet denne indeholder en komma-separeret liste af felter med ugyldige værdier. Et eksempel på dette kan ses i kildekoden til cpr2 importeren https://svn.nspop.dk/svn/public/components/sdm4-cpr2importer/latest/code/.

Hvis et felt markeres som "unreliable" skal det fremgå tydeligt af applikationsloggen med en advarsel. Feltnavn og den ugyldige værdi skal også fremgå.

Såfremt felter markeres som unreliable bør dette fremgå af SLA loggen - f.eks. ved angivelse af antal indlæste records med unreliable data.

Database design

Alle data persisteres i tabeller i MySql. Angives der ikke andet bliver tabeller oprettet med default sortering (latin1_swedish_ci) og tegnsæt (latin1) jf. husreglerne. Er der behov for understøttelse af flere tegn kan tabellen oprettes med utf8 tegnsæt.

Der skal som minimum oprettes 2 tabeller som import modulet skal vedligeholde. En tabel med angivelse af om import af data gik godt eller fejlede og en tabel til at holde data der importeres inklusiv "system" felter som SKRS skal anvende.

5.8. Data tabel inkl. SKRS standard felter

Udover de felter der skal holde de importerede data, skal der oprettes yderligere 5 felter som SKRS bruger til replikering af data.

Nedenstående sql script kan anvendes til at oprette data tabellen, bemærk at der oprettes indekser til støtte for både SKRS og data udsøgning. Det er et krav at der oprettes et indeks til SKRS med felterne PID og modifiedDate.

CREATE TABLE IF NOT EXISTS mydatatable ( 
 PID BIGINT(10) AUTO_INCREMENT NOT NULL AUTO_INCREMENT, 
 validFrom DATETIME NOT NULL, 
 validTo DATETIME NOT NULL, 
 modifiedDate DATETIME NOT NULL,
 ID VARCHAR(4) NOT NULL,
 YEAR INT(4) NOT NULL,
 PLACE INT(2) NOT NULL,
 NAME VARCHAR(255) NOT NULL,
 PRIMARY KEY (PID),
 INDEX (PID, modifiedDate) 
);

Udover SKRS standard felterne skal tabellen indeholde de importer-specifikke felter med forretningsdata.
Herudover bør feltet "Unreliable" tilføjes, såfremt man ønsker at håndtere mangelfulde data på en pæn måde.

5.9. Status for importering

Udover SLA loggen til at holde status på importering, skal der også oprettes en tabel til at holde status for importering. Tabelnavnet sammensættes ved at kalde 'getHome' metoden på Parser interfacet og tilføje teksten "ImportStatus".

Her er et eksempel på oprettelse af tabellen ImportStatus.

CREATE TABLE myimporterImportStatus ( 
 Id BIGINT(15) AUTO_INCREMENT NOT NULL, 
 StartTime DATETIME NOT NULL, 
 EndTime DATETIME, 
 Outcome VARCHAR(20), 
 PRIMARY KEY (ID),
 INDEX (StartTime) 
);

Importer frameworket sørger selv for at vedligeholde status af importeringen og der skal ikke yderligere gøres noget.

5.10. Opsætning af SKRS viewmapping

Data tabeller skal registreres så SKRS kan finde ud af at kopiere dataene.
Det er et krav at data gøres klar til kopiering, som aktiveres af operatør (whitelist).

INSERT IGNORE INTO SKRSViewMapping (register, datatype, version, tableName, createdDate) 
 VALUES ('xfaktor', 'result', 1, 'Xfaktor', NOW()); 
 
Set @ViewId= (SELECT idSKRSViewMapping FROM SKRSViewMapping WHERE register='xfaktor' AND datatype='result' AND version=1;
 
INSERT IGNORE INTO SKRSColumns (viewMap, isPID, tableColumnName, feedColumnName, feedPosition, dataType, maxLength) 
 VALUES 
 (@ViewId, 1, 'PID',           NULL,          0, -5, NULL), 
 (@ViewId, 0, 'ModifiedDate',  NULL,          0, 93, NULL), 
 (@ViewId, 0, 'ValidFrom',     'validFrom',   5, 93, NULL), 
 (@ViewId, 0, 'ValidTo',       'validTo',     6, 93, NULL), 
 (@ViewId, 0, 'Id',            'id',          1,  12, NULL), 
 (@ViewId, 0, 'YEAR',          'year',        2,  4, 4), 
 (@ViewId, 0, 'PLACE',         'place',       3,  4, 2), 
 (@ViewId, 0, 'NAME',          'name',        4,  12, NULL);

Ovenstående mapning sikrer, at SKRS servicen kan kopiere (udsnit af) de importerede data (et hypotetisk register over placeringer i tidligere X-Faktor konkurrencer). En beskrivelse af formatet kan ses i https://svn.nspop.dk/svn/public/components/sdm/latest/doc/Dynamisk%20SKRS.odt.

Mapningen angiver dels hvilken tabel datatypen 'result' fra registeret 'xfaktor' skal hente data fra (nemlig tabellen Xfaktor). Men også hvorledes de enkelte kolonner udvælges (ud fra den kolonne der er markeret som pid-kolonne, samt de krævede data-felter) og præsenteres. Her angives dels navn (feedColumName) og rækkefølge (feedPosiition) i feedet, dels datatype.

Datatypen referer til værdier af java.sql.Type, f.eks. 93 = http://docs.oracle.com/javase/7/docs/api/constant-values.html#java.sql.Types.TIMESTAMP.

5.11. Databasemigrering

Opgradering af databasen sker automatisk ved serverstart, og fungerer på den måde at sql scripts med navne formatet "Vyyyymmdd_hhmm_description.sql" afvikles på databasen. Script filerne placeres under "resources\db\migration" og inkluderes dermed automatisk i den deployede applikation.
Bemærk at sql filerne afvikles i navne orden, og da dato og tid indgår i navnet, kan man styre hvilke scripts der skal afvikles først.
Der oprettes automatisk en versionstabel (db_migrations) til at holde styr på hvilke scripts der er afviklet, så hvert script kun afvikles én gang.

Testability

Dette dokument beskriver hvordan modulet deployes til Jboss: https://svn.nspop.dk/svn/public/components/sdm4-core/latest/doc/Installationsvejledning.docx (afsnit 3.1.3).

NIAB (NSP in abox) bør anvendes til aftestning af modulets funktionalitet. Vejledning til opstilling af Virtuel maskine kan findes her: https://www.nspop.dk/display/web/NSP+In+A+Box . Herved sikres at testen kommer tæt på produktions konfigurationen. Da importerne i drift kører på Jboss 7, bør man anvende den NIAB der hedder NIAB m. Jboss 7.

Der skal leveres datafiler, eller et utility der generer datafiler, til aftestning af modulet. Så vidt det er muligt skal der være mange små datafiler, så det er hurtigt at genteste en specifik kombination.
Testdata bør være produktionslignende, eventuelle forbehold skal belyses. Testdata skal også omfatte historiske data såfremt dette understøttes.

Der skal oprettes unittests, så code coverage procenten opnås (jf. husreglerne 80%), unittest omfatter også "Hul igennem" test på status url.
Inden modulet afleveres til produktion, skal der udføres en integrationstest som omfatter hele forløbet fra kildedata modtages til data er replikeret via SKRS. Kildedata skal kunne sammenholdes med de replikerede data for at fange eventuelle fejl der opstår på tværs af import forløbet.

Release

Relevante filer skal afleveres i NSP projektets SVN repository og NSP Leverandøren informeres.
Leverancen omfatter bla:

• Kildekode, inkl. test.
• Dokumentation af kildedata, herunder leverandør, fil-format og -navne, forventet hyppighed og datamængder.
• Testdata eller scripts til at skabe testdata.
• Øvrig dokumentation.
• Testresultater.

Se husreglerne på denne side for yderligere uddybning: https://www.nspop.dk/display/web/NSP+SVN+anvendelse#NSPSVNanvendelse-2Komponentleverancer 
Specielle features skal dokumenteres:

• Validering og mapning af kildedata ifht. database tabeller, inkl. aggregerede/beregnede værdier.
• (Transaktions)-håndtering af store datamængder.
• Håndtering af fuld / delta opdatering.
• Liste af håndterede fejl (Exceptions) og deres mulige årsag/løsning.