= Import controller - Installations- og driftvejledning
Arosii A/S
v1.4.0, Januar 2014:
Import miljøer tilføjet

== Indledning
import controlleren er en J2EE applikation udviklet til at styre processen omkring afvikling af NSP importers samt test heraf. Dette dokument indholder informationer omkring installationen og opsætning af import controlleren.

=== Begreber
I de følgende afsnit vil disse ord blive anvendt:

Preflight importer :: En NSP importer installeret i et testmiljø. Miljøet er opbygget af et snapshot fra produktion, således at aftestning af importeren er mulig.

Production importer :: En NSP importer installeret i produktionsmiljøet.

Preflight tester :: Et program der kan teste om stamdata er sammenhængende og korrekt.

Inbox :: Et bibliotek i det lokale filsystem hvor import filer læses fra og skrives til.

Controller inbox :: Bibliotek hvor nye import filer skal placeres for at import controlleren behandler dem.

Importer inbox :: Bibliotek der er konfigureret i en tilhørende NSP importer således at denne behandler filer som placeres her af import controlleren.

Tester inbox :: Bibliotek der er konfigureret i en tilhørende NSP preflight tester således at denne kan startes af *import controlleren*.

Import definition :: En samling af én *controller inbox*, én *preflight importer inbox* samt én *production importer inbox*. De to *preflight importer inboxes* skal tilhøre to instancer af den samme NSP importer (f.eks. to CPR importere)

Tester definition :: Indeholder en *tester inbox* og konfigurationen af afhængigheder til andre tests samt information om en fejlet kørsel af testen skal resultere i en advarsel eller afbrydelse af *import controlleren*

Import controller :: En til flere *import definitions* og *test definitions* samles i en *import controller*. Controlleren styrer og validerer afviklingen af NSP importerne samt de efterfølgende tests.

Import environment :: En til flere *import controllers* samles i et *import environment*. *Import controllers* der deler database bør være i det samme *import environment* da de heri vil blive afviklet sekventielt.

=== Algoritme
En *import controller* monitorer et antal *controller inboxes* og sørger for at guide nye stamdata gennem Preflight setupet på følgende måde:

* Afventer stabilisering af nyt stamdata i *controller inboxes*
* Anmoder databasen på preflight miljøet om at foretage et snapshot
* Kopierer stamdata til *preflight importer inboxes*
* Afventer at alle importere afslutter uden fejl.
* Starter *preflight tests* og afventer positive resultater.
* Kopierer stamdata til *production importer inboxes*
* Afventer at alle importere afslutter uden fejl.
* Fjerner database snapshot igen.

Hvis en importer ikke kan gennemføres, eller hvis en af testene fejler, vil databasen blive rullet tilbage til snapshottet.

image:Importcontroller_sequence.png[Sekvensdiagram for en import controller]

Flere *import definitions* og *test definitions* kan knyttes til den samme *import controller*. Definitionerne knyttet til en controller vil blive afviklet samtidig og testet samlet.

==== Parallelitet
Den skeduleringsmekanisme der findes i import controlleren afvikler hvert *import environment* parallelt, men flere *import controllers* der er knyttet til det samme *import environment* bliver afviklet serielt.

image:Importcontroller_parallelity.png[Afvikling af import controllers parallelt og sekventielt]

==== Stabilisering
For at sikre at de filer der indeholder nye stamdata er fuldstændige inden import controlleren starter, er der lavet en stabiliseringsalgoritme. Algoritmen overvåger alle *controller inboxes* og sikrer at data er stabil i 60 sekunder inden import controlleren starter.

==== Spring over
Det er muligt at bede import controlleren om at springe en eller flere *preflight importers* eller *preflight tests* over. For at springe en preflight importer over placeres der en tom fil med navnet +IMPORTER.SKIP+ i den tilsvarende *controller inbox*. For at springe en preflight test over placeres en tom fil med navnet +TESTER.SKIP+ i den tilhørende *tester inbox*.

Det er også muligt at springe en hel *import definition* over i en controller. Dette gøres ved at placere en tom fil med navnet +CONTROLLER.SKIP+ i den tilsvarende *controller inbox*. Når en *import definition* er sprunget over, vil import controlleren fungere som om definitionen ikke var en del af konfigurationen. Det er ikke tilladt at springe alle *import definitions* over i en controller.

[id="locked"]
==== Låsning
Hvis import controlleren detekterer en fejl ifm. behandlingen af stamdata, opretter den en fil med navnet +LOCKED+ under alle dens *controller inboxes*. Import controlleren vil først starte behandling af ny stamdata når disse filer er slettede.

Hvis der sker en fejl i selve import controlleren låses alle controllere via memory og JBoss skal genstartes for at genoptage behandlingen af stamdata.

== Installation

=== Kompilering
Import controlleren leveres gennem NSP's git repository:
----
git clone ssh://git@git.nspop.dk:7999/im/import-controller.git
----
Efter checkout skal projektet bygges med Maven således:
----
mvn install
----
Følgende filer udgør nu leverancen og skal anvendes i resten af installationsvejledningen:
----
import-controller/target/import-controller-x.y.z.war
import-controller/etc/importcontroller/config.xml
import-controller/etc/importcontroller/importers.xml
import-controller/etc/importcontroller/testers.xml
import-controller/etc/importcontroller/controllers.xml
import-controller/etc/importcontroller/environments.xml
import-controller/etc/importcontroller/schedule.xml
import-controller/etc/log4j-importcontroller.xml
import-controller/etc/log4j-nspslalog-importcontroller.properties
import-controller/etc/nspslalog-importcontroller.properties
----

=== Konfiguration
Inden import controlleren kan deployes skal konfigurationesfilerne kopieres over i biblioteket +/pack/jboss7/standalone/configuration+. Følgende filer skal herefter findes:
----
/pack/jboss7/standalone/configuration/importcontroller/config.xml
/pack/jboss7/standalone/configuration/importcontroller/importers.xml
/pack/jboss7/standalone/configuration/importcontroller/testers.xml
/pack/jboss7/standalone/configuration/importcontroller/controllers.xml
/pack/jboss7/standalone/configuration/importcontroller/environments.xml
/pack/jboss7/standalone/configuration/importcontroller/schedule.xml
/pack/jboss7/standalone/configuration/log4j-importcontroller.xml
/pack/jboss7/standalone/configuration/log4j-nspslalog-importcontroller.properties
/pack/jboss7/standalone/configuration/nspslalog-importcontroller.properties
----

XML filerne under +importcontroller+ biblioteket indeholde et eksempel på en opsætning af 2 import controllere. Disse eksempler skal slettes og korrekte import controllere skal konfigureres *inden* selve applikationen deployes. En detaljeret gennemgang af filerne og opsætningen heri kan findes i afsnittet Opsætning.

=== Deployment
Ligesom NSP importerne så skal import controlleren deployes til en JBoss 7 applikationesserver. Filen +import-controller/target/import-controller-x.y.z.war+ kopieres til +/pack/jboss7/standalone/deployments/importcontroller.war+ *efter* alle konfigurationsfilerne er opdaterede.

[id="setup"]
== Opsætning
Inden import controller applikationen kan deployes skal *import definitions*, *test definitions*, og *import controllers* defineres i konfigurationsfilerne.

=== Konfigurationsfiler
De forskellige konfigurationsfiler indeholder hver en delmængde af de beskrevne opsætningsbegreber. Fordelingen kan ses i nedenstående oversigt:

image:Importcontroller_files.png[Oversigt over konfigurationsfiler]

De 5 nævnte filer skal alle udfyldes af driftsorganisationen således at import controlleren er konfigureret korrekt. Ud over de nævnte filer findes der en +config.xml+ fil der binder de andre filer sammen. Denne fil skal ikke redigeres.

=== importers.xml
I denne fil kombineres *controller inboxes*, *preflight importer inboxes* og *production importer inboxes* til *import definitions*. En *inbox* kan kun knyttes til en enkelt *import definition*. Det anbefales at der defineres en *import definition* for alle NSP importere.

[source,xml]
----
<bean id="abc_importer_controller_inbox"
      class="dk.nsi.sdm4.controller.io.ControllerInboxImpl">
	<constructor-arg value="/pack/jboss/domain/data/importcontroller/abcimporter" />
</bean>
<bean id="abc_importer_preflight_inbox"
      class="dk.nsi.sdm4.controller.io.ImporterInboxImpl">
	<constructor-arg value="/pack/jboss/domain/data/sdm4/abcimporter" />
</bean>
<bean id="abc_importer_production_inbox"
      class="dk.nsi.sdm4.controller.io.ImporterInboxImpl">
	<constructor-arg value="/pack/jboss/domain/data/target/abcimporter" />
</bean>
<bean id="abc_importer" class="dk.nsi.sdm4.controller.impl.ImportDefinitionImpl">
	<property name="name" value="ABC Importer" />
	<property name="controllerInbox" ref="abc_importer_controller_inbox" />
	<property name="importerInbox" ref="abc_importer_preflight_inbox" />
	<property name="productionInbox" ref="abc_importer_production_inbox" />
</bean>
----

Værdien af *import definition* attributten +name+ anvendes ifm. logning og bør vælges således.
De paths der gives til de forskellige inboxes kan være delt med NFS over netværket, hvilket betyder at selve NSP importerne kan være deployet på en seperat node.

=== testers.xml
I denne fil defineres *preflight tests* og *test definitions*.

[source,xml]
----
<bean id="some_tester_inbox" class="dk.nsi.sdm4.controller.io.TesterInboxImpl">
	<constructor-arg value="/pack/jboss/domain/data/test/some-db-test"/>
</bean>

<bean id="some_tester" class="dk.nsi.sdm4.controller.impl.TestDefinitionImpl">
	<property name="name" value="Some tester"/>
	<property name="testerInbox" ref="some_tester_inbox"/>
	<property name="severity" value="ERROR"/><!-- WARN/ERROR -->
	<property name="dependencies">
		<util:list>
			<ref bean="some_other_test"/>
		</util:list>
	</property>
</bean>
----

De paths der gives til de forskellige inboxes kan være delt med NFS over netværket, hvilket betyder at selve preflight testen kan være deployet på en seperat node.

Hvis en *test definition* har +severity+ sat til +WARN+ istedet for +ERROR+ vil import controlleren ikke stoppe et import selv om testen fejler. Fejlen vil blot blive logget. Hvis en test først giver mening at køre efter en anden test er udført, kan dette angives i +dependencies+. Vær opmærksom på ikke at få lavet cykliske afhængigheder i definitionerne.

=== controllers.xml
I denne fil samles en til flere *import definitions* og *test definitions* i en *import controller*. En *import definition* og en *test definition* kan kun knyttes til en enkel *import controller*.

[source,xml]
----
<bean id="abc_import_controller" class="dk.nsi.sdm4.controller.impl.ImportControllerImpl">
	<property name="name" value="Preflight ABC and XYZ importer controller" />
	<property name="importDefinitions">
		<util:list>
			<ref bean="abc_importer" />
			<ref bean="def_importer" />
		</util:list>
	</property>
	<property name="testDefinitions">
		<util:list>
			<ref bean="some_tester"/>
		</util:list>
	</property>
	<property name="createSnapshotCommand" value="createdbsnapshot.sh"/>
	<property name="rollbackSnapshotCommand" value="rollbackdbsnapshot.sh"/>
	<property name="removeSnapshotCommand" value="removedbsnapshot.sh"/>
</bean>
----

Værdien af *import controller* attributten +name+ anvendes ifm. logning og bør vælges således.
Når import controlleren kalder de konfigurerede snapshot kommandoer, vil de få tilføjet en unik streng efter sig der identificere den specifikke kørsel.

=== environments.xml
I denne fil samles en til flere *import controllers* i et import environment*. En *import controller* må kun tilhøre et enkelt *import environment*.

[source,xml]
----
<bean id="abc_environment" class="dk.nsi.sdm4.controller.impl.ImportEnvironmentImpl">
	<property name="importControllers">
		<util:list>
			<ref bean="abc_import_controller" />
			<ref bean="def_import_controller" />
		</util:list>
	</property>
</bean>
----

=== schedule.xml
I denne fil styres hvilke *import environments* der er aktive. Et *import environment* aktiveres ved at tilføje en linie under +task:scheduled-tasks+ ligesom der i følgende eksempel er for +abc_environment+ og +def_environment+.

[source,xml]
----
<task:scheduled-tasks scheduler="scheduler">
	<task:scheduled ref="abc_environment" method="update" fixed-delay="1000"/>
	<task:scheduled ref="def_environment" method="update" fixed-delay="1000"/>
</task:scheduled-tasks>

<task:scheduler id="scheduler" pool-size="10"/>
----

== Logning

=== Status
Hver enkelt *import controller* logger sin tilstand ind i et fælles status modul. Følgende er en liste over disse beskeder og hvad de betyder:

Controller inbox locked :: En *controller inbox* er låst. En *inbox* kan være låst af driftsorganisationen eller fordi der er sket en fejl. Når alle fejl er udbedret slettes filen +LOCKED+.
All controller inboxes skipped :: Alle *controller inboxes* blev sprunget over.
Preflight importer inbox locked :: Preflight importeren har tidligere fejlet og er låst for opdateringer. Se i dokumentationen for importeren.
Preflight importer inbox not empty :: Inden en import controller starer behandling af nye stamdata skal *preflight importer inbox* være tom.
Production importer inbox locked :: Produktion importeren har tidligere fejlet og er låst for opdateringer. Se i dokumentationen for importeren.
Production importer inbox not empty :: Inden en import controller starer behandling af nye stamdata skal *production importer inbox* være tom.
Controller inboxes waiting for stabilization :: Der blev fundet nye stamdata og import controlleren afventer at disse stabiliserer sig selv så alt data er klar.
Controller inboxes empty :: Der blev ikke fundet nogle nye stamdata.
Import entries found :: Der blev fundet nye stamdata, import controlleren vil påbegynde import processen.
Controller inbox skipped :: Import controlleren har sprunget denne controller inbox over.
Creating database snapshot :: Import controlleren har anmodet preflight databasen om at tage et snapshot.
Database snapshot created :: Snapshot oprettet på preflight databasen.
Could not create database snapshot :: Der skete en fejl under oprettelsen af database snapshot. *Controller inbox* er nu låst.
Skipping Preflight importer :: De nye stamdata vil ikke blive givet til denne preflight importer, istedet springes importeren over.
Waiting for Preflight importer to complete :: De nye stamdata er givet til denne preflight importer, og import controlleren afventer at importeren bliver færdig.
Preflight importer failed :: Preflight importeren fejlede og har låst dens *preflight importer inbox*. Hvis muligt er preflight databasen rullet tilbage til snapshottet. *Controller inbox* er nu låst.
Preflight importer successfull :: Preflight importeren har gennemført importen af nye stamdata uden fejl.
Preflight importer skipped :: Preflight importeren er sprunget over.
Rolling back database snapshot :: Import controlleren har anmodet preflight databasen om at rulle tilbage til snapshottet.
Database snapshot rolled back :: Preflight databasen er rullet tilbage til snapshottet
Could not roll back database snapshot :: Der skete en fejl under tilbagerulningen af databasen til snapshottet. *Controller inbox* er nu låst.
Waiting for Preflight tester to complete :: Afventer at preflight testen bliver færdig.
Preflight tester skipped :: Preflight testen er sprunget over.
Preflight tester failed :: Preflight testen fejlede. Hvis muligt er preflight databasen rullet tilbage til snapshottet. *Controller inbox* er nu låst.
Continuing after preflight tester failed :: Den fejlende test havde +severity+ niveau +WARN+, og import controlleren fortsætter derfor importet.
Preflight tester successfull :: Preflight testen er blevet gennemført uden fejl.
Waiting for Production importer to complete :: De nye stamdata er givet til denne produktions importer, og import controlleren afventer at importeren bliver færdig.
Production importer failed :: Produktions importeren fejlede og har låst dens *production importer inbox*. Hvis muligt er preflight databasen rullet tilbage til snapshottet. *Controller inbox* er nu låst.
Production importer successfull :: Produktions importeren har gennemført importen af nye stamdata uden fejl.
Removing database snapshot :: Import controlleren har anmodet preflight databasen om at slette det oprettede snapshot.
Database snapshot removed :: Snapshot slettet på preflight databasen.
Could not remove database snapshot :: Der skete en fejl under sletning af database snapshot. *Controller inbox* er nu låst.
Import failed because of an I/O error :: Der kom en fejl fra disken eller NFS systemet som forhindrede import controlleren i at fungere. *Controller inbox* er nu låst og alle import controllere er låst (kræver genstart af JBoss).
Import was interupted :: Der skete en fejl i trådskeduleringen som forhindrede import controlleren i at fungere. *Controller inbox* er nu låst og alle import controllere er låst (kræver genstart af JBoss).
Import failed because of an error :: Der skete en ukendt fejl som forhindrede import controlleren i at fungere. *Controller inbox* er nu låst og alle import controllere er låst (kræver genstart af JBoss).
Import finished successfully :: De nye stamdata der var placeret i de forskellige *controller inboxes* er blevet importeret og testet på preflightmiljøerne og derefter importeret på produktionsmiljøet. Import controlleren har nu slettet stamdataene i *controller inboxes* og er klar til næste opdatering.

Import controlleren logger kun en status hvis den er forskellig fra den sidste status der blev rapporteret. Dette sikrer at loggen ikke oversvømmes med beskeden *Controller inboxes empty* hvert sekund.

[id="web"]
=== Web grænseflade
De sidste 10 kørsler for hver *import controller* kan ses i en webgrænseflade der findes på addressen:
----
http://servername:port/importcontroller/status
----
Et HTTP request mod denne URL vil returnere 200 når import conterolleren er sat korrekt op, og 500 hvis der er sket en fejl der kræver genstart af JBoss.

I det følgende ses et eksempel på en kørsel baseret på den konfiguration der findes i SVN:

----
Completed - Preflight SKS and SOR importer controller (started 2014-01-09 14:26:58) (finished 2014-01-09 15:21:59):

    Import entries found.
        path=/pack/jboss/domain/data/importcontroller/sksimporter/test1
    Import entries found.
        path=/pack/jboss/domain/data/importcontroller/sorimporter/test2
    Creating database snapshot.
    Database snapshot created.
    Waiting for Preflight importer to complete.
        inbox=/pack/jboss/domain/data/sdm4/sksimporter
    Waiting for Preflight importer to complete.
        inbox=/pack/jboss/domain/data/sdm4/sorimporter
    Preflight importer successfull.
        inbox=/pack/jboss/domain/data/sdm4/sksimporter
    Preflight importer successfull.
        inbox=/pack/jboss/domain/data/sdm4/sorimporter
    Waiting for Preflight tester to complete.
        inbox=/pack/jboss/domain/data/test/sdm-skrs-db-test
    Preflight tester successfull.
        inbox=/pack/jboss/domain/data/test/sdm-skrs-db-test
    Waiting for Production importer to complete.
        inbox=/pack/jboss/domain/data/target/sksimporter
    Waiting for Production importer to complete.
        inbox=/pack/jboss/domain/data/target/sorimporter
    Production importer successfull.
        inbox=/pack/jboss/domain/data/target/sksimporter
    Production importer successfull.
        inbox=/pack/jboss/domain/data/target/sorimporter
    Removing database snapshot.
    Database snapshot removed.
    Import finished successfully.
----

----
Waiting - Preflight SKS and SOR importer controller (started 2014-01-09 14:25:45) (finished 2014-01-09 14:25:45):

    Controller inboxes waiting for stabilization.
        SKS Importer=/pack/jboss/domain/data/importcontroller/sksimporter
        SOR Importer=/pack/jboss/domain/data/importcontroller/sorimporter
----

----
Waiting - Preflight SKS and SOR importer controller (started 2014-01-09 13:47:10) (finished 2014-01-09 13:47:10):

    Controller inboxes empty.
        SKS Importer=/pack/jboss/domain/data/importcontroller/sksimporter
        SOR Importer=/pack/jboss/domain/data/importcontroller/sorimporter
----

----
Waiting - Preflight CPR importer controller (started 2014-01-09 13:47:10) (finished 2014-01-09 13:47:10):

    Controller inboxes empty.
        CPR Importer=/pack/jboss/domain/data/importcontroller/cprimporter        
----

Import controlleren +Preflight SKS and SOR importer controller+ har tre import logs. Første log viser at der endnu ikke er noget at lave for import controlleren. Den næste log fortæller at der er fundet nye stamdata og import controlleren afventer at disse bliver stabile. Den sidste log viser et komplet gennemløb uden fejl.

Det første ord i en import log kan være en af følgende:

In progress :: Import controlleren er stadig igang med denne kørsel.
Waiting :: Import controlleren er færdig med sin gennemkørsel og der var ikke noget at foretage sig lige nu.
Completed :: Import controlleren har kørt hele import forløbet til ende uden fejl.
Failed :: Der skete en fejl under en kørsel.

=== Log filer
Import controlleren skriver til 2 forskellige log filer:

importcontroller.log :: Standard log fil konfigureret i +log4j-importcontroller.xml+.

importcontroller-audit.log :: JSON baseret Audit logning der kan parses af Splunk.